Mailman 3 September 1996 - Doc-SIG

[PYTHON DOC-SIG] New Module StructuredText
by Jim Fulton Sept. 20, 1996

Sept. 20, 1996

I've added logic so that paragraphs that end with '::' and that have subparagraphs introduce sample code. This was necessary becaus it sometimes doesn't make sense to end the introductory paragraph with the word 'example'. I propose that this be incorporated into gendoc. See: http://www.digicool.com/jim/python/StructuredText.html Jim -- Jim Fulton Digital Creations jim(a)digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ##

2 1

Re: [PYTHON DOC-SIG] New Module StructuredText
by friedric＠rose.rsoc.rockwell.com Sept. 19, 1996

Sept. 19, 1996

|> From owner-doc-sig(a)python.org Thu Sep 19 10:57 CDT 1996 |> Date: Thu, 19 Sep 1996 11:44:25 -0400 |> From: Jim Fulton <jim.fulton(a)digicool.com> |> Organization: Digital Creations, L.C. |> X-Mailer: Mozilla 3.0b5 (WinNT; I) |> Mime-Version: 1.0 |> To: doc-sig(a)python.org |> Subject: [PYTHON DOC-SIG] New Module StructuredText |> Sender: owner-doc-sig(a)python.org |> Content-Type: multipart/mixed; boundary="------------23206CC4745" |> Content-Length: 5522 |> |> I've added logic so that paragraphs that end with '::' and that have |> subparagraphs introduce sample code. This was necessary becaus it |> sometimes doesn't make sense to end the introductory paragraph with the |> word 'example'. I propose that this be incorporated into gendoc. Cool. You got my vote. |> |> See: http://www.digicool.com/jim/python/StructuredText.html |> |> Jim |> |> -- |> Jim Fulton Digital Creations |> jim(a)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(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0

[PYTHON DOC-SIG] HTMLgen and gendoc
by friedric＠rose.rsoc.rockwell.com Sept. 16, 1996

Sept. 16, 1996

In order to illustrate the results of gendoc 0.6 we've unpacked the HTMLgen online documentation on the python server so you can browse it directly. When you get there, click the Manual button to spawn a new browser with the framed manual autogenerated with gendoc's HTMLgen formatter module. http://www.python.org/sigs/web-sig/HTMLgen/html/main.html ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

4 3

Re: [PYTHON DOC-SIG] Structured documentation syntax
by friedric＠rose.rsoc.rockwell.com Sept. 13, 1996

Sept. 13, 1996

|> Date: Thu, 12 Sep 1996 09:42:47 -0400 |> From: Jim Fulton <jim.fulton(a)digicool.com> ... |> I like the idea of using []s. |> |> Furthermore, I can see a usage where instead of saying: |> |> blah blah blah [spam] blah blah |> |> .... |> |> .. [spam] http://... |> |> One could say: |> |> blah blah blah spam [42] blah blah |> |> .... |> |> .. [42] http://... |> |> Where "[42]" gets highlighted. Which I would fine more readable |> as text and just as readable as hypertext. |> |> It would also be useful to define a URL hierarchy for gendoc |> and allow relative references in footnotes, so that a doc string could |> include links to documentation for other objects in the same module |> or other modules. This would also help to reduce HTML dependencies. |> For example, relative references might work for info files as well. OK now where getting somewhere. Does anyone volunteer to hack something up to try out? ;-) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

4 3

Re: [PYTHON DOC-SIG] Structured documentation syntax
by friedric＠rose.rsoc.rockwell.com Sept. 12, 1996

Sept. 12, 1996

