From jim.fulton@digicool.com Mon Aug 5 20:58:26 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Mon, 05 Aug 1996 15:58:26 -0400 Subject: [PYTHON DOC-SIG] Structured Text Module Message-ID: <32065262.3BB9@digicool.com> Hi, Some time ago I told some folks about a module I have for converting structured text to HTML. I suggested that this would be useful when generating documentation for python modules. Well, I'm finally getting around to releasing it. To find out about the structured text module, see: http://www.digicool.com/jim/python/StructuredText.html Or you can get the module itself at: http://www.digicool.com/jim/python/StructuredText.py I wrote this while working on my own module documentation tool, module2html: http://www.digicool.com/jim/python/module2html.py I'm releasing this both as an example of using StructuredText and as a source of ideas for improving gendoc. Some ideas perhaps worth borrowing: - A first cut at supporting built-in types. This is not much use without my meta-type module or MESS. - Use of meta-data alone. No parsing of python code is done. This is important if we want to document built-in modules. And I do. - Use of structured text to provide pretty rich text formatting capabilities while keeping the text readable. Jim -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Mon Aug 5 21:14:46 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Mon, 05 Aug 1996 16:14:46 -0400 Subject: [PYTHON DOC-SIG] Re: Setext followup (Re: Automatic Documentation) References: <199607301616.LAA25994@darwin.rsoc.rockwell.com> Message-ID: <32065636.77B@digicool.com> Robin Friedrich wrote: > > Before we get started let me comment that setext isn't our idea but > rather an adoption of an existing protocol to accomplish what we > thought was a common goal. Namely, to come up with a lightweight, > unobtusive markup standard which could be used in python doc strings. > They would be sufficient to allow automatic documentation tools to > generate nice output in several common documentation formats. > The setext protocol originated with Tony Sanders several years ago. > See http://www.BSDI.COM/setext/ > > |> From tibbs@geog.gla.ac.uk Tue Jul 30 06:38 CDT 1996 > |> X-Mailer: exmh version 1.6.7 5/3/96 > |> To: Robin Friedrich > |> From: Tony J Ibbs (Tibs) > |> Reply-To: gaga50@udcf.gla.ac.uk > |> Subject: Re: Setext followup (Re: Automatic Documentation) > |> Mime-Version: 1.0 > |> Date: Tue, 30 Jul 96 12:39:07 +0100 > |> Sender: tibbs@geog.gla.ac.uk > |> X-Mts: smtp > |> > |> Well, whilst I'm glad to see this is being worked on, I do have a couple of > |> comments. > |> > |> Doing this backwards, firstly, comments on the proposed typotags. > |> > |> Don't forget that people will want to do more complex lists than you > |> seem to be coping with at the moment. > |> > |> For instance: > |> > |> This is an initial list: > |> > |> o first item > |> o second item > |> o third item is a sublist > |> - which contains > |> - two things > |> o last item > |> > |> and if that doesn't work, we need another list > |> > |> o of which this is the first item > |> o and this is the second item > |> > |> and this is its second paragraph > |> > |> This is a comment from experience of doing something similar within the company > |> that pays me - we don't support the sublist or the multuple paragraphs in a list, or > |> the two lists in one documentation, and all of these are fairly horrible restrictions. > > This can be added in the future without difficulty. Hm. With setext? > Although I don't expect > doc strings to get that elaborate. doc strings aren't intended to replace > a formal users guide in the case of complicated applications. I disagree. I'd rather write my documentation in my module, so that I only have *one* source. > |> > |> So - the motto is, one needs to (a) say "start a list" and (b) say "end a list" > |> to have proper support. > > OK please propose something specific. See my StructuredText module. Note that with StructuredText, no extra markup is needed. Rather, indentation indicates structure, as is most natural for humans ans computers alike. > |> > |> You don't say how all those funny characters get inserted into the text when you want > |> them (and not their tag meaning). And this will lead to > |> problems with people forgetting whatever escape sequence/mechanism you choose. > > The typotags have fairly rigid regular expressions and I feel it's unlikely > that they get confused. I've been using them for several weeks and it hasn't > been a difficulty at all. Time will help in refining the regex patterns. > > |> > |> OK - that was the first point - that the system you propose is not complex enough (and > |> that's a response on almost no thought). > > Something complex is exactly what we didn't want. I want to encourage > people to use these tags. The best way of doing that is make it very easy and > logical, otherwise people won't bother to use it. > > |> > |> My second point is actually to argue against this exact approach - this is > |> unfortunately presumably repeating an argument in the SIG (which I was sure I > |> had signed up to ages ago - obviously not, which explains why it has been so > |> silent). I would strongly suggest that you are not going to come up > |> with solutions for all the formatting that users want, and sometimes need. > > So. That's not the intent. What's the harm in having a simple, workable system > now? I think we can have our cake and eat it too. Fairly complex formatting *can* be achieved with simple human readable ascii source. > |> It is also very likely, with an adhoc design like this, that one will "paint onself > > |> into a corner" in some way - the obvious example of this is if it is > |> decided later that a new typotag is needed, but, oh dear, choosing any new character > > |> will break existing doc strings. (this actually ties in with the comments on the main > |> list recently, saying essentially "I'm not terribly keen on X, Y or Z in Python, but > |> when I try to work round it, I get trouble - gosh, language design is difficult, and > |> Guido is clever"). Designing a new markup language (which is what you are doing) > |> is difficult. Designing one that can be future proof is even harde > |> > > As the preamble states this is not an ad hoc design. And extending the typotags > in the future shouldn't be an issue. I see no reason why adding a new format > would break anything. Doc strings don't break, they just may not pick up > correctly in the autogeneration tool(s) that's all. The worse thing I've > seen so far is that setext wasn't marked as expected, but that's hardly a > crisis and is easily fixed. > > |> When the company that pays me was designing its documentation comments, we were using > |> TeX for documentation. I stronly argued that we should use TeX commands as the markup, > |> rather than trying to grow our own - after all, there was a lot more experience in > |> there. I lost then. > |> > |> Nowadays, I would recommend HTML - it is simpler than Tex (and how!), easier to use, > |> easier to `read' when looking at source code, and browsers are easier to maintain than > |> TeX. The "everywhereness" of HTML means that most programmers will have written it > |> (especially with so many Python apps seeming to be net related these days!). The only > |> change I might make would be to allow blank lines to signify "

" - ie, new paragraph > |> - since this seems reasonably intuitive - but I can argue against tha > > Setext grew out of the need to avoid the ugliness of HTML. I maintain that > HTML markup is too verbose for doc strings, and clutters the reading of them > in code. Especially for hyperlinks. I found the reference approach setext a > far sight better that placing junk like this in HREF="http://www.python.org/sigs/doc-sig/">doc strings. Instead, I can use > doc_strings_ which flow unint > by the http reference. > > .. _doc_strings http://www.python.org/sigs/doc-sig/ It is critical IMHO that doc strings *not* contain explicit markup. They should be easily human readable, while supporting clever auto-markup. > |> > |> And HTML seems to support the right sort of subset of markup - it shouldn't be hard to > |> translate into n/troff, [La]TeX, Digital Runoff, whatever else one wants. Oh, and it > |> copes with URLs just fine. > |> > |> (it also gives you more than one style of list, especially if you use the Netscape > |> "type" extension). > |> > |> Is it harder to read than the setext proposal? Obviously a matter of opinion (ref the > |> arguments about indentation in Python!) - but many of the setext things are arbitrary > |> anyway (why not use "*" for `emphasis', not "**"? that would fit with the normal > |> email/ASCII convention? - oh, one can use "@" or something for lists if one must). And > |> you only give bold or italic - why not give us "emphasis" which is presented in a > |> device independent manner? I'm not wild about setext myself. > OK I will :-) > > In summary I remain unconvinced that any of the above mentioned issues are > problems with using setext in doc strings. I agree Jim -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Mon Aug 5 21:42:03 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Mon, 05 Aug 1996 16:42:03 -0400 Subject: [PYTHON DOC-SIG] setext in doc strings References: <199607232021.PAA15986@darwin.rsoc.rockwell.com> Message-ID: <32065C9B.4E52@digicool.com> Robin Friedrich wrote: > > I've been working with Daniel Larsson on gendoc. Currently there is a > little setext parser built into gendoc which identifies text structure > and stores the components in a metadocument which can be rendered in a > number of output formats (notably HTML and MML). Since most folks are > not necessary familiar with setext markup I'd like to provide a brief > synopsis. If you use this stuff in your doc strings nice things will > happen to your autogenerated manuals.:-) First, I apologize for the tardiness of my reply. I spent some time looking at setext after the workshop and was fairly underwhelmed. Actually setext document I looked at were sort of ugly in their basic form and example setext converted to html was often broken. I also has a tough time making out the setext documentation, which colored my opinion somewhat. In a separate note, I released a Structured text module that I consider to be superior to setext in several ways: - The sourse text os more readable, - It supports arbitrary levels of nesting, including numbered, bulleted and descriptive lists. - It generates HTML tags like and , rather than and . > SETEXT 101 > ========== > > Below is the setext definitions from the BSDI project. Note that not > all tags are supported (or needed) in python doc strings. This looks like the documentation I found for setext. I had trouble making it out then and have touble making it out now. :-| > > Valid Typotags Table > --------------------- > ____________________ ___________________ _______________ ____________ v14 > current (online) use setext form acted upon or name of > of text emphasis of same displayed as the typotag ? > ==================== =================== =============== ============ === > Internet mail header From Subject: shown subject-tt (a) > (start of a message) minimal mail header [Date: & From:] I assume this doesn't apply to us? > -------------------- ------------------- --------------- ------------ --- > title (1 per text) "Title a title title-tt (b) > in distinct position =====" in chosen style Is gendoc using this? This mechanism of setext is rather restrictive and ugly. > -------------------- ------------------- --------------- ------------ --- > heading (1+/ text) "Subhead a subhead subhead-tt (c) > in distinct position -------" in chosen style Ditto. > -------------------- ------------------- --------------- ------------ --- > body text 66-char lines in- lines undented indent-tt (d) > [plain not-indented] dented by 2 space and unfolded Ditto. > -------------------- ------------------- --------------- ------------ --- > 1+ bold word(s) **[multi]word** 1+ bold word(s) bold-tt (e) *mult word* would be more readable and follows standard conventions. I think emphasis is better than bold. This is what I did in StructuredText. > a single italic word ~word~ 1 italic word italic-tt (f) This looks ugly. Why specify italic directly? Doesn't this run counter to HTML philosophy. If the group wants this, I'd be willing to add it to StructuredText. If I do, what consitutes a 'word'? > 1+ underlined words [_multi]_word_ underlined text underline-tt (g) What consitutes a word? Does this run afoul of multi_word_python_variable_names? > hypertextual 1+ word [multi_]word_ 1+ hot word(s) hot-tt (h) This is weird. Where is the reference? Has this been implemented in gendoc? > >followed by text >[space][text] > [mono-spaced] include-tt (i) This looks like a quoted email message. But I guess it makes sense. > bullet-text in pos1 *[space][text] [bullet] [text] bullet-tt (j) I think 'o text' and '- text' are more readable. > `_quoted typotag!_` `_left alone!_` quote-tt (k) `_e_gads!_` I like 'this much better' > -------------------- ------------------- --------------- ------------ --- > [hypertext link def] ^.. _word URL jump to address href-tt (l) > [hypertext note def] ^.. _word Note:("*") ("cause error") note-tt (m) I have no idea what this means. > -------------------- ------------------- --------------- ------------ --- > end of first? setext $$ [last on a line] [parse another] twobuck-tt (n) > ^..[space][not dot] [line hidden] suppress-tt (o) > logical end of text ^..[alone on a line] [taken note of] twodot-tt (p) Huh? > ==================== =================== =============== ============ === > > Note: only one instance of the element (c) (or, in its absence, (b)) > is absolutely _required_ for a text to be considered a valid setext. > > All the elements but (c) are in effect optional, not necessary for > a setext to be declared as such. Element (a) deals with setexts > that arrive via email and end up being parsed (processed) as > unedited mailbox files; fully employed the (a), (b) and (c) make > it possible to distribute "multisetexts", i.e. setexts with one > additional level of logical structure (= more than one setext per > message; more than one message in a mailbox). If such file is > viewed as a multisetext it will result in 3-level-outline > structure: mail-subjects become top-level chapters, setext titles > denote subchapters (topics) and the subheads yet finer threads > within these (still a notch ABOVE mere "paragraphs of text"). > > $$ > ----------------------------------------------------------------------- > The following doc string example illustrates the usage of all setext > constructs recognized by the gendoc tool. (i think) > > class Setext(Text): > """Lets you change markup to stylize your text > > SETEXT 102 > ========== This is not valid setext. Setext wants the titles and headings to start in column 1 and the other text in column 3, like this: SETEXT 102 ========== **Setext** can be used to mark your text in a non-obtrusive manner. Text within double asterisks are treated as bold, ... > **Setext** can be used to mark your text in a non-obtrusive > manner. Text within double asterisks are treated as bold, > while single words with tilde at the front and back are > rendered as ~Italic~. You can _underline_a_phrase_ but it > will be rendered as bold in HTML. Placing hyperlinks > is easy; just hilite_the_tag_ and at the bottom of the doc > string include the address which it points to on a line by > itself. > > New paragraphs are separated by blank lines. > > And a bunch of literal text > > can be specified with the left > > arrow. This gets marked as 

 in HTML.
>     Otherwise the text will be wrapped according to whatever
>     output formatter is used.
> 
>     A bulleted list is done with single asterisks thusly:
>     * Lettuce
>     * Onions
>     * Pickles
> 
>     Extension to setext
>     -------------------

Ditto.

>     A frequent construct in python doc strings is to list ones
>     keyword arguments. This made us wish for a way to specify
>     a definition list so that it looks nice is html (and others).
>     I propose the following. I have this working in my version.
>     The double colons won't be in the output.
> 
>     item1 :: definition 1
>     item2 :: definition 2
>     item3 :: a rather long and involved definition for item 3
>              spanning more than one line.
>     item4 :: back to brevity with definition 4

Why not:

      item1 -- Definition 1
      ...

This looks much better to me, and works with StructuredText.
 
>     .. _hilite_the_tag http://www.python.org
>     """
> 
> Notes:
> 
> The indenting inserted by python-mode for the entire doc string is
> detected and processed out before setext rules are applied. So
> eventhough titles for example are required to start in column one they
> will if they obey the overall indenting for that doc string.

Hm.
 
> The underlines for the title and subtitle should be the same length as
> the title itself.
> 
> Spaces around tokens are important (for the "* ", "> ", and " :: ")
> 
> Comment are hearby welcome.

I think my structured text module mechanism provides richer 
text formatting with less obtrusive markup, especially for 
strings that have much structure, as many of mine do.

Jim

-- 
Jim Fulton         Digital Creations
jim@digicool.com   540.371.6909
## Python is my favorite language ##
##     http://www.python.org/     ##

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Mon Aug  5 22:42:04 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Mon, 5 Aug 1996 16:42:04 -0500
Subject: [PYTHON DOC-SIG] setext in doc strings
Message-ID: <199608052142.QAA03454@darwin.rsoc.rockwell.com>

|> From: Jim Fulton 
|> 
|> Robin Friedrich wrote:
|> > 

|> I spent some time looking at setext after the workshop and was fairly
|> underwhelmed.  Actually setext document I looked at were sort of ugly
|> in their basic form and example setext converted to html was often
|> broken.
|> I also has a tough time making out the setext documentation, which
|> colored
|> my opinion somewhat.
|> 
|> In a separate note, I released a Structured text module that I consider 
|> to be superior to setext in several ways:

Bummer. I didn't get it. Can you send it again? Be sure it's not >40K if
you send it to a sig list - it won't get forwarded.
|> 
|>   - The sourse text os more readable,

Really?:-)
|>   - It supports arbitrary levels of nesting, including numbered,
|> bulleted
|>     and descriptive lists.

Nice.
|>   - It generates HTML tags like  and , rather than 
|> and
|>     .

Actually, so doesn't gendoc.



|> >  Internet mail header  From         Subject: shown    subject-tt (a)
|> >  (start of a message)  minimal mail header  [Date: & From:]
|> 
|> I assume this doesn't apply to us?

Yes.

|> 
|> >  --------------------  -------------------  --------------- ------------ ---
|> >  title (1 per text)   "Title                a title             title-tt (b)
|> >  in distinct position  ====="               in chosen style
|> 
|> Is gendoc using this?  This mechanism of setext is rather restrictive
|> and ugly.

Yes, I thought so too but not badly so.
|> 
|> >  --------------------  -------------------  --------------- ------------ ---
|> >  heading (1+/ text)   "Subhead              a subhead         subhead-tt (c)
|> >  in distinct position  -------"             in chosen style
|> 
|> Ditto.
|> 
|> >  --------------------  -------------------  --------------- ------------ ---
|> >  body text               66-char lines in-  lines undented     indent-tt (d)
|> >  [plain not-indented]    dented by 2 space  and unfolded
|> 
|> Ditto.

Don't think this one is applied.
|> 
|> >  --------------------  -------------------  --------------- ------------ ---
|> >  1+ bold word(s)           **[multi]word**  1+ bold word(s)      bold-tt (e)
|> 
|> *mult word* would be more readable and follows standard conventions.  I
|> think 
|> emphasis is better than bold.  This is what I did in StructuredText.

The reason I guess was that * was used to indicate a bulleted list.

|> 
|> >  a single italic word               ~word~  1 italic word      italic-tt (f)
|> 
|> This looks ugly.  Why specify italic directly?  Doesn't this run counter
|> to HTML
|> philosophy.

HTML philosopy had nothing to do with setext as far as I can tell.
|> 
|> If the group wants this, I'd be willing to add it to StructuredText.  
|> If I do, what consitutes a 'word'?

A contiguous string of characters.
|> 
|> >  1+ underlined words        [_multi]_word_  underlined text underline-tt (g)
|> 
|> What consitutes a word?  Does this run afoul of
|> multi_word_python_variable_names?

Same. Not really as there has to be both a leading and trailing underscore.
|> 
|> >  hypertextual 1+ word        [multi_]word_  1+ hot word(s)        hot-tt (h)
|> 
|> This is weird.  Where is the reference?  Has this been implemented in
|> gendoc?

Yes. You specify a_hyperlink_ like this and it points to the address spec'd
at the end of the doc string.  It's not obvious from the setext docs. That's 
why I explained it later with examples.

.. _a_hyperlink http://www.python.org/sigs/

|> 
|> >  >followed by text     >[space][text]       > [mono-spaced]   include-tt (i)
|> 
|> This looks like a quoted email message.  But I guess it makes sense.
|> 
|> >  bullet-text in pos1   *[space][text]       [bullet] [text]    bullet-tt (j)
|> 
|> I think 'o text' and '- text' are more readable.
|> 
|> >                        `_quoted typotag!_`  `_left alone!_`     quote-tt (k)
|> 
|> `_e_gads!_`  I like 'this much better'

Don't think this comes up much and it's not necessarily implemented yet.
|> 
|> >  --------------------  -------------------  --------------- ------------ ---
|> >  [hypertext link def] ^.. _word URL         jump to address      href-tt (l)
|> >  [hypertext note def] ^.. _word Note:("*")  ("cause error")      note-tt (m)
|> 
|> I have no idea what this means.
|> 
|> >  --------------------  -------------------  --------------- ------------ ---
|> >  end of first? setext  $$ [last on a line]  [parse another]   twobuck-tt (n)
|> >                       ^..[space][not dot]   [line hidden]    suppress-tt (o)
|> >  logical end of text  ^..[alone on a line]  [taken note of]    twodot-tt (p)
|> 
|> Huh?

Read on McDuff...

...
|> > -----------------------------------------------------------------------
|> > The following doc string example illustrates the usage of all setext
|> > constructs recognized by the gendoc tool. (i think)
|> > 
|> > class Setext(Text):
|> >     """Lets you change markup to stylize your text
|> > 
|> >     SETEXT 102
|> >     ==========
|> 
|> This is not valid setext.  Setext wants the titles and headings to start 
|> in column 1 and the other text in column 3, like this:

Yes but the implementation doesn't enforce that now. headings and body can 
be in column one.  Remember Daniel strips the leading tab/spaces from the 
doc string before applying these rules.

|> 
|> SETEXT 102
|> ==========
|> 
|>   **Setext** can be used to mark your text in a non-obtrusive
|>   manner. Text within double asterisks are treated as bold, ...
|> 
|> >     **Setext** can be used to mark your text in a non-obtrusive
|> >     manner. Text within double asterisks are treated as bold,
|> >     while single words with tilde at the front and back are
|> >     rendered as ~Italic~. You can _underline_a_phrase_ but it
|> >     will be rendered as bold in HTML. Placing hyperlinks
|> >     is easy; just hilite_the_tag_ and at the bottom of the doc
|> >     string include the address which it points to on a line by
|> >     itself.
|> > 
|> >     New paragraphs are separated by blank lines.
|> >     > And a bunch of literal text
|> >     > can be specified with the left
|> >     > arrow. This gets marked as 
 in HTML.
|> >     Otherwise the text will be wrapped according to whatever
|> >     output formatter is used.
|> > 
|> >     A bulleted list is done with single asterisks thusly:
|> >     * Lettuce
|> >     * Onions
|> >     * Pickles
|> > 
|> >     Extension to setext
|> >     -------------------
|> 
|> Ditto.
|> 
|> >     A frequent construct in python doc strings is to list ones
|> >     keyword arguments. This made us wish for a way to specify
|> >     a definition list so that it looks nice is html (and others).
|> >     I propose the following. I have this working in my version.
|> >     The double colons won't be in the output.
|> > 
|> >     item1 :: definition 1
|> >     item2 :: definition 2
|> >     item3 :: a rather long and involved definition for item 3
|> >              spanning more than one line.
|> >     item4 :: back to brevity with definition 4
|> 
|> Why not:
|> 
|>       item1 -- Definition 1
|>       ...
|> 
|> This looks much better to me, and works with StructuredText.

Hey, I just picked it out of the blue. (And I've never seen your
structured text module.) ':-(

|>  
|> >     .. _hilite_the_tag http://www.python.org
|> >     """
|> > 
|> > Notes:
|> > 
|> > The indenting inserted by python-mode for the entire doc string is
|> > detected and processed out before setext rules are applied. So
|> > eventhough titles for example are required to start in column one they
|> > will if they obey the overall indenting for that doc string.
|> 
|> Hm.
|>  
|> > The underlines for the title and subtitle should be the same length as
|> > the title itself.
|> > 
|> > Spaces around tokens are important (for the "* ", "> ", and " :: ")
|> > 
|> > Comment are hearby welcome.
|> 
|> I think my structured text module mechanism provides richer 
|> text formatting with less obtrusive markup, especially for 
|> strings that have much structure, as many of mine do.
|> 
|> Jim

Fine,
Send it to me!!
-Robin

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From jim.fulton@digicool.com  Tue Aug  6 13:26:21 1996
From: jim.fulton@digicool.com (Jim Fulton)
Date: Tue, 06 Aug 1996 08:26:21 -0400
Subject: [PYTHON DOC-SIG] setext in doc strings
References: <199608052142.QAA03454@darwin.rsoc.rockwell.com>
Message-ID: <320739ED.34D6@digicool.com>

Robin Friedrich wrote:
> 
> |> From: Jim Fulton 
> |>
> |> Robin Friedrich wrote:
> |> >
> 
> |> I spent some time looking at setext after the workshop and was fairly
> |> underwhelmed.  Actually setext document I looked at were sort of ugly
> |> in their basic form and example setext converted to html was often
> |> broken.
> |> I also has a tough time making out the setext documentation, which
> |> colored
> |> my opinion somewhat.
> |>
> |> In a separate note, I released a Structured text module that I consider
> |> to be superior to setext in several ways:
> 
> Bummer. I didn't get it. Can you send it again? Be sure it's not >40K if
> you send it to a sig list - it won't get forwarded.

Hm.  It was only a K or so.  I got a copy through the list.  Dod anyone
else
not get the StructuredText note?  Did everyone else get this note?

Robin, I forwarded another copy to you.

> |>
> |>   - The sourse text os more readable,
> 
> Really?:-)

Yes, assuming it is spelled correctly.

> |>   - It supports arbitrary levels of nesting, including numbered,
> |> bulleted
> |>     and descriptive lists.
> 
> Nice.
> |>   - It generates HTML tags like  and , rather than 
> |> and
> |>     .
> 
> Actually, so doesn't gendoc.
> 
> 
> 
> |> >  Internet mail header  From         Subject: shown    subject-tt (a)
> |> >  (start of a message)  minimal mail header  [Date: & From:]
> |>
> |> I assume this doesn't apply to us?
> 
> Yes.
> 
> |>
> |> >  --------------------  -------------------  --------------- ------------ ---
> |> >  title (1 per text)   "Title                a title             title-tt (b)
> |> >  in distinct position  ====="               in chosen style
> |>
> |> Is gendoc using this?  This mechanism of setext is rather restrictive
> |> and ugly.
> 
> Yes, I thought so too but not badly so.
> |>
> |> >  --------------------  -------------------  --------------- ------------ ---
> |> >  heading (1+/ text)   "Subhead              a subhead         subhead-tt (c)
> |> >  in distinct position  -------"             in chosen style
> |>
> |> Ditto.
> |>
> |> >  --------------------  -------------------  --------------- ------------ ---
> |> >  body text               66-char lines in-  lines undented     indent-tt (d)
> |> >  [plain not-indented]    dented by 2 space  and unfolded
> |>
> |> Ditto.
> 
> Don't think this one is applied.
> |>
> |> >  --------------------  -------------------  --------------- ------------ ---
> |> >  1+ bold word(s)           **[multi]word**  1+ bold word(s)      bold-tt (e)
> |>
> |> *mult word* would be more readable and follows standard conventions.  I
> |> think
> |> emphasis is better than bold.  This is what I did in StructuredText.
> 
> The reason I guess was that * was used to indicate a bulleted list.

But it is easy to tell the two apart:

  * this is a bulleted item.  Notice the space after the star and no
"closing" star
 
  But this paragraph *has some emphasized* text. Notice the position of
the * relative
  to whitespace.
 
> |>
> |> >  a single italic word               ~word~  1 italic word      italic-tt (f)
> |>
> |> This looks ugly.  Why specify italic directly?  Doesn't this run counter
> |> to HTML
> |> philosophy.
> 
> HTML philosopy had nothing to do with setext as far as I can tell.

But I would argue that, while python documentation strings should not
be bound by HTML, they should share the philosphy of content, rather
than
presentation-oriented markup.

> |>
> |> If the group wants this, I'd be willing to add it to StructuredText.
> |> If I do, what consitutes a 'word'?
> 
> A contiguous string of characters.

Which characters?  Are there limits?  Are spaces allowed?  What about
single quotes?
I think you need to be more specific.

> |>
> |> >  1+ underlined words        [_multi]_word_  underlined text underline-tt (g)
> |>
> |> What consitutes a word?  Does this run afoul of
> |> multi_word_python_variable_names?
> 
> Same. Not really as there has to be both a leading and trailing underscore.

Uh, you mean, as in __getstate__ or __add__?

> |>
> |> >  hypertextual 1+ word        [multi_]word_  1+ hot word(s)        hot-tt (h)
> |>
> |> This is weird.  Where is the reference?  Has this been implemented in
> |> gendoc?
> 
> Yes. You specify a_hyperlink_ like this and it points to the address spec'd
> at the end of the doc string.  It's not obvious from the setext docs. That's
> why I explained it later with examples.
> 
> .. _a_hyperlink http://www.python.org/sigs/

Hm.  I didn't try to address this in StructuredText.  But there has to
be
a better way.

Something I've done in the past is:

  (See so and so.)

gets translated, in HTML, to:

  (See so and so.)

 
> |>
> |> >  >followed by text     >[space][text]       > [mono-spaced]   include-tt (i)
> |>
> |> This looks like a quoted email message.  But I guess it makes sense.
> |>
> |> >  bullet-text in pos1   *[space][text]       [bullet] [text]    bullet-tt (j)
> |>
> |> I think 'o text' and '- text' are more readable.
> |>
> |> >                        `_quoted typotag!_`  `_left alone!_`     quote-tt (k)
> |>
> |> `_e_gads!_`  I like 'this much better'
> 
> Don't think this comes up much and it's not necessarily implemented yet.

It comes up *all the time* in my doc strings. If I am mentioning 
a function name or argument to a method, I quote it to separate it from
the 
rest of the text.  Ditto if I mention a small snippet of code within
prose.

> |>
> |> >  --------------------  -------------------  --------------- ------------ ---
> |> >  [hypertext link def] ^.. _word URL         jump to address      href-tt (l)
> |> >  [hypertext note def] ^.. _word Note:("*")  ("cause error")      note-tt (m)
> |>
> |> I have no idea what this means.
> |>
> |> >  --------------------  -------------------  --------------- ------------ ---
> |> >  end of first? setext  $$ [last on a line]  [parse another]   twobuck-tt (n)
> |> >                       ^..[space][not dot]   [line hidden]    suppress-tt (o)
> |> >  logical end of text  ^..[alone on a line]  [taken note of]    twodot-tt (p)
> |>
> |> Huh?
> 
> Read on McDuff...

I did.  But I didn't see any new explanation.  I studied the table some
more and
figured out that the ^ must mean the begining of a line.  So let me see
if I've 
got this straight:

  - A line beginning with two dots is a "comment".
  - There are special comments:

     - A line with just two dots is the end of the document.
     - A line beginning with two dots, a space, and an underscore
defines the 
       target of a reference in some fashion.

  - A line ending in two dollar signs defines the end of a document
component.
    But, of course, document components have not been defined.

> ...
> |> > -----------------------------------------------------------------------
> |> > The following doc string example illustrates the usage of all setext
> |> > constructs recognized by the gendoc tool. (i think)
> |> >
> |> > class Setext(Text):
> |> >     """Lets you change markup to stylize your text
> |> >
> |> >     SETEXT 102
> |> >     ==========
> |>
> |> This is not valid setext.  Setext wants the titles and headings to start
> |> in column 1 and the other text in column 3, like this:
> 
> Yes but the implementation doesn't enforce that now. headings and body can
> be in column one.  Remember Daniel strips the leading tab/spaces from the
> doc string before applying these rules.

I saw that below.  But much of the argument for using setext seems to be
that you are leveraging an existing mechanism.  Buy you aren't really. 
You are
borrowing from it the things you like.
 
> |>
> |> SETEXT 102
> |> ==========
> |>
> |>   **Setext** can be used to mark your text in a non-obtrusive
> |>   manner. Text within double asterisks are treated as bold, ...
> |>
> |> >     **Setext** can be used to mark your text in a non-obtrusive
> |> >     manner. Text within double asterisks are treated as bold,
> |> >     while single words with tilde at the front and back are
> |> >     rendered as ~Italic~. You can _underline_a_phrase_ but it
> |> >     will be rendered as bold in HTML. Placing hyperlinks
> |> >     is easy; just hilite_the_tag_ and at the bottom of the doc
> |> >     string include the address which it points to on a line by
> |> >     itself.
> |> >
> |> >     New paragraphs are separated by blank lines.
> |> >     > And a bunch of literal text
> |> >     > can be specified with the left
> |> >     > arrow. This gets marked as 
 in HTML.
> |> >     Otherwise the text will be wrapped according to whatever
> |> >     output formatter is used.
> |> >
> |> >     A bulleted list is done with single asterisks thusly:
> |> >     * Lettuce
> |> >     * Onions
> |> >     * Pickles
> |> >
> |> >     Extension to setext
> |> >     -------------------
> |>
> |> Ditto.
> |>
> |> >     A frequent construct in python doc strings is to list ones
> |> >     keyword arguments. This made us wish for a way to specify
> |> >     a definition list so that it looks nice is html (and others).
> |> >     I propose the following. I have this working in my version.
> |> >     The double colons won't be in the output.
> |> >
> |> >     item1 :: definition 1
> |> >     item2 :: definition 2
> |> >     item3 :: a rather long and involved definition for item 3
> |> >              spanning more than one line.
> |> >     item4 :: back to brevity with definition 4
> |>
> |> Why not:
> |>
> |>       item1 -- Definition 1
> |>       ...
> |>
> |> This looks much better to me, and works with StructuredText.
> 
> Hey, I just picked it out of the blue. (And I've never seen your
> structured text module.) ':-(

Hey, please don't take my note of a criticism of your work.  I'm
just trying to comment on the format.  I apreciate you and Dan moving
this
thing along.

> |>
> |> >     .. _hilite_the_tag http://www.python.org
> |> >     """
> |> >
> |> > Notes:
> |> >
> |> > The indenting inserted by python-mode for the entire doc string is
> |> > detected and processed out before setext rules are applied. So
> |> > eventhough titles for example are required to start in column one they
> |> > will if they obey the overall indenting for that doc string.
> |>
> |> Hm.
> |>
> |> > The underlines for the title and subtitle should be the same length as
> |> > the title itself.
> |> >
> |> > Spaces around tokens are important (for the "* ", "> ", and " :: ")
> |> >
> |> > Comment are hearby welcome.
> |>
> |> I think my structured text module mechanism provides richer
> |> text formatting with less obtrusive markup, especially for
> |> strings that have much structure, as many of mine do.
> |>
> |> Jim
> 
> Fine,
> Send it to me!!

I did.

Jim

-- 
Jim Fulton         Digital Creations
jim@digicool.com   540.371.6909
## Python is my favorite language ##
##     http://www.python.org/     ##

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From dlarsson@sw.seisy.abb.se  Tue Aug  6 16:53:26 1996
From: dlarsson@sw.seisy.abb.se (Daniel Larsson)
Date: Tue, 06 Aug 1996 17:53:26 +0200
Subject: [PYTHON DOC-SIG] setext in doc strings
References: <199608052142.QAA03454@darwin.rsoc.rockwell.com> <320739ED.34D6@digicool.com>
Message-ID: <32076A76.5BBC@sw.seisy.abb.se>

Jim Fulton wrote:
> 
> Robin Friedrich wrote:
> >
> Hm.  It was only a K or so.  I got a copy through the list.  Dod anyone
> else
> not get the StructuredText note?  Did everyone else get this note?
> 
> Robin, I forwarded another copy to you.

Yes, I got it.

> > |>   - It supports arbitrary levels of nesting, including numbered,
> > |> bulleted
> > |>     and descriptive lists.
> >
> > Nice.

I started yesterday to fool around with your module. It will probably be
awhile before I have something to share, but I would really like to use
your stuff, Jim, especially the nested/numbered list stuff.

> > |> *mult word* would be more readable and follows standard conventions.  I
> > |> think
> > |> emphasis is better than bold.  This is what I did in StructuredText.
> >
> > The reason I guess was that * was used to indicate a bulleted list.
> 
> But it is easy to tell the two apart:
> 
>   * this is a bulleted item.  Notice the space after the star and no
> "closing" star
> 
>   But this paragraph *has some emphasized* text. Notice the position of
> the * relative
>   to whitespace.

Originally, gendoc used *emphasized string*, but I changed it to setext
syntax. I'd be happy to change it back, if that is the consensus of this
group.

> > |>
> > |> >  a single italic word               ~word~  1 italic word      italic-tt (f)
> > |>
> > |> This looks ugly.  Why specify italic directly?  Doesn't this run counter
> > |> to HTML
> > |> philosophy.
> >
> > HTML philosopy had nothing to do with setext as far as I can tell.
> 
> But I would argue that, while python documentation strings should not
> be bound by HTML, they should share the philosphy of content, rather
> than
> presentation-oriented markup.
>

Yes, that sounds reasonable. That is also what gendoc does. I don't (as
far as
I can remember...) use the physical markups of HTML.

> 
> > |>
> > |> >  1+ underlined words        [_multi]_word_  underlined text underline-tt (g)
> > |>
> > |> What consitutes a word?  Does this run afoul of
> > |> multi_word_python_variable_names?
> >
> > Same. Not really as there has to be both a leading and trailing underscore.
> 
> Uh, you mean, as in __getstate__ or __add__?

Since variables with surrounding double underscores are *very* common in
Python, I explicitly check for this.

> > |>
> > |> >  hypertextual 1+ word        [multi_]word_  1+ hot word(s)        hot-tt (h)
> > |>
> > |> This is weird.  Where is the reference?  Has this been implemented in
> > |> gendoc?
> >
> > Yes. You specify a_hyperlink_ like this and it points to the address spec'd
> > at the end of the doc string.  It's not obvious from the setext docs. That's
> > why I explained it later with examples.
> >
> > .. _a_hyperlink http://www.python.org/sigs/
> 
> Hm.  I didn't try to address this in StructuredText.  But there has to
> be
> a better way.
> 
> Something I've done in the past is:
> 
>   (See so and so.)
> 
> gets translated, in HTML, to:
> 
>   (See so and so.)

How do you derive the url?

> > |>
> > |> >  >followed by text     >[space][text]       > [mono-spaced]   include-tt (i)
> > |>
> > |> This looks like a quoted email message.  But I guess it makes sense.
> > |>
> > |> >  bullet-text in pos1   *[space][text]       [bullet] [text]    bullet-tt (j)
> > |>
> > |> I think 'o text' and '- text' are more readable.
> > |>
> > |> >                        `_quoted typotag!_`  `_left alone!_`     quote-tt (k)
> > |>
> > |> `_e_gads!_`  I like 'this much better'
> >
> > Don't think this comes up much and it's not necessarily implemented yet.
> 
> It comes up *all the time* in my doc strings. If I am mentioning
> a function name or argument to a method, I quote it to separate it from
> the
> rest of the text.  Ditto if I mention a small snippet of code within
> prose.

*, - and o is now valid bullets ('o' is not in version 0.5). I'll add
quoted text, if no one objects.

> > |>
> > |> >  --------------------  -------------------  --------------- ------------ ---
> > |> >  [hypertext link def] ^.. _word URL         jump to address      href-tt (l)
> > |> >  [hypertext note def] ^.. _word Note:("*")  ("cause error")      note-tt (m)
> > |>
> > |> I have no idea what this means.
> > |>
> > |> >  --------------------  -------------------  --------------- ------------ ---
> > |> >  end of first? setext  $$ [last on a line]  [parse another]   twobuck-tt (n)
> > |> >                       ^..[space][not dot]   [line hidden]    suppress-tt (o)
> > |> >  logical end of text  ^..[alone on a line]  [taken note of]    twodot-tt (p)
> > |>
> > |> Huh?
> >
> > Read on McDuff...
> 
> I did.  But I didn't see any new explanation.  I studied the table some
> more and
> figured out that the ^ must mean the begining of a line.  So let me see
> if I've
> got this straight:
> 
>   - A line beginning with two dots is a "comment".
>   - There are special comments:
> 
>      - A line with just two dots is the end of the document.
>      - A line beginning with two dots, a space, and an underscore
> defines the
>        target of a reference in some fashion.

Only the last is implemented in gendoc.

>   - A line ending in two dollar signs defines the end of a document
> component.
>     But, of course, document components have not been defined.

This is skipped too in gendoc

> > ...
> > |> > -----------------------------------------------------------------------
> > |> > The following doc string example illustrates the usage of all setext
> > |> > constructs recognized by the gendoc tool. (i think)
> > |> >
> > |> > class Setext(Text):
> > |> >     """Lets you change markup to stylize your text
> > |> >
> > |> >     SETEXT 102
> > |> >     ==========
> > |>
> > |> This is not valid setext.  Setext wants the titles and headings to start
> > |> in column 1 and the other text in column 3, like this:
> >
> > Yes but the implementation doesn't enforce that now. headings and body can
> > be in column one.  Remember Daniel strips the leading tab/spaces from the
> > doc string before applying these rules.
> 
> I saw that below.  But much of the argument for using setext seems to be
> that you are leveraging an existing mechanism.  Buy you aren't really.
> You are
> borrowing from it the things you like.

Yes that's correct (with the possible exception that I'm not sure I like
all I borrowed :-)