|> Date: Thu, 12 Sep 1996 23:52:11 +0900 |> From: Ka-Ping Yee <s-ping(a)orange.cv.tottori-u.ac.jp> |> |> Skip Montanaro wrote: |> > That was my thought also. I believe the "official" way to |> > distinguish URLs in otherwise plain ASCII text is with a |> > URL: prefix, as in: |> > |> > <URL:http://www.python.org/> |> |> It is, but (as i said in response to Ken M.) i thought we |> were talking about the hyperlinked *text*, not the URL. |> |> Jim Fulton wrote: |> > One could say: |> > |> > blah blah blah spam [42] blah blah |> > |> > .... |> > |> > .. [42] http://.. |> > |> > Where "[42]" gets highlighted. Which I would fine more readable |> > as text and just as readable as hypertext. |> |> This is exactly what i had in mind when i suggested [], as |> this kind of usage is fairly common practice. Sometimes the |> brackets contain numbers, sometimes small identifiers like |> [ROSSUM96], or the author can choose to just [use the flow] |> of text. |> |> Robin Friedrich wrote: |> > OK now where getting somewhere. Does anyone volunteer to |> > hack something up to try out? ;-) |> |> Sorry, but i thought gendoc already implemented this? It |> looks like all you'd have to do is change a couple of lines |> in docregex.py. |> ... |> Or am i missing something? I was refering to the internal reference scheme Jim had in mind. The external reference scheme is implimented and works fine. And yes, the above trivial change with make the delimiters brackets rather that quotes. This seems to be the consensus so it'll change in the next release. (or in your local copy) |> |> Unfortunately, i can't test this out because whenever i |> run 'gendoc', i always get |> |> Traceback (innermost last): |> File "./gendoc", line 2, in ? |> import ni |> File "/usr/local/lib/python1.4/ni.py", line 435, in ? |> install() |> . |> . |> . |> File "./__init__.py", line 1, in ? |> path = __.__path__[0] |> TypeError: unsubscriptable object |> |> I would like to see 'gendoc' in action, so if someone |> knows what's going wrong here, please let me know. |> (I'm using a recently-downloaded release 0.6.) |> OK this is a symptom of trying to run the gendoc script in place. It needs to be moved somewhere in your $PATH. The make install would do this, but you have to have GNU make:-( The gendoc directory should be in your PYTHONPATH. The gendoc script should be in your PATH. |> By the way, can i put in a plug for RE_SYNTAX_AWK |> here? They would be an awful lot easier to read, what |> with all the parentheses you don't have to backslash. Plug away:-) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0

Re: [PYTHON DOC-SIG] Structured documentation syntax
by friedric＠rose.rsoc.rockwell.com Sept. 12, 1996

Sept. 12, 1996

|> Date: Thu, 12 Sep 1996 10:14:42 -0400 |> From: Jim Fulton <jim.fulton(a)digicool.com> |> |> Robin Friedrich wrote: |> > OK now where getting somewhere. Does anyone volunteer to hack something |> > up to try out? ;-) |> |> Hm. Well, for the first part, "" -> [], I assume that this would be |> a fairly minor change. trivial. |> |> The second part needs some thinking by someone who is very familiar |> with the URL hierarchy defined by gendoc. (Is this documented |> somewhere?) My thought is that the hierarchy should be reviewed |> before any hacking takes place. To me, this feels like an exercise |> for the gendoc author. True. But he's in Barcelona for 4 weeks. Can we at least define the features/requirements for such a thing while he's gone? Other things he wondered outload to me was an approach for representing packages. Any thoughts? ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0

Re: [PYTHON DOC-SIG] Structured documentation syntax
by friedric＠rose.rsoc.rockwell.com Sept. 12, 1996

Sept. 12, 1996

|> From skip(a)automatrix.com Thu Sep 12 07:25 CDT 1996 |> Date: Thu, 12 Sep 1996 08:22:54 -0400 |> From: Skip Montanaro <skip(a)automatrix.com> |> To: klm(a)CNRI.Reston.Va.US |> Cc: Robin Friedrich <friedric(a)rose.rsoc.rockwell.com>, |> s-ping(a)orange.cv.tottori-u.ac.jp, doc-sig(a)python.org |> Subject: Re: [PYTHON DOC-SIG] Structured documentation syntax |> Reply-To: skip(a)calendar.com (Skip Montanaro) |> Content-Type: text |> Content-Length: 802 |> |> Ken Manheimer writes: |> |> Having not kept track of the specifics, i don't know what disqualifies |> what i would consider the obvious candidate - angle brackets, eg, |> "<http://www.python.org>". This is the way i've frequently seen URLs |> distinguished - is there a reason not to use them generally for |> hyperlinks? Maybe because they specifically imply URLs, or because |> they're already dedicated to some other purpose? |> |> That was my thought also. I believe the "official" way to distinguish URLs |> in otherwise plain ASCII text is with a URL: prefix, as in: |> |> <URL:http://www.python.org/> |> OK guys. Here's the reasoning. You want the doc string to be as easy to read and devoid of uninformative markups as possible. Placing the actual link address (which can be quite long) in the body of the doc string really hurts that. IMHO moving the link address to a footnote area solves this and still provides enough data for the processor to generate the appropriate HTML. That leaves only some kind of delimiter of what text is to be highlighted in the flow of the text. This I feel preserves the readability of the doc string for those reading source. This idea came from setext. -Robin ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