> > |>
> > |> SETEXT 102
> > |> ==========
> > |>
> > |>   **Setext** can be used to mark your text in a non-obtrusive
> > |>   manner. Text within double asterisks are treated as bold, ...
> > |>
> > |> >     **Setext** can be used to mark your text in a non-obtrusive
> > |> >     manner. Text within double asterisks are treated as bold,
> > |> >     while single words with tilde at the front and back are
> > |> >     rendered as ~Italic~. You can _underline_a_phrase_ but it
> > |> >     will be rendered as bold in HTML. Placing hyperlinks
> > |> >     is easy; just hilite_the_tag_ and at the bottom of the doc
> > |> >     string include the address which it points to on a line by
> > |> >     itself.
> > |> >
> > |> >     New paragraphs are separated by blank lines.
> > |> >     > And a bunch of literal text
> > |> >     > can be specified with the left
> > |> >     > arrow. This gets marked as 
 in HTML.
> > |> >     Otherwise the text will be wrapped according to whatever
> > |> >     output formatter is used.
> > |> >
> > |> >     A bulleted list is done with single asterisks thusly:
> > |> >     * Lettuce
> > |> >     * Onions
> > |> >     * Pickles
> > |> >
> > |> >     Extension to setext
> > |> >     -------------------
> > |>
> > |> Ditto.
> > |>
> > |> >     A frequent construct in python doc strings is to list ones
> > |> >     keyword arguments. This made us wish for a way to specify
> > |> >     a definition list so that it looks nice is html (and others).
> > |> >     I propose the following. I have this working in my version.
> > |> >     The double colons won't be in the output.
> > |> >
> > |> >     item1 :: definition 1
> > |> >     item2 :: definition 2
> > |> >     item3 :: a rather long and involved definition for item 3
> > |> >              spanning more than one line.
> > |> >     item4 :: back to brevity with definition 4
> > |>
> > |> Why not:
> > |>
> > |>       item1 -- Definition 1
> > |>       ...
> > |>
> > |> This looks much better to me, and works with StructuredText.
> >
> > Hey, I just picked it out of the blue. (And I've never seen your
> > structured text module.) ':-(
> 
> Hey, please don't take my note of a criticism of your work.  I'm
> just trying to comment on the format.  I apreciate you and Dan moving
> this
> thing along.

Well, this discussion is precisely what I wanted to see when I released
gendoc to this group. As I stated in the README, this is supposed to
be a collaborative effort, and I hope we can make this into a very
useful
tool for a lot of people in the Python community.

> > |>
> > |> >     .. _hilite_the_tag http://www.python.org
> > |> >     """
> > |> >
> > |> > Notes:
> > |> >
> > |> > The indenting inserted by python-mode for the entire doc string is
> > |> > detected and processed out before setext rules are applied. So
> > |> > eventhough titles for example are required to start in column one they
> > |> > will if they obey the overall indenting for that doc string.
> > |>
> > |> Hm.
> > |>
> > |> > The underlines for the title and subtitle should be the same length as
> > |> > the title itself.
> > |> >
> > |> > Spaces around tokens are important (for the "* ", "> ", and " :: ")
> > |> >
> > |> > Comment are hearby welcome.
> > |>
> > |> I think my structured text module mechanism provides richer
> > |> text formatting with less obtrusive markup, especially for
> > |> strings that have much structure, as many of mine do.
> > |>
> > |> Jim
> >
> > Fine,
> > Send it to me!!
> 
> I did.
>

As I said, I want to take a good look at Jim's work. Unfortunately, some
of the work expected from me by my employer needs to be done, so I'm
afraid
it might take a couple of weeks before I have something for you to try
out.

Keep on discussing!

> Jim
> 
> --
> Jim Fulton         Digital Creations
> jim@digicool.com   540.371.6909
> ## Python is my favorite language ##
> ##     http://www.python.org/     ##
> 
> =================
> DOC-SIG  - SIG for the Python Documentation Project
> 
> send messages to: doc-sig@python.org
> administrivia to: doc-sig-request@python.org
> =================

-- 
Daniel Larsson, ABB Industrial Systems AB

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Tue Aug 13 14:06:12 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Tue, 13 Aug 1996 08:06:12 -0500
Subject: [PYTHON DOC-SIG] setext in doc strings
Message-ID: <199608131306.IAA13411@darwin.rsoc.rockwell.com>


|> From owner-doc-sig@python.org Fri Aug  9 10:33 CDT 1996
|> Date: Tue, 06 Aug 1996 08:26:21 -0400
|> From: Jim Fulton 
|> 
|> Robin Friedrich wrote:
|> > ..... 
|> > Bummer. I didn't get it. Can you send it again? Be sure it's not >40K if
|> > you send it to a sig list - it won't get forwarded.
|> 
|> Hm.  It was only a K or so.  I got a copy through the list.  Dod anyone
|> else
|> not get the StructuredText note?  Did everyone else get this note?
|> 
|> Robin, I forwarded another copy to you.

Got it, finally.  I've just recovered from a new IP number here so I'm
afraid I have missed much of last week's traffic. I've gotten your
StructuredText module (a couple days after you sent it) and have played
with it a little.
I have the following comments:

	I would rather not have to separate each item in 
	a bulleted list by a blank line.

	We need to incorporate a tagging method for hyperlink
	URLs. Would the sextext method be acceptable for this?
	I still don't see anything wrong with it.

	Can we change the ** mapping to 'strong'? It seems
	redundant with the * mapping.

	Ordered list elements don't seem to work. 


I can see some nice potential here for gendoc though and I'm sure Dan
can use pieces of it. When I said leverage off an existing setext idea
I meant that we could borrow from others that have paid some thought to 
the same requirements we have with doc strings, not to adopt any
implementations verbatum. I think doc-sig should specify a nice doc
string format which serves our needs. The implementation in python 
will be the easy part.

Below is an example of my doc string using the setext method...

class FramesetDocument(Document):
    """A minimal document suitable for entering Framesets.

    Arguments are for contents **NOT** a document resource file.
    No  markup. Instead add Frameset(s) with the constructor or
    append method.  Useful methods are _append_, _prepend_, _write_,
    and _copy_. Others inherited from Document class are unused.

    Keyword Parameters
    ------------------
    
    title :: string to be used as the document title.
    base  :: object of the Base class
    meta  :: object of the Meta class
    cgi   :: if non zero will issue a mime type of text/html
    """

And following is what it might look like given the structured text support.

class FramesetDocument(Document):
    """A minimal document suitable for entering Framesets.

    Arguments are for contents **NOT** a document resource file.
    No  markup. Instead add Frameset(s) with the constructor or
    append method.  Useful methods are *append*, *prepend*, *write*,
    and *copy*. Others inherited from Document class are unused.

    Keyword Parameters
   
	title -- string to be used as the document title.
	base  -- object of the Base class
	meta  -- object of the Meta class
	cgi   -- if non zero will issue a mime type of text/html
    """

Looks fine to me.  What do others think?

-Robin

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From amk@magnet.com  Tue Aug 13 16:36:57 1996
From: amk@magnet.com (Andrew Kuchling)
Date: Tue, 13 Aug 1996 11:36:57 -0400 (EDT)
Subject: [PYTHON DOC-SIG] Documentation format
Message-ID: <199608131536.LAA27412@lemur.magnet.com>

One of the goals of the Doc-SIG is to decide on a format for written
documentation, such as the tutorial and library reference.  Currently
LaTeX is used for everything, and it's converted to Texinfo and HTML.

However, there are now more things that need to be documented, such as
the presence and name of keyword arguments, and default argument
values.  We could add LaTeX macros to handle them, but it might be a
good time to think about the format of Python's documentation, and to
consider the usefulness of changing it (both the input format, and the
typographical presentation of the output).  Therefore, I'm raising the
topic for discussion here.

Some possible topics: How should keywords and default values be
presented while keeping the library manual readable?  What other
formatting features would be useful?  Should we stick with LaTeX, or
would some other format be easier to work with?  What are the
advantages and disadvantages of the various possibilities?

Quoting from the Doc-SIG Web page: 
+ The format options:
               o Write in one format, and generate multiple output formats.
                    # Linuxdoc
                    # Bill Janssen suggested something else
               o What output formats are needed
                    # Postscript
                    # HTML
                    # info
                    # troff (-man option)
                    # native Grail .pyc files ??


	I'll list the possible input formats I can think of, without
commenting on their usefulness or applicability:

	* LaTeX 
PostScript output for free; converted to Texinfo, provides HTML, Info.

	* Texinfo
PostScript, HTML, Info output for free.

	* Texinfo variants (such as ILU's TIM, or an otherwise
modified texinfo) 
PostScript, HTML, Info could be produced, but changes to texinfo.tex,
makeinfo, texi2html would be required to get that output.

	* HTML 
How can one convert HTML to PostScript or Info?  

	* Some other SGML-based solution (like Linuxdoc-SGML)
In theory, any output we like (TeX, troff, HTML) could be generated,
but a fair amount of coding would be required to get that output.  

	* troff  
I don't know troff very well; presumably one can get PS output, but is
there a troff-to-HTML converter?

	I'd imagine automatic generation of an index and table of
contents is mandatory, particularly for the reference guide and
library reference.

	Any thoughts on this?


	Andrew Kuchling
	amk@magnet.com

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Tue Aug 13 22:14:33 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Tue, 13 Aug 1996 16:14:33 -0500
Subject: [PYTHON DOC-SIG] Documentation format
Message-ID: <199608132114.QAA14058@darwin.rsoc.rockwell.com>


|> From: Andrew Kuchling 
|> 
|> One of the goals of the Doc-SIG is to decide on a format for written
|> documentation, such as the tutorial and library reference.  Currently
|> LaTeX is used for everything, and it's converted to Texinfo and HTML.
|> 
|> However, there are now more things that need to be documented, such as
|> the presence and name of keyword arguments, and default argument
|> values.  We could add LaTeX macros to handle them, but it might be a
|> good time to think about the format of Python's documentation, and to
|> consider the usefulness of changing it (both the input format, and the
|> typographical presentation of the output).  Therefore, I'm raising the
|> topic for discussion here.
|> 
|> Some possible topics: How should keywords and default values be
|> presented while keeping the library manual readable?  What other
|> formatting features would be useful?  Should we stick with LaTeX, or
|> would some other format be easier to work with?  What are the
|> advantages and disadvantages of the various possibilities?
|> 
|> Quoting from the Doc-SIG Web page: 
|> + The format options:
|>                o Write in one format, and generate multiple output formats.
|>                     # Linuxdoc
|>                     # Bill Janssen suggested something else
|>                o What output formats are needed
|>                     # Postscript
|>                     # HTML
|>                     # info
|>                     # troff (-man option)
|>                     # native Grail .pyc files ??
|> 
|> 
|> 	I'll list the possible input formats I can think of, without
|> commenting on their usefulness or applicability:
|> 
|> 	* LaTeX 
|> PostScript output for free; converted to Texinfo, provides HTML, Info.
|> 
|> 	* Texinfo
|> PostScript, HTML, Info output for free.
|> 
|> 	* Texinfo variants (such as ILU's TIM, or an otherwise
|> modified texinfo) 
|> PostScript, HTML, Info could be produced, but changes to texinfo.tex,
|> makeinfo, texi2html would be required to get that output.
|> 
|> 	* HTML 
|> How can one convert HTML to PostScript or Info?  
|> 
|> 	* Some other SGML-based solution (like Linuxdoc-SGML)
|> In theory, any output we like (TeX, troff, HTML) could be generated,
|> but a fair amount of coding would be required to get that output.  
|> 
|> 	* troff  
|> I don't know troff very well; presumably one can get PS output, but is
|> there a troff-to-HTML converter?
|> 
|> 	I'd imagine automatic generation of an index and table of
|> contents is mandatory, particularly for the reference guide and
|> library reference.
|> 
|> 	Any thoughts on this?
|> 

Good thread Andy. I might add PDF and FrameMaker and WinHelp formats 
to the list. I think troff may be extranious at this point.

As far as the native base docs, Frame is a valid candidate.

Pros: WYSIWYG, so it's easier to maintain.
      Output in PostScript free; output in HTML free or nearly so;
      output in PDF inexpensive.  Output in RTF(as a way to WinHelp)
      Support for hyperlinks native. Support for Graphics and nice
      tables.  Support for equations.  Indexing and TOC support.
      Framemaker is very common (more so than TeX) Large extension
      writers more likely to use it (NumPy, PIL, etc) and fold it into
      the Doc tree.  Portable; available on most platforms.  Converter
      available for LaTeX -> Frame.  see
      http://www.ius.cs.cmu.edu/IUS/sin_www/help/Document/latex2fm.html

Cons: convertion to info not available. 

Having said this LaTeX2e would be the best choice if we are keeping it
in a ASCII readable format which can be parsed. It continues to
provide many useful output formats.

OTOH, I just installed TeX and was impressed by how much a pain in the
buttocks it was to get running.  I see the use of LaTeX in the future
dwindling (although LaTeX3 may save it).  Either way, TeX is a black
art and we're not going to get many people to help with the doc
maintenance as long as it's encoded that way. 

I'm going to download the latex2fm tool above and try my hand at 
converting the 1.4b2 docs.  (just for grins)

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From jim.fulton@digicool.com  Tue Aug 13 22:45:52 1996
From: jim.fulton@digicool.com (Jim Fulton)
Date: Tue, 13 Aug 1996 17:45:52 -0400
Subject: [PYTHON DOC-SIG] Documentation format
References: <199608132114.QAA14058@darwin.rsoc.rockwell.com>
Message-ID: <3210F790.445@digicool.com>

Robin Friedrich wrote:
> 
> |> From: Andrew Kuchling 
> |>
> |> One of the goals of the Doc-SIG is to decide on a format for written
> |> documentation, such as the tutorial and library reference.  Currently
> |> LaTeX is used for everything, and it's converted to Texinfo and HTML.
> |>
> |> However, there are now more things that need to be documented, such as
> |> the presence and name of keyword arguments, and default argument
> |> values.  We could add LaTeX macros to handle them, but it might be a
> |> good time to think about the format of Python's documentation, and to
> |> consider the usefulness of changing it (both the input format, and the
> |> typographical presentation of the output).  Therefore, I'm raising the
> |> topic for discussion here.
> |>
> |> Some possible topics: How should keywords and default values be
> |> presented while keeping the library manual readable?  What other
> |> formatting features would be useful?  Should we stick with LaTeX, or
> |> would some other format be easier to work with?  What are the
> |> advantages and disadvantages of the various possibilities?
> |>
> |> Quoting from the Doc-SIG Web page:
> |> + The format options:
> |>                o Write in one format, and generate multiple output formats.
> |>                     # Linuxdoc
> |>                     # Bill Janssen suggested something else
> |>                o What output formats are needed
> |>                     # Postscript
> |>                     # HTML
> |>                     # info
> |>                     # troff (-man option)
> |>                     # native Grail .pyc files ??
> |> 
> |>
> |>      I'll list the possible input formats I can think of, without
> |> commenting on their usefulness or applicability:
> |>
> |>      * LaTeX
> |> PostScript output for free; converted to Texinfo, provides HTML, Info.
> |>
> |>      * Texinfo
> |> PostScript, HTML, Info output for free.
> |>
> |>      * Texinfo variants (such as ILU's TIM, or an otherwise
> |> modified texinfo)
> |> PostScript, HTML, Info could be produced, but changes to texinfo.tex,
> |> makeinfo, texi2html would be required to get that output.
> |>
> |>      * HTML
> |> How can one convert HTML to PostScript or Info?
> |>
> |>      * Some other SGML-based solution (like Linuxdoc-SGML)
> |> In theory, any output we like (TeX, troff, HTML) could be generated,
> |> but a fair amount of coding would be required to get that output.
> |>
> |>      * troff
> |> I don't know troff very well; presumably one can get PS output, but is
> |> there a troff-to-HTML converter?

Yes.

> |>      I'd imagine automatic generation of an index and table of
> |> contents is mandatory, particularly for the reference guide and
> |> library reference.
> |>
> |>      Any thoughts on this?
> |>
> 
> Good thread Andy. I might add PDF and FrameMaker and WinHelp formats
> to the list.

As input or output?

> I think troff may be extranious at this point.

Hm.
 
> As far as the native base docs, Frame is a valid candidate.
> 
> Pros: WYSIWYG, so it's easier to maintain.
>       Output in PostScript free; output in HTML free or nearly so;
>       output in PDF inexpensive.  Output in RTF(as a way to WinHelp)
>       Support for hyperlinks native. Support for Graphics and nice
>       tables.  Support for equations.  Indexing and TOC support.
>       Framemaker is very common (more so than TeX) Large extension
>       writers more likely to use it (NumPy, PIL, etc) and fold it into
>       the Doc tree.  Portable; available on most platforms.  Converter
>       available for LaTeX -> Frame.  see
>       http://www.ius.cs.cmu.edu/IUS/sin_www/help/Document/latex2fm.html

I like Frame alot, but it is pricey.
 
> Cons: convertion to info not available.
> 
> Having said this LaTeX2e would be the best choice if we are keeping it
> in a ASCII readable format which can be parsed. It continues to
> provide many useful output formats.
> 
> OTOH, I just installed TeX and was impressed by how much a pain in the
> buttocks it was to get running.  I see the use of LaTeX in the future
> dwindling (although LaTeX3 may save it).  Either way, TeX is a black
> art and we're not going to get many people to help with the doc
> maintenance as long as it's encoded that way.

I never had the enthusiasm to get TeX or any of it's variants running on
any 
platform I had access to.  I doubt I ever will.
 
Personally, I think that we should strive for generating as much
documentation 
as possible from module doc strings.  

I also think a simple doc string format should be used with clever
conversion 
tools. I've has quite satisfactory results doing this myself.

Jim

-- 
Jim Fulton         Digital Creations
jim@digicool.com   540.371.6909
## Python is my favorite language ##
##     http://www.python.org/     ##

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Tue Aug 13 23:26:17 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Tue, 13 Aug 1996 17:26:17 -0500
Subject: [PYTHON DOC-SIG] Documentation format
Message-ID: <199608132226.RAA14452@darwin.rsoc.rockwell.com>


|> From jim.fulton@digicool.com Tue Aug 13 16:48 CDT 1996
|> Date: Tue, 13 Aug 1996 17:45:52 -0400
|> From: Jim Fulton 
|> 
|> Robin Friedrich wrote:
|> > 
|> > |> From: Andrew Kuchling 
|> > |>
...
|> > |>      I'd imagine automatic generation of an index and table of
|> > |> contents is mandatory, particularly for the reference guide and
|> > |> library reference.
|> > |>
|> > |>      Any thoughts on this?
|> > |>
|> > 
|> > Good thread Andy. I might add PDF and FrameMaker and WinHelp formats
|> > to the list.
|> 
|> As input or output?

Output. Except in the possible case of Framemaker.
|> 
|> > I think troff may be extranious at this point.
|> 
|> Hm.

By this I was refering to the lessening importance of man pages in a
world not dominated by Unix. Latex also has some packages for
generation or man-like pages as well.

|>  
|> > As far as the native base docs, Frame is a valid candidate.
|> > 
|> > Pros: WYSIWYG, so it's easier to maintain.
|> >       Output in PostScript free; output in HTML free or nearly so;
|> >       output in PDF inexpensive.  Output in RTF(as a way to WinHelp)
|> >       Support for hyperlinks native. Support for Graphics and nice
|> >       tables.  Support for equations.  Indexing and TOC support.
|> >       Framemaker is very common (more so than TeX) Large extension
|> >       writers more likely to use it (NumPy, PIL, etc) and fold it into
|> >       the Doc tree.  Portable; available on most platforms.  Converter
|> >       available for LaTeX -> Frame.  see
|> >       http://www.ius.cs.cmu.edu/IUS/sin_www/help/Document/latex2fm.html
|> 
|> I like Frame alot, but it is pricey.

And many many folks have already bitten that bullet. (although I would say
$500 is only pricey for individuals not companies, and that's who would 
need it.) It would be used by the PSA stuckee in charge of maintaining
the Docs.  Guido would like to get this whole deal off his back. 
End users look at paper or html or winhelp.

BTW I downloaded the above la2mml tool and compiled it and ran it 
against all the 1.4b2 .tex files and it did generate the complete doc
set (with many caveats).  MML (maker markup language) is rather limited
in scope as it has no support for character tags. Thus all the \code
latex markups etc, is left in the text. That would have to be cleaned 
up with a little processor.  The indexes likewise would have to be
manually dealt with to get the docs back up to snuff in the Frame5 format.
This conversion mess would have to be done only once though so I don't
worry too much about it. I estimate two weeks for a FrameMaker-Python-Latex-
MML-MIF expert ;-).

Otherwise the bulk of the text came over fine.

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From amk@magnet.com  Tue Aug 13 23:26:49 1996
From: amk@magnet.com (Andrew Kuchling)
Date: Tue, 13 Aug 1996 18:26:49 -0400 (EDT)
Subject: [PYTHON DOC-SIG] Documentation format
In-Reply-To: <3210F790.445@digicool.com> from "Jim Fulton" at Aug 13, 96 05:45:52 pm
Message-ID: <199608132226.SAA07622@lemur.magnet.com>


Robin Friedrich wrote:
> > Good thread Andy. I might add PDF and FrameMaker and WinHelp formats
> > to the list.

	Good point, particularly WinHelp; we shouldn't be Unix-centric
here, and the 95/NT ports deserve support.  (What does the Mac use for
help?  That should be supported, too.)  However, I think we also need
some sort of basic ASCII-readable format (consider the recent poster
to python-list who didn't have FTP or Web access); presumably that's
why troff was listed in the original charter, and why Info's supported
now.

Jim Fulton wrote:
> Personally, I think that we should strive for generating as much
> documentation as possible from module doc strings.  

	True, but would this really help with things like the tutorial
and the reference manual?  While it's not absolutely required that
everything be done in the same format, variety probably is a bad thing
in this case, or we might wind up with, say only the library
ref. available in WinHelp, but not the other documents.

	Another thought: If we turn module-level docstrings into
lengthy blocks of text intended for paper and HTML documents, .pyc
files will get larger and slower to read, and the temptation to
optimize them by stripping out the docstrings will increase.  But if
everyone strips out docstrings by default, they're no longer available
from inside the interpreter, which damages their usefulness.  

> I also think a simple doc string format should be used with clever
> conversion tools. I've has quite satisfactory results doing this
> myself.

	Good suggestion.  Would it be feasible to write straight
documents in a docstring format?  For example, could I take the
tutorial, turn it into one huge docstring, run it through a conversion
tool and get reasonable output?  I guess this approach is similar to
Perl's pod format, which is a simple application-specific ASCII format
which is converted to HTML, troff, or whatever.  
	
	My original posting tried to be neutral, so I might as well
say now that my personal preference leans toward either Texinfo or a
simple made-up format like pod or docstring.  Either one is less
powerful than full-blown LaTeX, which means it's easier to parse.
However, Texinfo's typography is really bad, so it would have to be
modified to change the margins and fonts.

	(Frame's non-free status doesn't worry me much, though I'd
never have access to it.  The Frame source would be available on
python.org, and the distribution would ship with various output files
like PS, HTML, or WinHelp.  Better make sure Guido has access to it,
though.)


	Andrew Kuchling
	amk@magnet.com


=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Wed Aug 14 00:05:25 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Tue, 13 Aug 1996 18:05:25 -0500
Subject: [PYTHON DOC-SIG] Documentation format
Message-ID: <199608132305.SAA14489@darwin.rsoc.rockwell.com>


|> From: Andrew Kuchling 
|> 
|> Robin Friedrich wrote:
|> > > Good thread Andy. I might add PDF and FrameMaker and WinHelp formats
|> > > to the list.
|> 
|> 	Good point, particularly WinHelp; we shouldn't be Unix-centric
|> here, and the 95/NT ports deserve support.  (What does the Mac use for
|> help?  That should be supported, too.)  However, I think we also need

The Mac doesn't have a universal tool although Apple would like 
everyone to write in the Assistant(?) format. I use the html myself
on the Mac at home. 

|> some sort of basic ASCII-readable format (consider the recent poster
|> to python-list who didn't have FTP or Web access); presumably that's
|> why troff was listed in the original charter, and why Info's supported
|> now.

I place the ascii version as a lower priority. For the quick reference
I do keep a file in an emacs buffer all the time but when I want the
full docs I just open the book (never far from my side). The info docs
are nice but I wouldn't miss them too much. And again that's leading
to me Unix-centric in thinking.  As a base format I think we need a 
powerful tool not a pod-like clone.

|> 
|> Jim Fulton wrote:
|> > Personally, I think that we should strive for generating as much
|> > documentation as possible from module doc strings.  
|> 
|> 	True, but would this really help with things like the tutorial
|> and the reference manual?  While it's not absolutely required that
|> everything be done in the same format, variety probably is a bad thing
|> in this case, or we might wind up with, say only the library
|> ref. available in WinHelp, but not the other documents.
|> 
|> 	Another thought: If we turn module-level docstrings into
|> lengthy blocks of text intended for paper and HTML documents, .pyc
|> files will get larger and slower to read, and the temptation to
|> optimize them by stripping out the docstrings will increase.  But if
|> everyone strips out docstrings by default, they're no longer available
|> from inside the interpreter, which damages their usefulness.  

This was addressed at the last workshop and after some jabberwalky
we concluded that it's really not as big a drag as people think.
The final recommendation was to use doc strings with gusto and 
let the anal retentives strip them out.  

|> 
|> > I also think a simple doc string format should be used with clever
|> > conversion tools. I've has quite satisfactory results doing this
|> > myself.
|> 
|> 	Good suggestion.  Would it be feasible to write straight
|> documents in a docstring format?  For example, could I take the
|> tutorial, turn it into one huge docstring, run it through a conversion
|> tool and get reasonable output?  I guess this approach is similar to
|> Perl's pod format, which is a simple application-specific ASCII format
|> which is converted to HTML, troff, or whatever.  
|> 	
|> 	My original posting tried to be neutral, so I might as well
|> say now that my personal preference leans toward either Texinfo or a
|> simple made-up format like pod or docstring.  Either one is less
|> powerful than full-blown LaTeX, which means it's easier to parse.
|> However, Texinfo's typography is really bad, so it would have to be
|> modified to change the margins and fonts.
|> 
|> 	(Frame's non-free status doesn't worry me much, though I'd
|> never have access to it.  The Frame source would be available on
|> python.org, and the distribution would ship with various output files
|> like PS, HTML, or WinHelp.  Better make sure Guido has access to it,
|> though.)
|> 

I believe CNRI does have Framemaker.  But again, the docs are something
Guido would love to delegate.
I vote for a powerful system, either Latex or Frame.

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From janssen@parc.xerox.com  Wed Aug 14 00:37:35 1996
From: janssen@parc.xerox.com (Bill Janssen)
Date: Tue, 13 Aug 1996 16:37:35 PDT
Subject: [PYTHON DOC-SIG] Bill Janssen suggested...
Message-ID: 

As a new member of the documentation SIG, let me point out that it's
Bill Janssen, not `Bill Janseen', as the web page says.  You can find a
write-up on what I suggested (it's called TIM) at
ftp://ftp.parc.xerox.com/pub/ilu/20/20a8-manual-html/manual_17.html#SEC27
5 (which, by the way, is written in TIM).

The basic idea is simple.  Let's take a reasonable markup source
language which has lots of tools to translate it into other formats, and
add a layer on top to support domain-specific markup.  We picked GNU
texinfo as a decent source form, from which text, HTML, Info, and
Postscript could be produced.  We then added a preprocessor layer to
translate domain-specific terms such as `@isl' (used to mark an ILU ISL
literal), to the domain-independent terms used by texinfo; for example,
`@isl' is translated to `@code'.  The preprocessor also drives the
transformation from texinfo to the desired output format, thereby
freeing the user from having to remember how to run TeX, etc.  Finally,
two domain-independent features are provided by TIM, and implemented in
the preprocessor.  They are the ability to include pictures in texinfo,
and the ability to add URL links.

Bill

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From richard.jones@bom.gov.au  Wed Aug 14 00:58:45 1996
From: richard.jones@bom.gov.au (Richard Jones)
Date: Tue, 13 Aug 1996 23:58:45 GMT
Subject: [PYTHON DOC-SIG] Documentation format
In-Reply-To: Message from Andrew Kuchling of 1996-Aug-13 18:26:49,
 <199608132226.SAA07622@lemur.magnet.com>
Message-ID: <199608140000.UAA17816@python.org>


Andrew Kuchling wrote:
> Jim Fulton wrote:
> > I also think a simple doc string format should be used with clever
> > conversion tools. I've has quite satisfactory results doing this
> > myself.
> 
> 	Good suggestion.  Would it be feasible to write straight
> documents in a docstring format?  For example, could I take the
> tutorial, turn it into one huge docstring, run it through a conversion
> tool and get reasonable output?  I guess this approach is similar to
> Perl's pod format, which is a simple application-specific ASCII format
> which is converted to HTML, troff, or whatever.  

	I'd like to add a vote here for a simple format like the docstring format 
that can be then turned into pretty pages.  Let's try to keep it simple 
for the people who have to write this documentation (like me).  I don't 
have access to Frame, and probably never will.  I do have access to LaTeX 
(and I'm not afraid to use it), but I think we'd be making a mistake 
keeping on going down that path - TeX _is_ a pain to install.

	The docstring format has another thing going for it -- apart from being a 
simple format to write documents in -- in that it is immediately readable 
by all users.  If a user doesn't have access to a PS, HTML, Frame, DVI, 
etc viewer, then they can still view the documentation.  This is a Good 
Thing.  Unfortunately the docstring format doesn't support images - which 
are sometimes invaluable in tutorials etc.


		Richard



=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From amk@magnet.com  Wed Aug 14 18:03:05 1996
From: amk@magnet.com (Andrew Kuchling)
Date: Wed, 14 Aug 1996 13:03:05 -0400 (EDT)
Subject: [PYTHON DOC-SIG] Documentation format
In-Reply-To: <199608140000.UAA17816@python.org> from "Richard Jones" at Aug 13, 96 11:58:45 pm
Message-ID: <199608141703.NAA23869@lemur.magnet.com>

Richard Jones wrote:
> 	I'd like to add a vote here for a simple format like the docstring format 
> that can be then turned into pretty pages.  Let's try to keep it simple 
> for the people who have to write this documentation (like me).  I don't 

	I agree.  I also like a simple, nonextensible format because
it'll prevent people from inventing new constructs.  For example, when
documenting a class with keywords, there's a temptation to write
something like:

\begin{funcdesc}{Bastion}{object\, {\bf filter}=filterfunc, 
	                  {\bf name}=objectname\, {\bf bastionclass}=class}

	...which may look OK in the LaTeX output.  But will the
conversion process to Texinfo or HTML still work?  With a simple,
highly constrained language, inventing a new command would require
changing the code, which would reduce the number of commands that get
added.

> Thing.  Unfortunately the docstring format doesn't support images - which 
> are sometimes invaluable in tutorials etc.

	Well, no one intends that all Python-related material *must*
be written in this format; books and papers can be written in Frame,
LaTeX, Lout, or whatever the author likes.  I'm only thinking of the
material that should be available wherever Python is ported; that must
include the library reference, and should include the reference
manual.  Neither of those documents includes any graphics at all.  The
tutorial would be nice to have, but users don't need it close at hand.

	(The fourth item in the Doc/ subdirectory is the paper
"Interactively Testing Remote Servers Using the Python Programming
Language", which would be left in LaTeX; it doesn't need to be
translated since it's not immensely helpful in using Python.)


	Andrew Kuchling
	amk@magnet.com


=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From guido@CNRI.Reston.Va.US  Wed Aug 14 20:37:10 1996
From: guido@CNRI.Reston.Va.US (Guido van Rossum)
Date: Wed, 14 Aug 1996 15:37:10 -0400
Subject: [PYTHON DOC-SIG] Documentation format
In-Reply-To: Your message of "Tue, 13 Aug 1996 18:26:49 EDT."
 <199608132226.SAA07622@lemur.magnet.com>
References: <199608132226.SAA07622@lemur.magnet.com>
Message-ID: <199608141937.PAA06835@monty>

> 	(Frame's non-free status doesn't worry me much, though I'd
> never have access to it.  The Frame source would be available on
> python.org, and the distribution would ship with various output files
> like PS, HTML, or WinHelp.  Better make sure Guido has access to it,
> though.)

I do, and I like Frame a lot.  What you say here also makes me feel
more comfortable with Frame's non-free status; however the free HTML
generation sucks.

However, we have some internal projects where we are supposed to
maintain the real documentation in Frame (by our own choice) and it
seems no-one is willing to maintain Frame documents -- one reason
seems to be that you can't edit them in Emacs.

--Guido van Rossum (home page: http://www.python.org/~guido/)

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From guido@CNRI.Reston.Va.US  Wed Aug 14 20:30:16 1996
From: guido@CNRI.Reston.Va.US (Guido van Rossum)
Date: Wed, 14 Aug 1996 15:30:16 -0400
Subject: [PYTHON DOC-SIG] Documentation format
In-Reply-To: Your message of "Tue, 13 Aug 1996 23:58:45 GMT."
 <199608140000.UAA17816@python.org>
References: <199608140000.UAA17816@python.org>
Message-ID: <199608141930.PAA06808@monty>

I'm trying to follow this discussion without reading every message...

For standard C modules like posix, am I supposed to have the complete
text of the manual section for that module in the C source?  Should it
be accesseble at runtime?  I'm not sure this is an ideal solution (for
one thing, large amounts of plain text are a pain to type in Emacs' CC
mode).

If this is not happening, we still have the question of what
documentation format to use (also for things like the reference
manual, the tutorial and the extending/embedding manual, which will
never be contained in docstrings).  How feasible is @texinfo or ILU's
TIM (which looks like an extension of @texinfo)?

--Guido van Rossum (home page: http://www.python.org/~guido/)

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From guido@CNRI.Reston.Va.US  Wed Aug 14 20:32:08 1996
From: guido@CNRI.Reston.Va.US (Guido van Rossum)
Date: Wed, 14 Aug 1996 15:32:08 -0400
Subject: [PYTHON DOC-SIG] Bill Janssen suggested...
In-Reply-To: Your message of "Tue, 13 Aug 1996 16:37:35 PDT."
 
References: 
Message-ID: <199608141932.PAA06820@monty>

> As a new member of the documentation SIG, let me point out that it's
> Bill Janssen, not `Bill Janseen', as the web page says.  You can find a
> write-up on what I suggested (it's called TIM) at
> ftp://ftp.parc.xerox.com/pub/ilu/20/20a8-manual-html/manual_17.html#SEC27
> 5 (which, by the way, is written in TIM).
> 
> The basic idea is simple.  Let's take a reasonable markup source
> language which has lots of tools to translate it into other formats, and
> add a layer on top to support domain-specific markup.  We picked GNU
> texinfo as a decent source form, from which text, HTML, Info, and
> Postscript could be produced.  We then added a preprocessor layer to
> translate domain-specific terms such as `@isl' (used to mark an ILU ISL
> literal), to the domain-independent terms used by texinfo; for example,
> `@isl' is translated to `@code'.  The preprocessor also drives the
> transformation from texinfo to the desired output format, thereby
> freeing the user from having to remember how to run TeX, etc.  Finally,
> two domain-independent features are provided by TIM, and implemented in
> the preprocessor.  They are the ability to include pictures in texinfo,
> and the ability to add URL links.

I like this idea a lot.

--Guido van Rossum (home page: http://www.python.org/~guido/)

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From amk@magnet.com  Wed Aug 14 21:59:34 1996
From: amk@magnet.com (Andrew Kuchling)
Date: Wed, 14 Aug 1996 16:59:34 -0400 (EDT)
Subject: [PYTHON DOC-SIG] Documentation format
In-Reply-To: <199608141930.PAA06808@monty> from "Guido van Rossum" at Aug 14, 96 03:30:16 pm
Message-ID: <199608142059.QAA00845@lemur.magnet.com>

Guido van Rossum wrote:
> never be contained in docstrings).  How feasible is @texinfo or ILU's
> TIM (which looks like an extension of @texinfo)?

	I wrote my SSLeay documentation in Texinfo, and it was no
difficulty; however, it's a lot smaller than the library reference.
Documentation for an object method looks like this:

@defmethod @r{SSLconn objects} use_certificate_file (@var{filename})
Set the X.509 certificate to be used; @var{filename} is the name of a
file containing an X.509 certificate encoded in PEM format.
@end defmethod

	The HTML output looks like this in Lynx:

   use_certificate_file (filename) -- Method on SSLconn objects
          Set the X.509 certificate to be used; filename is the name
          of a file containing an X.509 certificate encoded in PEM 
          format.

	We'd still need to think about things like default values and
keyword arguments.  Perhaps something like (following TIM's lead):

@defmethod @r{object} func (@keyword{filename} filename @default{@file{/etc/passwd}})
  ...text...
Not very readable, is it?    Anyway, it could then be formatted
into something like:
   
  func (filename= filename [/etc/passwd] )
        ...text...

	(There may be a good argument to be made for putting default
argument values into the text here.  Ah well, that's a typographical
question independent of the formatter used.)


	Andrew Kuchling
	amk@magnet.com

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From janssen@parc.xerox.com  Wed Aug 14 22:53:52 1996
From: janssen@parc.xerox.com (Bill Janssen)
Date: Wed, 14 Aug 1996 14:53:52 PDT
Subject: [PYTHON DOC-SIG] Bill Janssen suggested...
In-Reply-To: <199608141932.PAA06820@monty>
References: 
 <199608141932.PAA06820@monty>
Message-ID: 

The missing part is a generalization of the specific tools we've written
for ILU.  Right now, a Perl script translates our ILU-specific markup
into the texinfo generic markup, with the translations hard-wired into
the script.  This should be re-written as a Python program which takes
arbitrary macro definitions of the form

	@macro				

which means ``translate the markup @{foobar} into
@{foobar}'', and simply replaces them.  So the documentation
writer would write

	...and so we can see that the function @Python{@fn{foobar}} will cause
effects which...

and what the already existing texinfo processors will see is

	...and so we can see that the function @code{@code{foobar}} will cause
effects which...

Bill

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From janssen@parc.xerox.com  Wed Aug 14 23:02:48 1996
From: janssen@parc.xerox.com (Bill Janssen)
Date: Wed, 14 Aug 1996 15:02:48 PDT
Subject: [PYTHON DOC-SIG] Documentation format
In-Reply-To: <199608141937.PAA06835@monty>
References: <199608132226.SAA07622@lemur.magnet.com>
 <199608141937.PAA06835@monty>
Message-ID: 

On a project I was working on at MCC, we used our own markup language,
called DML, which was a lot like LaTeX, and generated MIF from that for
FrameMaker (as well as generating Info, and doc-strings (yes, the other
way around), and so forth).

Bill

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Wed Aug 14 23:22:15 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Wed, 14 Aug 1996 17:22:15 -0500
Subject: [PYTHON DOC-SIG] Documentation format
Message-ID: <199608142222.RAA17427@darwin.rsoc.rockwell.com>

   Andy: Better make sure Guido has access to it, though.
   Guido:
|> I do, and I like Frame a lot.  What you say here also makes me feel
|> more comfortable with Frame's non-free status; however the free HTML
|> generation sucks.

I know. What we have done here is use the niffy free tool fm2html.
It's a perl:( thing which orchastrates the various data graphic 
conversions and table conversion needed. Adobe has a new tool they
call HoTaMaLe which supposedly does nicely at HTML. I haven't tried
it yet as it requires Frame5.1. Downloadable from www.adobe.com.
It's free now but I don't know how long it'll last. I don't expect it
to be expensive though.

As I mentioned before, I tried converting the .tex docs to FrameMaker.
I've finished the Tutorial today just to see how involved it is and
it turned out nicely. Only about 2 hours (because I spruced it up some).
I'll sent it to you under separate email. See what you think.

I picked the tutorial doc because it doesn't involve indexes.
Given the power of Framemaker I can image some very nice polished
(professional looking) documents to show for ourselves. (Someone
might even pay for them in their Frame native format so they could
integrate it into their production documentation systems;-)


=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From klm@CNRI.Reston.Va.US  Wed Aug 14 23:42:09 1996
From: klm@CNRI.Reston.Va.US (Ken Manheimer)
Date: Wed, 14 Aug 1996 18:42:09 -0400 (EDT)
Subject: [PYTHON DOC-SIG] Bill Janssen suggested...
In-Reply-To: 
Message-ID: 

On Wed, 14 Aug 1996, Bill Janssen wrote:

> The missing part is a generalization of the specific tools we've written
> for ILU.  Right now, a Perl script translates our ILU-specific markup
> into the texinfo generic markup, with the translations hard-wired into
> the script.  This should be re-written as a Python program which takes
> arbitrary macro definitions of the form
> 
> 	@macro				
> 
> which means ``translate the markup @{foobar} into
> @{foobar}'', and simply replaces them.  So the documentation

As i recall, after the third conference we were pretty sold on going with
TIM, but didn't get anywhere with it because noone resolved this step.  It
sounds like we're getting stopped by a small thing - if only someone 
had time to take on this task.  !

Ken Manheimer		klm@cnri.reston.va.us	    703 620-8990 x268
	    (orporation for National Research |nitiatives

	# If you appreciate Python, consider joining the PSA #
		  # . #


=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From skip@calendar.com (Skip Montanaro)  Tue Aug 20 20:14:00 1996
From: skip@calendar.com (Skip Montanaro) (Skip Montanaro)
Date: Tue, 20 Aug 1996 15:14:00 -0400
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
In-Reply-To: <199608201852.OAA13736@monty>
References: <199608201835.OAA07526@dolphin.automatrix.com>
 <199608201852.OAA13736@monty>
Message-ID: <199608201914.PAA07706@dolphin.automatrix.com>

Okay, Guido agrees the docs I'm looking for are needed:

   > I haven't been able to find any sort of reference or user documentation for
   > the Python C API other than the extending/embedding manual and the comments
   > in Include/abstract.h.  Does anything else exist? ...

   Someone just donated a LaTeX file containing a translation from
   abstract.h (mostly), but apart from that, this stuff is still sorely
   missing...

   > At this point I'm mostly interested in a reference document ...
   > Longer term, I'd like to see some user documentation with short code
   > examples ...
   
   All totally agreed...  We need more volunteer help to complete this
   job!

I'd like to generate one or more template documents automatically from the C
source or some other easily created template file that I can then make
available to people with an interest in completing individual sections.  I
don't want to get into a quagmire right off the bat, so I will initially
move this discussion from the main list to the doc-sig@python.org list.
(Don't worry, I'll move it back when I need more help... :-) Would someone
involved with the DOC-SIG (Michael McLay perhaps?)  give me a quick
brain-dump of the current state of the musings on the DOC-SIG, especially
about issues of documentation format, input source, etc?  I've subscribed to
the doc-sig at this point, so further discussion should take place there.
I'll also try and wade through the list's archives.

Thx,

Skip Montanaro     |   Musi-Cal: http://concerts.calendar.com/
skip@calendar.com  |   Conference Calendar: http://conferences.calendar.com/
(518)372-5583      |   Python: http://www.python.org/

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Tue Aug 20 21:05:06 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Tue, 20 Aug 1996 15:05:06 -0500
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
Message-ID: <199608202005.PAA26554@darwin.rsoc.rockwell.com>

|> From: Skip Montanaro 
|> 
|> Okay, Guido agrees the docs I'm looking for are needed:
|> 
|>    > I haven't been able to find any sort of reference or user documentation for
|>    > the Python C API other than the extending/embedding manual and the comments
|>    > in Include/abstract.h.  Does anything else exist? ...
|> 
|>    Someone just donated a LaTeX file containing a translation from
|>    abstract.h (mostly), but apart from that, this stuff is still sorely
|>    missing...
|> 
|>    > At this point I'm mostly interested in a reference document ...
|>    > Longer term, I'd like to see some user documentation with short code
|>    > examples ...
|>    
|>    All totally agreed...  We need more volunteer help to complete this
|>    job!

The user documentation you seek will probably be met by the two books 
to be on the bookselves RSN;-)  As for the definitive reference, I agree
100%; we need a big upgrade to the Extending & Embedding docs.

|> 
|> I'd like to generate one or more template documents automatically from the C
|> source or some other easily created template file that I can then make
|> available to people with an interest in completing individual sections.  I
|> don't want to get into a quagmire right off the bat, so I will initially
|> move this discussion from the main list to the doc-sig@python.org list.
|> (Don't worry, I'll move it back when I need more help... :-) Would someone
|> involved with the DOC-SIG (Michael McLay perhaps?)  give me a quick
|> brain-dump of the current state of the musings on the DOC-SIG, especially
|> about issues of documentation format, input source, etc?  I've subscribed to
|> the doc-sig at this point, so further discussion should take place there.
|> I'll also try and wade through the list's archives.
|> 
|> Thx,
|> 
|> Skip Montanaro   

The skinny recently has been the proposition that we come up with a 
new standard documentation format for the distribution docs. Currently
things are baselined in LaTeX and other formats are spun off from that.
I have argued that we should switch over to FrameMaker as the baseline
tool. As I sit here I am working to steamline such an effort with some
tools to aid the LaTeX->FrameMaker conversion. (Already finished the 
tutorial but that was easy as it didn't have an index.) At this point
I would recommend _not_ using LaTeX markup. If we/you create a tool
to generate docs for the API let's tune it for FrameMaker. We could 
either use the MML (maker markup language) or go through MIF (maker
interchange format). The former is a very simple paragraph markup
resembling HTML and the later is a full blown markup supporting
everything Frame supports.

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Tue Aug 20 21:33:49 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Tue, 20 Aug 1996 22:33:49 +0200
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
In-Reply-To: <199608201914.PAA07706@dolphin.automatrix.com> (message from Skip
 Montanaro on Tue, 20 Aug 1996 15:14:00 -0400)
Message-ID: <9608202033.AA21712@arnold.image.ivab.se>


> I will initially move this discussion from the main list to the
> doc-sig@python.org list.

Ok, I'll better hang on :-)

> I'd like to generate one or more template documents automatically
> from the C source or some other easily created template file that I
> can then make available to people with an interest in completing
> individual sections.

Here's a start...

#
# translate rename2.h into a simple document template

import string

entries = []
for s in open("rename2.h").readlines():
    s = string.split(s)
    if len(s) == 3 and s[0] == "#define":
	entries.append((s[2], s[1]))

entries.sort()

for n, o in entries:
	print n
	print
	print "\tThis function ..."
	print
	print "\tOld name: %s" % o
	print

	/F

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From mclay@eeel.nist.gov  Tue Aug 20 16:30:47 1996
From: mclay@eeel.nist.gov (Michael McLay)
Date: Tue, 20 Aug 1996 15:30:47 GMT
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
In-Reply-To: <199608201914.PAA07706@dolphin.automatrix.com>
References: <199608201835.OAA07526@dolphin.automatrix.com>
 <199608201852.OAA13736@monty>
 <199608201914.PAA07706@dolphin.automatrix.com>
Message-ID: <199608201530.PAA01439@fermi.eeel.nist.gov>

Skip Montanaro writes:
 > 
 > I'd like to generate one or more template documents automatically from the C
 > source or some other easily created template file that I can then make
 > available to people with an interest in completing individual sections.  I
 > don't want to get into a quagmire right off the bat, so I will initially
 > move this discussion from the main list to the doc-sig@python.org list.
 > (Don't worry, I'll move it back when I need more help... :-) Would someone
 > involved with the DOC-SIG (Michael McLay perhaps?)  give me a quick
 > brain-dump of the current state of the musings on the DOC-SIG, especially
 > about issues of documentation format, input source, etc?  

Robin's answer covered what's been discussed lately on the WWW pages.
I am a bit concerned about standardizing on Framemaker.  I've watch my
organization "standardize" on two commercial products for
wordprocessing.  There are definite pitfalls in picking a vendor.
An immediate problem is that Framemaker isn't universally available
this choice will limit who can participate in the documentation project.

I just read about another possible option.  YODL is described as:

  nsect(What's YODL?)

    YODL (Yet Oneother Document Language) is a package that consists of
    programs, some shell scripts, and auxiliary "lib" files for which hold
    macro files. The whole purpose of the package is to provide a
    simple-to-use and extensible document language, that can be used to
    convert documents in the YODL format to a variety of other formats. In
    this purpose, YODL somewhat resembles generic markup languages, e.g. SGML
    footnote(Standard Generalized Markup Language) but:

The paragraph is in YODL notation.  I'm not advocating it.  I just
thought it might be of interest.

How about writing the documentation in Python?  That should be
flexible enough.  It also shouldn't take too much to add a minimal GUI
front end so you don't have to write lots of special notation
characters.  If the objects were massaged properly the html2ps.py
filter could be used to output the documents to a postscript printer.

Michael

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Tue Aug 20 21:59:52 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Tue, 20 Aug 1996 22:59:52 +0200
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
In-Reply-To: <199608201530.PAA01439@fermi.eeel.nist.gov> (mclay@eeel.nist.gov)
Message-ID: <9608202059.AA07439@arnold.image.ivab.se>


> An immediate problem is that Framemaker isn't universally available
> this choice will limit who can participate in the documentation project.

True.  Rule me out, for example.

 Being an ex-technical writer/graphics designer, I don't see why we
cannot just use plain old ASCII editors to write the core reference
stuff.  A reference manual really doesn't need much fancy formatting;
its more important to make it easy for anyone to contribute than to
get a tool that allows you do all sorts of formatting stunts from the
beginning.

I'd vote for something very simple:

int
PyArg_GetChar(PyObject* args, int nargs, int i, char* p_arg)

	If _args_ can be interpreted as a character, copy it to
	p_arg[0] and return 1.  Otherwise, raise an exception
	and return 0.

	For details on the other arguments, see _PyArg_GetObject_.

	Old name: _getichararg_

int
PyArg_GetDoubleArray(PyObject* args, int nargs, int i, int n, double* p_arg)

	If _args_ can be interpreted as an array of floating
	point values of length _n_, extract it to _p_arg[0..n-1]_
	and return 1.  Otherwise, raise an exception and return
	0.

	Args can be either a tuple or a sequence.

	For details on the other arguments, see _PyArg_GetObject_.

	Old name: _getidoublearray_

Add a python script that create headings for each function, renders
the function names in boldface and the arguments in italics, and
outputs it all in HTML:


PyArg_GetDoubleArray


int

PyArg_GetDoubleArray(PyObject* args, int nargs, int i, int n, double* p_arg)


If args can be interpreted as an array of floating
point values of length n, extract it to p_arg[0..n-1]
and return 1.  Otherwise, raise an exception and return
0.


Args can be either a tuple or a sequence.


For details on the other arguments, see PyArg_GetObject.


Old name: getidoublearray



>From there, you can convert it to whatever, and add cross-references,
"see alsos", etc.  Anyone not happy with this can write in whatever
tool he prefers, and convert from there to HTML.  The only thing that
needs to be agreed on is the basic layout issues (mainly if and where
to use boldface/italic...).

And hey, my new mail client allows me to write directly in HTML :-)

	/F

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From skip@calendar.com (Skip Montanaro)  Tue Aug 20 22:23:56 1996
From: skip@calendar.com (Skip Montanaro) (Skip Montanaro)
Date: Tue, 20 Aug 1996 17:23:56 -0400
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
In-Reply-To: <199608202005.PAA26554@darwin.rsoc.rockwell.com>
References: <199608202005.PAA26554@darwin.rsoc.rockwell.com>
Message-ID: <199608202123.RAA08166@dolphin.automatrix.com>

   
Robin wrote:

   I have argued that we should switch over to FrameMaker as the baseline
   tool.

I'm sure FrameMaker is a terrific piece of software.  I even used it
occasionally in my days at GE. However, I simply can't afford to purchase it
(or anything else) at this point.

Generally speaking, I can't see how it benefits a free piece of software to
have its documentation developed using a proprietary word processor, even
something as ubiquitous as Microsoft Word (which I also can't afford at the
moment).  Others who might be cajoled into working on the documentation
might well be put off -- as am I -- at the thought of having to spend money
to support free software.

To Michael McLay's point, I'm also not too interested in writing a bunch of
Python code just to document existing C code.  (Maybe I misunderstood
something.)  Writing is writing.  Programming is programming.  Many (all?)
of the functions and data to be documented are not going to be visible to
tools like gendoc, so doc strings (if that's what you had in mind) won't cut
it.  Nor am I interested in learning a new text processing system just for
this project.  My day-to-day exposure to various text processors tends to be
rather minimal, so I'd rather stick with something I know, however vaguely.

My first choice would be LaTeX or texinfo.  I believe all the existing
Python documentation is written in LaTeX.  It's freely available on a wide
variety of platforms.  If people decide later on to move to something else
altogether, then the effort of converting existing documentation to a new
text processing system will be minimized by having only one source format to
convert.

The only other obvious alternative I see is HTML.  It's big disadvantage is
that it's a moving target.  LaTeX is much more stable, and you can use tools
like latex2html (or latex2frame, or ...) to generate other formats like
HTML.

Skip Montanaro     |   Musi-Cal: http://concerts.calendar.com/
skip@calendar.com  |   Conference Calendar: http://conferences.calendar.com/
(518)372-5583      |   Python: http://www.python.org/

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Tue Aug 20 22:33:03 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Tue, 20 Aug 1996 16:33:03 -0500
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
Message-ID: <199608202133.QAA26582@darwin.rsoc.rockwell.com>

|> From: Fredrik Lundh 
|> 
|>   From: Michael McLay
|> > An immediate problem is that Framemaker isn't universally available
|> > this choice will limit who can participate in the documentation project.
|> 
|> True.  Rule me out, for example.

Untrue. A Framemaker standard would apply to the primary printed format
and doesn't limit the methods/formats used in the authoring phase. There's
nothing to say that we can't do just what Fredrik states. Once the text
is written/generated then it would be imported into Frame to generate
the printed/indexed/postscript version. Relying on cobbled together free
tools pieces for the whole job is just unnecessary. Anyone can write the
doc inputs in text and hand it over to someone with Framemaker for the
integration. I just didn't want to see the distribution docs, which are
currently nicely typeset in latex, in a reduced quality format. There's
no need to reinvent the wheel here. This doen't mean that everyone helping
with the doc projects will need Framemaker, just the docmaster.
I agree with Fredrik's approach for the C API programmer reference, 
but I just don't want to stop there. I tend to use the printed docs
much more than the various online references and I don't see that changing.
-Robin

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Tue Aug 20 22:40:26 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Tue, 20 Aug 1996 23:40:26 +0200
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
Message-ID: <9608202138.AA07752@arnold.image.ivab.se>

This is a multi-part message in MIME format.

------=_NextPart_000_01BB8EF0.F670BF60
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

Skip wrote:
> The only other obvious alternative I see is HTML.  It's big
> disadvantage is that it's a moving target.

Well, I don't think the basics will change any time soon. And as I
hinted in my last mail, even mail clients include HTML editors nowadays.

AMAZING, ISN'T IT?

Regards /F


------=_NextPart_000_01BB8EF0.F670BF60
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable


Skip wrote:
> The =
only other obvious alternative I see is HTML.  It's big
> =
disadvantage is that it's a moving target.

Well, I don't =
think the basics will change any time soon. And as I
hinted in my =
last mail, even mail clients include HTML editors nowadays.



  • AMAZING, ISN'T IT?



Regards /F




------=_NextPart_000_01BB8EF0.F670BF60--


=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Tue Aug 20 23:30:13 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Wed, 21 Aug 1996 00:30:13 +0200
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
In-Reply-To: <199608202133.QAA26582@darwin.rsoc.rockwell.com>
 (friedric@rose.rsoc.rockwell.com)
Message-ID: <9608202230.AA25574@arnold.image.ivab.se>


Robin writes:

> A Framemaker standard would apply to the primary printed format and
> doesn't limit the methods/formats used in the authoring
> phase. There's nothing to say that we can't do just what Fredrik
> states. Once the text is written/generated then it would be imported
> into Frame to generate the printed/indexed/postscript version.

Which is exactly what I tried to say :-)

Okay, I couldn't resist trying out my own little concept.  Here's a
somewhat terse (and incomplete) version of the PyArg group of
functions.

So, what do you think?  What more need to be described for each
function?  Is the formatting ok?  Etc, etc...

	/F

--------------------------------------------------------------------

Source (for one function):

int
PyArg_GetChar(PyObject* args, int nargs, int i, char* p_arg)

	If _args[i]_ can be interpreted as a character, extract it to
	_p_arg[0]_ and return 1.  Otherwise, raise an exception
	and return 0.

	_Args[i]_ should be a string of length 1.

	Old name: _getichararg_

Formatted result (more functions):


PyArg_GetChar

int

PyArg_GetChar(PyObject* args, int nargs, int i, char* p_arg)




    
If args[i] can be interpreted as a character, extract it to
p_arg[0] and return 1. Otherwise, raise an exception
and return 0.

    
Args[i] should be a string of length 1.

    
Old name: getichararg

    



PyArg_GetDoubleArray

int

PyArg_GetDoubleArray(PyObject* args, int nargs, int i, int n, double* p_arg)




    
If args[i] can be interpreted as an array of floating
point values of length n, extract it to p_arg[0..n-1]
and return 1. Otherwise, raise an exception and return
0.

    
Args[i] can be either a tuple or a sequence, of length n.

    
Old name: getidoublearray

    



PyArg_GetFloat

int

PyArg_GetFloat(PyObject* args, int nargs, int i, float* p_arg)




    
If args[i] can be interpreted as a floating point value,
extract it to p_arg[0] and return 1. Otherwise, raise an
exception and return 0.

    
Old name: getifloatarg

    



PyArg_GetFloatArray

int

PyArg_GetFloatArray(PyObject* args, int nargs, int i, int n, float* p_arg)




    
Same as PyArg_GetDoubleArg, but extracts data to a
float array instead.

    
Old name: getifloatarray

    



PyArg_GetLong

int

PyArg_GetLong(PyObject* args, int nargs, int i, long* p_arg)




    
If args[i] can be interpreted as an integer, extract it
to p_arg[0] and return 1. Otherwise, raise an exception
and return 0.

    
Old name: getilongarg

    



PyArg_GetLongArray

int

PyArg_GetLongArray(PyObject* args, int nargs, int i, int n, long* p_arg)






PyArg_GetLongArraySize

int

PyArg_GetLongArraySize(PyObject* args, int nargs, int i, long* p_arg)




    
If args[i] can interpreted as a sequence, extract the
length to p_arg[0] and return 1. Otherwise, raise an
exception and return 0.

    
Args[i] can be either a list or a tuple.

    
Old name: getilongarraysize

    



PyArg_GetObject

int

PyArg_GetObject(PyObject* args, int nargs, int i, PyObject** p_arg)




    
Copy args[i] into p_arg[0], and return 1. If the argument
does not exist, raise an exception and return 0. Note that
args is either a single object (_n_ = 1), or a tuple of
arguments.

    
Old name: getiobjectarg

    



PyArg_GetShort

int

PyArg_GetShort(PyObject* args, int nargs, int i, int n, float* p_arg)




    
If args[i] can be interpreted as an integer, extract it
to p_arg[0] and return 1. Otherwise, raise an exception
and return 0.

    
Old name: getishortarg

    



PyArg_GetShortArray

int

PyArg_GetShortArray(PyObject* args, int nargs, int i, int n, float* p_arg)




    
Same as PyArg_GetDoubleArray, but extracts data to a
short array instead.

    
Old name: getishortarray

    



PyArg_GetShortArraySize

int

PyArg_GetShortArraySize(PyObject* args, int nargs, int i, short* p_arg)




    
Same a PyArg_GetLongArraySize, but returns the length
as a short instead.

    
FIXME: what happens if the size exceeds 32k?

    
Old name: getishortarraysize

    



PyArg_GetString

PyArg_GetString()




    
FIXME

    
Old name: getistringarg

    



PyArg_NoArgs

PyArg_NoArgs()




    
FIXME

    
Old name: getnoarg

    



PyArg_Parse

PyArg_Parse()




    
FIXME

    
Old name: getargs

    



PyArg_ParseTuple

PyArg_ParseTuple()




    
FIXME

    
Old name: newgetargs

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Wed Aug 21 03:53:16 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Wed, 21 Aug 1996 04:53:16 +0200
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a1, or something
Message-ID: <9608210253.AA07922@arnold.image.ivab.se>


Okay, I'm intentionally misusing the image-sig corner on python.org,
but here we go anyway:

	http://www.python.org/sigs/image-sig/PyCAPI.html

Far from complete and very rough, but probably enough to begin
discussing the style and layout, as well as the content itself.

	/F

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Wed Aug 21 03:53:16 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Wed, 21 Aug 1996 04:53:16 +0200
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a1, or something
Message-ID: <9608210253.AA07922@arnold.image.ivab.se>


Okay, I'm intentionally misusing the image-sig corner on python.org,
but here we go anyway:

	http://www.python.org/sigs/image-sig/PyCAPI.html

Far from complete and very rough, but probably enough to begin
discussing the style and layout, as well as the content itself.

	/F

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Wed Aug 21 13:53:02 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Wed, 21 Aug 1996 07:53:02 -0500
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a1, or something
Message-ID: <199608211253.HAA27363@darwin.rsoc.rockwell.com>

|> 
|> Okay, I'm intentionally misusing the image-sig corner on python.org,
|> but here we go anyway:
|> 
|> 	http://www.python.org/sigs/image-sig/PyCAPI.html

Cool. Great start. I like the format so far. Also, maybe a crossref index
where you can look at it sorted by new name or old name can be generated.
Can someone move the html over to the doc sig area or make a symlink?

(also HTMLgen is available for this kind of thing <0.6wink>.)

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Wed Aug 21 14:15:09 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Wed, 21 Aug 1996 15:15:09 +0200
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a1, or something
In-Reply-To: <199608211253.HAA27363@darwin.rsoc.rockwell.com>
 (friedric@rose.rsoc.rockwell.com)
Message-ID: <9608211315.AA10208@arnold.image.ivab.se>


>
> maybe a crossref index where you can look at it sorted by new name
> or old name can be generated.

I'll fix that.

>
> Can someone move the html over to the doc sig area or make a symlink?

Hmm.  Since I've hardly read it myself, I'd prefer to make one more
rush through it before publishing it for a larger audience (could be a
good idea to at least complete the APIs for the most commonly used
objects).  I'll let you know :-)

>
> also HTMLgen is available for this kind of thing <0.6wink>.

Yep, I promise to take a look on that some day.  Have a project coming
up where I don't think I can do without it.

	/F

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Wed Aug 21 14:15:09 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Wed, 21 Aug 1996 15:15:09 +0200
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a1, or something
In-Reply-To: <199608211253.HAA27363@darwin.rsoc.rockwell.com>
 (friedric@rose.rsoc.rockwell.com)
Message-ID: <9608211315.AA10208@arnold.image.ivab.se>


>
> maybe a crossref index where you can look at it sorted by new name
> or old name can be generated.

I'll fix that.

>
> Can someone move the html over to the doc sig area or make a symlink?

Hmm.  Since I've hardly read it myself, I'd prefer to make one more
rush through it before publishing it for a larger audience (could be a
good idea to at least complete the APIs for the most commonly used
objects).  I'll let you know :-)

>
> also HTMLgen is available for this kind of thing <0.6wink>.

Yep, I promise to take a look on that some day.  Have a project coming
up where I don't think I can do without it.

	/F

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Wed Aug 21 16:23:08 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Wed, 21 Aug 1996 17:23:08 +0200
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)
Message-ID: <9608211523.AA12514@arnold.image.ivab.se>


Same address: http://www.python.org/sigs/image-sig/PyCAPI.html

Corrections and more comments are welcome.

	/F

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From skip@calendar.com (Skip Montanaro)  Wed Aug 21 18:56:02 1996
From: skip@calendar.com (Skip Montanaro) (Skip Montanaro)
Date: Wed, 21 Aug 1996 13:56:02 -0400
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)
In-Reply-To: <9608211523.AA12514@arnold.image.ivab.se>
References: <9608211523.AA12514@arnold.image.ivab.se>
Message-ID: <199608211756.NAA15693@dolphin.automatrix.com>


Fredrik,
   
I took a quick look at your second pass.  What's there looks fine.  It's
moving too fast for me to edit and send back to you for comments.  Here are
some observations.

    1. One of the most critical pieces of information to document is
    reference counting behavior of the various functions.  It's the most
    difficult thing for a programmer to get right.  For each function input
    and output I'd like to know if references are consumed or produced by
    the function, for instance.

    2. While it's easy to get at the old names from rename2.h, I think they
    should be deprecated, perhaps not even documented at this point other
    than to have a link from, say, newlongobject to PyLong_FromLong in a
    function index.

    3. I'd like the most commonly used stuff documented first.  In my
    limited experience that would be things like argument passing (PyArg*),
    sequence (PySequence*, PyList*, PyTuple*) and mapping (PyMapping*,
    PyDict*) Get/Set/Slice functions, and object creation. Every module
    function has to deal with one or more of those areas to some degree.
    Many of the other C API names appear much less frequently in common
    usage, and may even not be meant for general programmer use, but are
    just meant for communication between different parts of the run-time
    system.

    4. I still think LaTeX or TeXinfo would be better vehicles for the
    actual text processing than HTML.  For one thing, TeX and it's various
    spinoff macro packages already have good cross-reference and index
    features.  I believe tools like latex2html can take advantage of them to
    generate links and indexes in generated HTML.

    5. I'd like to see a more stratified top-level structure, something
    like:

	Introduction
	    Terminology
		Owned vs. borrowed references
		...

	Types
	    PyFloat_Type
	    ...
	    Type Checking
		PyCallable_Check
		...

	Data Items
	    Py_True
	    Py_False
	    Py_None
	    Exceptions
		PyExc_IndexError
		...
	    Builtin Objects
		PyFloatObject
		...
		Object Macros
		    PyObject_HEAD
		    ...

	Reference Counting
	    Py_INCREF
	    ...

	Functions
	    Abstract Interface
		Object Protocol
		    PyObject_HasAttrString
		    ...

	    Argument Passing
		PyArg_ParseTuple
		...

	    List Functions
		PyList_Append
		...

	    Mapping Functions
	    Numeric Functions
	    String Functions
	    ...

    I think your current document starts to flesh out the Functions section
    of the above outline.

Skip Montanaro     |   Musi-Cal: http://concerts.calendar.com/
skip@calendar.com  |   Conference Calendar: http://conferences.calendar.com/
(518)372-5583      |   Python: http://www.python.org/

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From guido@CNRI.Reston.Va.US  Wed Aug 21 19:28:46 1996
From: guido@CNRI.Reston.Va.US (Guido van Rossum)
Date: Wed, 21 Aug 1996 14:28:46 -0400
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)
In-Reply-To: Your message of "Wed, 21 Aug 1996 13:56:02 EDT."
 <199608211756.NAA15693@dolphin.automatrix.com>
References: <9608211523.AA12514@arnold.image.ivab.se>
 <199608211756.NAA15693@dolphin.automatrix.com>
Message-ID: <199608211828.OAA03572@monty>

>     1. One of the most critical pieces of information to document is
>     reference counting behavior of the various functions.  It's the most
>     difficult thing for a programmer to get right.  For each function input
>     and output I'd like to know if references are consumed or produced by
>     the function, for instance.

Notice that the default is that no references are consumed on
arguments, and a reference is produced on output (thanks for this
terminology).  Only the deviations from this rule have to be noted.

>     3. I'd like the most commonly used stuff documented first.  In my
>     limited experience that would be things like argument passing (PyArg*),
>     sequence (PySequence*, PyList*, PyTuple*) and mapping (PyMapping*,
>     PyDict*) Get/Set/Slice functions, and object creation. Every module
>     function has to deal with one or more of those areas to some degree.
>     Many of the other C API names appear much less frequently in common
>     usage, and may even not be meant for general programmer use, but are
>     just meant for communication between different parts of the run-time
>     system.

Hmm, the abstrct interface makes use of these a lot less necessary.

BTW the PyArg_GetLong() etc. family of functions is not very useful --
they are mostly macros around the preferred PyArg_ParseTuple().

>     4. I still think LaTeX or TeXinfo would be better vehicles for the
>     actual text processing than HTML.  For one thing, TeX and it's various
>     spinoff macro packages already have good cross-reference and index
>     features.  I believe tools like latex2html can take advantage of them to
>     generate links and indexes in generated HTML.

This needs to be considered per manual.  For the library manual, at
the moment I think I agree.  For the tutorial and reference manual, I
think there should be one author (me) and FrameMaker is a serious
candidate.  For the extensions manual, I guess there are two parts --
the C API for which the same as for the library reference applies, and
the running text, which works more like a tutorial.  I guess the
proper thing to do is to split the Python C API off into a separate
manual!

--Guido van Rossum (home page: http://www.python.org/~guido/)

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From lutz@rmi.net  Wed Aug 21 22:40:00 1996
From: lutz@rmi.net (Mark Lutz)
Date: Wed, 21 Aug 96 15:40 MDT
Subject: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
Message-ID: 

>> [stuff about Python C API documentation]
> 
> I had been hoping that Mark Lutz' book would cover things in more detail
> than the existing Python docs -- is that wrong (Mark?)?
 
I suppose it depends on what you mean by "more detail".
 
Yes, my book does go beyond the docs, and discusses C integration in
considerable detail.  In fact, that was one of its original goals: to
provide the extra perspective and context you can't get from manuals.
 
OTOH, my book doesn't replace the manuals; it's not an exhaustive
reference to every "extern" symbol in the Python system.  I think
manuals are a better vehicle for that sort of documentation.
 
A few more details...
The O'Reilly book discusses C integration, by working through examples.
There's a C extension module, a C extension type, extension wrapper
classes, an enhanced embedded-call API, and case studies on embedding
Python in C/C++.  Commonly-used API tools are documented along the way.
 
But it doesn't exhaustively document _every_ C API symbol in detail.
That's material for a reference manual IMHO.  For one thing, such a
reference could add hundreds of pages to an already-huge book.  For
another, the C API changes often; manuals can handle this better.
 
Of course, there is alot of language reference material in my book too,
and it's possible that more might creep in over time.  Which will all
make much more sense when the book finally comes out next month :-).
 
So, my $0.02 -- I think a C API doc outside any book would be a very
useful thing.  Better still, if this material can be put online in
HTML form, it can provide links that a book can't.
 
> I'm not sure what it would mean to help, but I've been writing a reasonable
> number of sets of Python bindings to C over the last several months, and I'd be
> happy to help if I can.
 
Sounds like a volunteer! :-).  BTW, the doc sig mail-list is digging into
this too; check out "doc-sig-request@python.org", unless you already have.
 
Cheers,
Mark L.

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From anthony.baxter@aaii.oz.au  Thu Aug 22 04:31:54 1996
From: anthony.baxter@aaii.oz.au (anthony baxter)
Date: Thu, 22 Aug 1996 13:31:54 +1000
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)
In-Reply-To: Message from Fredrik Lundh of 1996-Aug-21 17:23:08,
 <9608211523.AA12514@arnold.image.ivab.se>
Message-ID: <199608220332.NAA18396@alamein>


Feel free to steal stuff from 
http://www.dgs.monash.edu.au/~anthony/python/docs.html

I started it ages ago, there's docs for PyDict*, PyFile*, PyInt* and
PyTuple*


(I want to know how Fredrik manages to find the time for all this! :)

Anthony

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From anthony.baxter@aaii.oz.au  Thu Aug 22 06:02:47 1996
From: anthony.baxter@aaii.oz.au (anthony baxter)
Date: Thu, 22 Aug 1996 15:02:47 +1000
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)
In-Reply-To: Message from Fredrik Lundh of 1996-Aug-21 17:23:08,
 <9608211523.AA12514@arnold.image.ivab.se>
Message-ID: <199608220502.PAA19327@alamein>


And on another note - the best way for this to be done would be for
people to be able to contribute individual functions - what's the best
way of doing this?

(I guess what I'm asking here is "what is the original format you're using 
for this?")

Anthony

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From fredrik_lundh@ivab.se  Thu Aug 22 09:32:03 1996
From: fredrik_lundh@ivab.se (Fredrik Lundh)
Date: Thu, 22 Aug 1996 10:32:03 +0200
Subject: [PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)
In-Reply-To: <199608220502.PAA19327@alamein> (message from anthony baxter on
 Thu, 22 Aug 1996 15:02:47 +1000)
Message-ID: <9608220832.AA19403@arnold.image.ivab.se>


Various people wrote various things:

> And on another note - the best way for this to be done would be for
> people to be able to contribute individual functions - what's the best
> way of doing this?

I use a plain text format; I'm not fluent in tex, and Word et al are
not as efficient as emacs for terse, kill/yank/macro-intensive editing
like this.  So I write plain text, and process it with a small Python
script to add the necessary formatting.  Here's a sample:

PyObject*
PyInstance_New(PyObject* class, PyObject* arg, PyObject* kw)

	Construct a new _class_ instance object.  If the class
	defines an __init__ method, it is called with _arg_ (a tuple)
	and _kw_ (a dictionary) as arguments.  Otherwise, an empty
	instance is created.

	Exceptions: _err_badcall_, _TypeError_ (constructor takes
	no arguments), _MemoryError_

	Old name: _newinstanceobject_

So to contribute, simply write things down in plain old ASCII using a
style similar to that in the document, use _underscore_ to mark which
words to highlight (the formatter chooses where to use boldface and
italics), and I'll fix the rest in no time at all.

>
> One of the most critical pieces of information to document is
> reference counting behavior of the various functions.  It's the most
> difficult thing for a programmer to get right.  For each function
> input and output I'd like to know if references are consumed or
> produced by the function, for instance.

As Guido answered, the library is usually very consistent in how
things are done.  When things have stabilised, and most of the
functions are covered, I'll add an introduction describing such common
behaviour, and stuff like the object implementation, etc.

>
> BTW the PyArg_GetLong() etc. family of functions is not very useful
> -- they are mostly macros around the preferred PyArg_ParseTuple().

This is important info.  When rushing through the header and source
files, its not always easy to quickly tell whats the preferred way to
do things, and whats internal/obsolete stuff.  We don't need a
Schulman for Python (not yet, at least ;-)

So more of this, please.

>
> I still think LaTeX or TeXinfo would be better vehicles for the
> actual text processing than HTML.  For one thing, TeX and it's
> various spinoff macro packages already have good cross-reference and
> index features.

Well, I wanted to avoid the usual tool-religous wars that tend to halt
many projects before they've even started, collaborative or not...
This far, I've spent some 4 hours on this (including the scripts); I
might be able to finish it off in less than 10 hours in total, but not
if someone forces me to learn one or more new tools in the process.
Its simply a matter of using the available time efficiently.  We can
always convert the stuff later.

(If that strategy isn't acceptable, feel free to write your own C
reference manual.  But if you use my text, don't forget mentioning my
name...)

>
> I'd like to see a more stratified top-level structure, something
> like:

Yep.  But that's obviously a much larger effort.

As for things like a full-blown C programmers reference with a good
narrative section, I think we should consider leaving that to the
professional publishers.  They have enormous resources when it comes
to formatting, copy-editing, indexing, etc; and the author gets a
little money for his efforts as well.  More Python books will
definitely not hurt Python, and more books are already underway.

Besides language tutorial/references, I'd say the aim should be to
keep the freely available documentation complete but terse.  Better to
spend that time on programming...

>
> I want to know how Fredrik manages to find the time for all this!

Well, I'm actually a group of people, working on similar things and
posting from a single account.  So when I contradict myself, say
something utterly stupid, or write very bad English, its probably
someone else.  Or something.

Cheers	/F

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From mclay@eeel.nist.gov  Thu Aug 22 13:22:48 1996
From: mclay@eeel.nist.gov (Michael McLay)
Date: Thu, 22 Aug 1996 12:22:48 GMT
Subject: [PYTHON DOC-SIG] doc string style question
Message-ID: <199608221222.MAA08295@fermi.eeel.nist.gov>


My docstring style keeps dithering since I haven't found a well
defined convention to follow.  Is there a WWW page on this that I've
missed?   What's the recommended style for writting doc strings inside
classes and function.  Here is a foo and a bar example that can be
used for discussing the issue:

class foo:
    """holds a foo, but if the doc string is long the lines needs