2 1

Re: [PYTHON DOC-SIG] Structured documentation syntax
by friedric＠rose.rsoc.rockwell.com Sept. 12, 1996

Sept. 12, 1996

|> From: Ka-Ping Yee <s-ping(a)orange.cv.tottori-u.ac.jp> |> To: Jim Fulton <jim.fulton(a)digicool.com> |> Cc: doc-sig(a)python.org |> Subject: Re: [PYTHON DOC-SIG] Structured documentation syntax |> |> Hi again. Given that the goal is to have a more flexible |> syntax, i can understand now why you chose to allow three |> kinds of list bullets, why it's better to leave double-quotes |> visible, and why we might as well allow "1 Heading" or |> "1. Heading" or "1.2 Heading" or "1.2. Heading". |> |> Thank you for the explanations. |> |> I was just expressing a personal preference about **emphasis**, |> *emphasis*, and _emphasis_, but i don't feel as strongly |> about that as Fredrik Lundh seems to. Just to clarify. Gendoc uses *emphasis* and **strong** to delineate text. The underscores were rejected partly because they are harder to segregate from normal Python names like __init__ which appear in doc strings often. |> |> Mostly, though, i do still feel that double-quotes aren't |> really the best choice for hyperlinks (and i don't think |> any existing doc strings contain hyperlinks, anyway). Are |> there typical uses of brackets, other than [references], |> that i haven't thought of? This is easy to change. I really didn't care, much I just picked double quotes out of the air. [] & {} would have worked as well. I have used this hyperlink feature in my doc strings and it works fine. |> |> Are there really many doc-strings already that use -- to |> make definition lists? I have seen very few definition-list |> structures anywhere, and those i have seen use just ":". |> I would prefer to avoid "--", but i guess i can live with it. I use them whenever I list out the parameters of the function and the public attributes. Is this an esthetic thing only or do you wish to really reserve it for emdash? |> |> I'm looking through Grail source while thinking about this. |> Noticed in a few places: maybe it would be safe to assume |> that an identifier followed by () is a function name, and |> thus treat it as <code> (and possibly hyperlink it)? |> Specifically, this regex: |> |> [A-Za-z_]+(\.[A-Za-z_]+)* |> |> using AWK syntax. |> The gendoc approach is not to parse through the source files (unless you use the -p option) at all. It lets python import do that and then just walk through the symbol dictionaries to collect doc strings. So no assumptions need to be made. In fact gendoc does generate hyperlinks for other functions/modules. See http://www.python.org/sigs/web-sig/HTMLgen/html/index.html |> |> I was glad to hear that there's a convention for function |> documentation. I was about to propose something specific. |> To make the one-line description consistent in its form, |> i was thinking of: |> |> nouns (classes, attributes, variables): |> Use an object phrase, e.g. "a can of spam" |> |> verbs (functions, methods): |> Use the imperative form, e.g. "Count to (exactly) three." |> Format as a complete sentence (capital and period). |> |> > For Python functions there are function object attributes for |> > getting function argument names and defaults. |> |> Yes, but their descriptions would still be in the doc-string, right? Well this is debateble by some but I agree with you on this. |> |> > For more complex functions, I use somthing like: |> > |> > The arguments to this function are: |> > |> > foo -- description of foo |> > |> > bar -- description of bar |> > |> > def1 -- description of def1, including the default value |> > |> > def2 -- description of def2, including the default value |> > |> > Note that this is very readable as text and will be converted to |> > a nice descriptive list in HTML. It would also be quite easy to write |> > a function to find and extract the argument descriptions from the |> > text, if necessary. |> |> Yes, this stands out very nicely. Can we agree to put such |> a list immediately after the one-line description, if there |> is to be one, and not worry about explicitly preceding it |> with "the arguments are..." -- thus establishing the use of |> a definition list in this position as a convention? I think this convention may be too restrictive. Again, gendoc detects def lists by their structure not their position. This could be part of a style guide though. -Robin ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