to be wrapped to the next line"""
    def foofunc(self):
	"""foofunc definitions can often be longer than one line.
Should they wrap and not indent"""


class bar:
    """holds a bar, but if the doc string is long the lines needs
	   to be wrapped to the next line"""
    def barfunc(self):
	"""barfunc definitions can often be longer than one line.
	   Should they wrap and indent"""

If indent is correct, should the next line be lined up with the first '"'
mark or the first character in the quote?


    def barfunc(self):
	"""barfunc definitions can often be longer than one line.
	   Should they wrap and indent"""

or 

    def barfunc(self):
	"""barfunc definitions can often be longer than one line.
        Should they wrap and indent"""

Opiniions?
 
Michael

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From klm@CNRI.Reston.Va.US  Thu Aug 22 18:45:42 1996
From: klm@CNRI.Reston.Va.US (Ken Manheimer)
Date: Thu, 22 Aug 1996 13:45:42 -0400 (EDT)
Subject: [PYTHON DOC-SIG] doc string style question
In-Reply-To: <199608221222.MAA08295@fermi.eeel.nist.gov>
Message-ID: 

On Thu, 22 Aug 1996, Michael McLay wrote:

> My docstring style keeps dithering since I haven't found a well
> defined convention to follow.  Is there a WWW page on this that I've
> missed?   What's the recommended style for writting doc strings inside
> classes and function.  Here is a foo and a bar example that can be
> [...]
>
>    def barfunc(self):
>	 """barfunc definitions can often be longer than one line.
>	    Should they wrap and indent"""
>
>or 
>
>    def barfunc(self):
>	 """barfunc definitions can often be longer than one line.
>        Should they wrap and indent"""
>
> Opiniions?

Python-mode offers some good hints along these lines, and not just by
coincidence.  For instance, i much prefer the latter, and that is the
one "endorsed" by python-mode.  Python-mode represents deliberate
coding-style design decisions, with influence from guido as well as tim,
barry, and others.  Let the mode wrap the lines for you, and use Ctrl-j
when you specifically want to include a newline, or use Ctrl-i for
existing lines. 

(There are some things not conveyed by the mode, eg that the docstring's
first line ideally is a terse, self-contained description, with
subsequent lines after a blank line and elaborating; or where in general
to put blank lines, etc.  It would be really nice to develop an explicit
style guide, but that will take a volunteer to coordinate it...)

Ken Manheimer		klm@cnri.reston.va.us	    703 620-8990 x268
	    (orporation for National Research |nitiatives

	# If you appreciate Python, consider joining the PSA! #
		  # . #


=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From friedric@rose.rsoc.rockwell.com  Thu Aug 22 19:00:32 1996
From: friedric@rose.rsoc.rockwell.com (Robin Friedrich)
Date: Thu, 22 Aug 1996 13:00:32 -0500
Subject: [PYTHON DOC-SIG] doc string style question
Message-ID: <199608221800.NAA00735@darwin.rsoc.rockwell.com>

|> From: mclay@eeel.nist.gov (Michael McLay)
|> 
|> My docstring style keeps dithering since I haven't found a well
|> defined convention to follow.  Is there a WWW page on this that I've
|> missed?   

No. but there should be when we can all converge on a tool.

|> What's the recommended style for writting doc strings inside
|> classes and function. 

I use the following style.

def mif_escape(text):
    """Substitute the appropriate tokens for problematic characters.
    
    As you can see the python-mode will wrap the
    verbose author's text to tab level 1 when the return is struck.
    """
    split = string.split
    join  = string.join

gendoc currently figures out the initial indent for the doc string
and strips it off the text body.
Also remember the "one liner" rule. The doc string should have the 
first line a summary of the purpose and the rest of the doc string 
is after a blank line.

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================

From sam@linus.mitre.org  Thu Aug 22 20:19:34 1996
From: sam@linus.mitre.org (Samuel L. Bayer)
Date: Thu, 22 Aug 1996 15:19:34 -0400
Subject: [PYTHON DOC-SIG] archives
Message-ID: <199608221919.PAA04902@gont.mitre.org>


Having just joined, can somebody tell me if this list is archived? 

Sam

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================