6 7

[PYTHON DOC-SIG] Structured documentation syntax
by Ka-Ping Yee Sept. 11, 1996

Sept. 11, 1996

Hi -- i just saw the following on python-list: > Daniel Larsson has released gendoc 0.6 for your documentation > pleasure. The big change here is the adoption of structured text > for the doc string formatting standard. -- and went to have a look at the doc-sig page to find out what the formatting syntax was. Syntactic things: ----------------- I know that it may not be my place to speak so soon, as i have not spent any time researching what has been done, but a look at the description on the doc-sig page produced these thoughts (in order of decreasing strength): - Double-quotes seem too common to be used as hyperlink delimiters. More in keeping with common practice might be the use of [], the way most people use them to mark references. - Also, it would make sense for double and single quotes to both mark example code. What if you need to talk about a single-quoted string, for example? - As noted on the page, use of "--" is reasonably common for em-dashes (in fact, i'd even suggest turning them into real &emdash; entities in HTML). Why not use "::" instead for tagged list elements? - Couldn't you just choose one bullet marker for list elements, instead of three? - Is it true that a first-level list begins "12 First sentence..." but deeper levels begin "3.4. First sentence..."? That is, the description on the page seems to imply that the periods follow each ordering component, rather than separate them. - It might be nicer (simpler) to use _underscores_ for italics and use *single asterisks* for bold. (Special Python names that start and end with underscores should be marked as code examples anyway...) Btw, how do you make headings? Do you just make everything a sub-paragraph of a short paragraph containing the heading? Semantic things: ---------------- Has there been any thought towards a well-defined standard for documenting functions? I'm thinking of things about the interface, like parameter lists and descriptions of parameters, and maybe a defined place for a one-sentence (or even one-predicate) summary of what the function does, and/or what circumstances it expects to be run under. I think this could be fairly useful. A project i'm working on now (called MINSE, for the representation of structured expressions -- like math -- in HTML documents) needs a way to describe just these kinds of things about functions, and not just for the sake of documentation but actually as a real part of its operation. I want it to produce semantic information attached to the structures in the expression, and the perfect place to describe this seems to be __doc__. So i am thinking about designing a way to specify this information, but after reading the post thought that it might be better for gendoc and MINSE to understand things the same way. For more info on MINSE, please see http://www.lfw.org/math/. (Slightly out of date, so i can give more details if anyone has questions.) It currently has a working renderer for math expressions, which makes it possible for anyone to write math directly in their HTML and anyone to view it in any graphical OR textual browser. It's done in Python, of course. :) Ping ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

4 7

Re: [PYTHON WEB-SIG] Re: [PYTHON DOC-SIG] HTMLgen and gendoc
by friedric＠rose.rsoc.rockwell.com Sept. 11, 1996

Sept. 11, 1996

|> From: Bill Janssen <janssen(a)parc.xerox.com> |> |> Excerpts from ext.python: 11-Sep-96 [PYTHON DOC-SIG] HTMLgen an.. Robin |> Friedrich(a)rose.rso (526) |> |> > In order to illustrate the results of gendoc 0.6 we've unpacked the |> > HTMLgen online documentation on the python server so you can browse |> > it directly. When you get there, click the Manual button to spawn a |> > new browser with the framed manual autogenerated with gendoc's HTMLgen |> > formatter module. |> |> > http://www.python.org/sigs/web-sig/HTMLgen/html/main.html |> |> Hmmm, not good. I go to my Emacs, type "M-x w3-fetch |> http://www.python.org/sigs/web-sig/HTMLgen/html/main.html", and see |> nothing. Frames are not supported by several useful browsers; I'd like |> to see a solution which doesn't use them. |> |> Bill Not to worry. Gendoc supports vanilla HTML emission via the -f HTML option (which is the default btw). The HTMLgen formatter is for the more tooty-fruity style of pages :-) The vanilla HTML, MIF, and ASCII versions could have been emitted at no extra effort. -Robin ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0