From Edward Welbourne Tue Jan 4 10:56:10 2000 From: Edward Welbourne (Edward Welbourne) Date: Tue, 4 Jan 2000 10:56:10 GMT Subject: [Doc-SIG] Documentation systems for other languages In-Reply-To: <14432.14.215063.798808@weyr.cnri.reston.va.us> References: <14430.37284.507421.983098@weyr.cnri.reston.va.us> <200004051129.MAA20636@lsls4p.lsl> <14432.14.215063.798808@weyr.cnri.reston.va.us> Message-ID: <200001041056.KAA21483@lsls4p.lsl> > Is there a pointer to something that describes this in the context > of Occam? None I know of. > I've heard about folding as a general approach ... > ... but had not heard of it as specific to a language. AFAIK, Occam introduced the idiom. It is otherwise irrelevant to the discussion: the folding idiom is what I was thinking of, not Occam. I only mentioned Occam because it'd ring some bells where `folded files' might not have done. Eddy. -- And a happy new year to doc-sig, too ;^> From fdrake@acm.org Tue Jan 4 14:59:34 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Tue, 4 Jan 2000 09:59:34 -0500 (EST) Subject: [Doc-SIG] Documentation systems for other languages In-Reply-To: <200001041056.KAA21483@lsls4p.lsl> References: <14430.37284.507421.983098@weyr.cnri.reston.va.us> <200004051129.MAA20636@lsls4p.lsl> <14432.14.215063.798808@weyr.cnri.reston.va.us> <200001041056.KAA21483@lsls4p.lsl> Message-ID: <14450.2774.140591.429387@weyr.cnri.reston.va.us> Edward Welbourne writes: > AFAIK, Occam introduced the idiom. It is otherwise irrelevant to the > discussion: the folding idiom is what I was thinking of, not Occam. > I only mentioned Occam because it'd ring some bells where `folded files' > might not have done. I did not know that; interesting! > And a happy new year to doc-sig, too ;^> Bah, humbug! ;) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From janssen@parc.xerox.com Sat Jan 8 00:05:59 2000 From: janssen@parc.xerox.com (Bill Janssen) Date: Fri, 7 Jan 2000 16:05:59 PST Subject: [Doc-SIG] Documentation systems for other languages In-Reply-To: Your message of "Tue, 21 Dec 1999 04:30:04 PST." <200004051129.MAA20636@lsls4p.lsl> Message-ID: <00Jan7.160454pst."3446"@watson.parc.xerox.com> > For a pythonic system, folding would mean taking any fairly large chunk > of code or doc (sharing a common base indent) and providing for it to be > *displayed* (by the IDE) either (open fold) as the whole chunk or > (closed fold) as a single line carrying (typically encoded as a comment) > some text that says what's in the fold. In between, of course, we have > the fold open but some portions of its contents folded out of sight. > Most modern directory-browsers display directory tree hierarchies in a > way instantly recognisable to anyone who ever used a folded editor. Sounds like outline mode in emacs. The GNU Emacs support for SGML provides this, perhaps more closely resembling what you describe. Bill From klm@i.am Mon Jan 10 22:15:51 2000 From: klm@i.am (Ken Manheimer) Date: Mon, 10 Jan 2000 17:15:51 -0500 (EST) Subject: [Doc-SIG] Documentation systems for other languages Message-ID: <14458.23063.798080.637233@splat.digicool.com> On Fri, 7 Jan 2000 16:05:59 PST, bill janssen wrote: > Before that, (i think) edward welbourne wrote: > > For a pythonic system, folding would mean taking any fairly large chunk > > of code or doc (sharing a common base indent) and providing for it to be > > *displayed* (by the IDE) either (open fold) as the whole chunk or > > (closed fold) as a single line carrying (typically encoded as a comment) > > some text that says what's in the fold. In between, of course, we have > > the fold open but some portions of its contents folded out of sight. > > Most modern directory-browsers display directory tree hierarchies in a > > way instantly recognisable to anyone who ever used a folded editor. > > Sounds like outline mode in emacs. The GNU Emacs support for SGML > provides this, perhaps more closely resembling what you describe. I've been meaning to mention my outdent.el - it provides emacs outline-mode style text visibility control based on indentation, and runs as a minor mode - so you can run it in conjunction with python mode. I find it quite useful for looking at the structure of modules, especially large ones, and narrowing focus to particular portions. There are things yet to be done for it - searching can leave the cursor within hidden regions (so you need to hit ^C^I or ^C^S to expose where you are - interrupting the search), and i've been hoping for years to have a moment to incorporate this functionality directly in python-mode.el, but alas. It should be useful as is - it is for me... Find it at http://starship.python.net/crew/klm/outdent.el Ken Manheimer klm@i.am From aa8vb@yahoo.com Tue Jan 11 20:17:09 2000 From: aa8vb@yahoo.com (Randall Hopper) Date: Tue, 11 Jan 2000 15:17:09 -0500 Subject: [Doc-SIG] outdent.el (for .py editing in Emacs) In-Reply-To: <14458.23063.798080.637233@splat.digicool.com> References: <14458.23063.798080.637233@splat.digicool.com> Message-ID: <20000111151709.B44533@vislab.epa.gov> Ken Manheimer: |I've been meaning to mention my outdent.el - it provides emacs |outline-mode style text visibility control based on indentation, and |runs as a minor mode - so you can run it in conjunction with python |mode. I find it quite useful for looking at the structure of modules, |especially large ones, and narrowing focus to particular portions. That is a really nice aid for Emacs users. Personally I think this is worth posting to the main python list! ;-) And linked off of http://www.python.org/emacs/, if you're confortable with it. I can see myself using this a good bit. So many times I've been browsing someone else's .py and wanted to know what class we're in. Page up, page up, page up, and hope you don't miss it, or do a search-backward-regex. Now just C-c C-u. Hiding can be useful for browsing too, as you said. Seeing outdent-show-all, I was looking for an 'outdent-hide-all' or 'outdent-hide-this-level', but didn't find one. No big deal. I'll write a macro for that sometime. Thanks for the tool. -- Randall Hopper aa8vb@yahoo.com From klm@digicool.com Fri Jan 14 19:37:49 2000 From: klm@digicool.com (Ken Manheimer) Date: Fri, 14 Jan 2000 14:37:49 -0500 (EST) Subject: [Doc-SIG] Re: outdent.el (for .py editing in Emacs) In-Reply-To: <20000111151709.B44533@vislab.epa.gov> Message-ID: On Tue, 11 Jan 2000, Randall Hopper wrote: > [I posted outdent.el, an exposure-control emacs minor mode for indented text.] > That is a really nice aid for Emacs users. Personally I think this is > worth posting to the main python list! ;-) And linked off of > http://www.python.org/emacs/, if you're confortable with it. It was on the python.org contrib section, but that's now gone. I think it was in the python.org emacs section, too, but that seems to be gone - too bad! I too would like to see it back there. I don't have time to post it to comp.lang.emacs right now - feel free to do so, if you'd like! I just can't followup at the moment, due to lack of time... > Seeing outdent-show-all, I was looking for an 'outdent-hide-all' or > 'outdent-hide-this-level', but didn't find one. No big deal. I'll write a > macro for that sometime. Do '^U^C^H' at a top-level topic. (If you just keep doing a '^C^H' it'll close things until you get to the top level, then a message will tell you to give the repeat count.) > Thanks for the tool. Glad you like it! Ken klm@digicool.com From aa8vb@yahoo.com Tue Jan 18 13:15:17 2000 From: aa8vb@yahoo.com (Randall Hopper) Date: Tue, 18 Jan 2000 08:15:17 -0500 Subject: [Doc-SIG] Re: outdent.el (for .py editing in Emacs) In-Reply-To: References: <20000111151709.B44533@vislab.epa.gov> Message-ID: <20000118081517.A391136@vislab.epa.gov> Ken Manheimer: |> That is a really nice aid for Emacs users. Personally I think this is |> worth posting to the main python list! ;-) And linked off of |> http://www.python.org/emacs/, if you're confortable with it. | |It was on the python.org contrib section, but that's now gone. I think it |was in the python.org emacs section, too, but that seems to be gone - too |bad! No it's still there: http://www.python.org/emacs/ However I found it via the search engine, so I don't know whether it's reachable through links. FAQ entry 1.19 really needs updated to include: Other Emacs goodies for Python (PDB Mode, outdent, etc.) can be found at: http://www.python.org/emacs Randall |> Seeing outdent-show-all, I was looking for an 'outdent-hide-all' or |> 'outdent-hide-this-level', but didn't find one. No big deal. I'll write a |> macro for that sometime. | |Do '^U^C^H' at a top-level topic. (If you just keep doing a '^C^H' it'll |close things until you get to the top level, then a message will tell you |to give the repeat count.) Great. Referring to the function help on outdent-mode again, I infer that ^U must generally mean "for all"; I didn't pick that up the first time from the specific outdent-show-all example. -- Randall Hopper aa8vb@yahoo.com From klm@digicool.com Tue Jan 18 15:42:58 2000 From: klm@digicool.com (Ken Manheimer) Date: Tue, 18 Jan 2000 10:42:58 -0500 (EST) Subject: [Doc-SIG] Re: outdent.el (for .py editing in Emacs) In-Reply-To: <20000118081517.A391136@vislab.epa.gov> Message-ID: On Tue, 18 Jan 2000, Randall Hopper wrote: > Ken Manheimer: > |> That is a really nice aid for Emacs users. Personally I think this is > |> worth posting to the main python list! ;-) And linked off of > |> http://www.python.org/emacs/, if you're confortable with it. > | > |It was on the python.org contrib section, but that's now gone. I think it > |was in the python.org emacs section, too, but that seems to be gone - too > |bad! > > No it's still there: > > http://www.python.org/emacs/ Whoops - my statement was ambiguous - i didn't mean that http://www.python.org/emacs/ was gone, but rather that outdent isn't in it. > However I found it via the search engine, so I don't know whether it's > reachable through links. > > FAQ entry 1.19 really needs updated to include: > > Other Emacs goodies for Python (PDB Mode, outdent, etc.) can be found at: > > http://www.python.org/emacs Yes - i think outdent was there, can't recall why it was ditched... (Barry?) > Randall > > |> Seeing outdent-show-all, I was looking for an 'outdent-hide-all' or > |> 'outdent-hide-this-level', but didn't find one. No big deal. I'll write a > |> macro for that sometime. > | > |Do '^U^C^H' at a top-level topic. (If you just keep doing a '^C^H' it'll > |close things until you get to the top level, then a message will tell you > |to give the repeat count.) > > Great. Referring to the function help on outdent-mode again, I infer that > ^U must generally mean "for all"; I didn't pick that up the first time > from the specific outdent-show-all example. It's not ideal. Neither is an alternative choice i made in my outliner for emacs, allout.el, where doing a hide of a top-level topic that's already hidden would do a hide-all. Neither is particularly obvious, and its easier to accidentally invoke the allout choice - for better or worse, i'm not sure... Ken Manheimer klm@digicool.com From fdrake@acm.org Tue Jan 18 23:01:23 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Tue, 18 Jan 2000 18:01:23 -0500 (EST) Subject: [Doc-SIG] IPC8 Developers Day discussion paper Message-ID: <14468.61635.536531.220677@weyr.cnri.reston.va.us> I've posted the discussion document for the IPC Developers Day session; see it at: http://www.python.org/workshops/2000-01/doc-sig.html I hope to see you at the conference! -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From da@ski.org Sat Jan 22 07:33:36 2000 From: da@ski.org (David Ascher) Date: Fri, 21 Jan 2000 23:33:36 -0800 Subject: [Doc-SIG] Docstring grammar: a very revised proposal In-Reply-To: <14472.51043.121344.784410@weyr.cnri.reston.va.us> Message-ID: Over the last week, I've been incorporating all of the comments that various folks made in the DOC-SIG about the docstring grammar proposal, and writing code to provide a reference implementation. It's been going well, and I was polishing up to post it. In preparation of a discussion at IPC8's DevDay, and anticipating (perhaps mistakenly) some resistance to "yet another structured text format" from Jim Fulton, I went to look at StructuredText to find out what aspects of it I had problems with in the past. Just as a point of historical interest, I have long been a fan of the idea behind StructuredText, and have used a fairly old version of it to generate much of my website automatically. I stopped doing so because I found it lacking for the things I was trying to get it to do, unintuitive at times, and too hard to modify for my (somewhat exotic) needs. I just looked again at StructuredText's rules (not code) within the context of "Python code documentation" exclusively (a much more narrow domain than website management), and found it better-suited than I remembered, with three kinds of problems: - StructuredText is too generic -- in markup terms, it's much like SGML or XML without a DTD (or with a very weak one). So while it's an OK markup, it's too weak as it stands. - StructuredText has some markup rules which I think are wrong, in the sense that they fail the "naturalness" test which we set out to use in our alternative markup or they cause "bad" side-effects when a docstring is not fully marked up. - Missing features (not surprising -- the aim is different) I'll describe each of the kinds of problems in detail, but first, let's look at the rules which are followed by the *latest* version of StructuredText.py, which is available at the Zope CVS site. I include the docstring for StructuredText.py here: Structured Text Manipulation Parse a structured text string into a form that can be used with structured formats, like html. Structured text is text that uses indentation and simple symbology to indicate the structure of a document. A structured string consists of a sequence of paragraphs separated by one or more blank lines. Each paragraph has a level which is defined as the minimum indentation of the paragraph. A paragraph is a sub-paragraph of another paragraph if the other paragraph is the last preceding paragraph that has a lower level. Special symbology is used to indicate special constructs: - A single-line paragraph whose immediately succeeding paragraphs are lower level is treated as a header. - A paragraph that begins with a '-', '*', or 'o' is treated as an unordered list (bullet) element. - A paragraph that begins with a sequence of digits followed by a white-space character is treated as an ordered list element. - A paragraph that begins with a sequence of sequences, where each sequence is a sequence of digits or a sequence of letters followed by a period, is treated as an ordered list element. - A paragraph with a first line that contains some text, followed by some white-space and '--' is treated as a descriptive list element. The leading text is treated as the element title. - Sub-paragraphs of a paragraph that ends in the word 'example' or the word 'examples', or '::' is treated as example code and is output as is. - Text enclosed single quotes (with white-space to the left of the first quote and whitespace or puctuation to the right of the second quote) is treated as example code. - Text surrounded by '*' characters (with white-space to the left of the first '*' and whitespace or puctuation to the right of the second '*') is emphasized. - Text surrounded by '**' characters (with white-space to the left of the first '**' and whitespace or puctuation to the right of the second '**') is made strong. - Text surrounded by '_' underscore characters (with whitespace to the left and whitespace or punctuation to the right) is made underlined. - Text encloded by double quotes followed by a colon, a URL, and concluded by punctuation plus white space, *or* just white space, is treated as a hyper link. For example: "Zope":http://www.zope.org/ is ... Is interpreted as 'Zope is ....' Note: This works for relative as well as absolute URLs. - Text enclosed by double quotes followed by a comma, one or more spaces, an absolute URL and concluded by punctuation plus white space, or just white space, is treated as a hyper link. For example: "mail me", mailto:amos@digicool.com. Is interpreted as 'mail me.' - Text enclosed in brackets which consists only of letters, digits, underscores and dashes is treated as hyper links within the document. For example: As demonstrated by Smith [12] this technique is quite effective. Is interpreted as '... by Smith [12] this ...'. Together with the next rule this allows easy coding of references or end notes. - Text enclosed in brackets which is preceded by the start of a line, two periods and a space is treated as a named link. For example: .. [12] "Effective Techniques" Smith, Joe ... Is interpreted as '[12] "Effective Techniques" ...'. Together with the previous rule this allows easy coding of references or end notes. - A paragraph that has blocks of text enclosed in '||' is treated as a table. The text blocks correspond to table cells and table rows are denoted by newlines. By default the cells are center aligned. A cell can span more than one column by preceding a block of text with an equivalent number of cell separators '||'. Newlines and '|' cannot be a part of the cell text. For example: |||| **Ingredients** || || *Name* || *Amount* || ||Spam||10|| ||Eggs||3|| is interpreted as::
Ingredients
Name Amount
Spam 10
Eggs 3
------- This markup has nice features: - it's very similar to the core of what we were discussing (no big surprise, since my proposal was mostly stolen from earlier StructuredText =). - The (new to me) mechanism for dealing with references to URLs and to other bits of text is quite elegant. Ok, now onto the problems with the above markup rules, IMO of course. StructuredText as XML without a DTD: Unlike the grammar which was discussed on the doc-sig, StructuredText does not allow us to specify special syntax for special kinds of text, such as: signature blocks/tooltip descriptions, doctest.py code, and keyworded paragraphs. This is a lack of feature rather than a flaw, and could maybe be fixed by adding a postprocessor which would be Python-internal-doc specific. StructuredText as a markup with some flaws for inline doc: The use of single quotes to markup inline code (as in 'x') can be surprising. Many current docstrings use 'x' to refer to the *string* containing the character x, not the variable x. In StructuredText, the quotes would dissappear in the rendering. With practice, the current scheme could be used but users would have to learn to write '"x"' to have their intent carry through to the renderer. This is probably my biggest problem with StructuredText because I don't know how to fix it while maintaining compatibility. Related questions for Jim or Ken are 1) How does StructuredText parse ''? 2) How can one have a single quote in verbatim text? The tagging of underlined text with _'s is suboptimal. Underlines shouldn't be used from a typographic perspective (underlines were designed to be used in manuscripts to communicate to the typesetter that the text should be italicized -- no well-typeset book ever uses underlines), and conflict with double-underscored Python variable names (__init__ and the like), which would get truncated and underlined when that effect is not desired. Note that while *complete* markup would prevent that truncation ('__init__'), I think of docstring markups much like I think of type annotations -- they should be optional and above all do no harm. In this case the underline markup does harm. The requirement that a paragraph end with the word example or examples or :: goes against my natural style, as I often do not want such word or punctuation before a "displayed" paragraph. Furthermore, the spec currently doesn't say how the renderer is supposed to process the :: -- is it displayed as two colons, one, or none? If the two colons are not displayed by the renderer, then my objection is diminished, although I would have preferred a markup which is local to the paragraph which is affected, not the previous one (cut and paste errors follow too easily). In some versions in the past at least, both colons were displayed. I'll leave that as an open question, as additional markup could provide an alternative which would suit me. Missing features: The definition of references is well-designed for referencing URLs. The docstring proposal needs to address referencing other code elements (methods of current class, other classes, other methods of other classes, builtin modules, imported modules, etc.) This is also more of a lack of feature than a real flaw, and defining the namespaces for lookup of 'reference targets' would probably go most of the way towards fixing the spec for our needs. The DOC-SIG folks strongly wanted to be able to have list items not require blank lines in between them. This is not hard to do from scratch (I've got code to do it). I suspect it could be added to StructuredText as a postprocessing step. (From experience, such list items should be required to be indented relative to the previous line, to avoid spurious bulletization.) I think many folks liked the idea of "tagged" paragraphs, as in: Author: Guido van Rossum and Release-History: 0.1: June 1920 0.2: July 1919 etc. Again, postprocessing smarts for this could be added while keeping backwards compatibility. Many of the features related to these tagged paragraphs (internationalization of keywords, etc.) could be dealt within the postprocessor. Technical points: StructuredText.py uses the regex module, which is deprecated. StructuredText.py currently rarely produces an exception. The output may not be what you expected, but it will produce output. For a rigorous docstring markup, I'd expect to see much stricter rules enforced, which raises technical questions (the line numbers for example are not maintained as part of the StructuredText.py parsing process I suspect). This requirement would probably have the most impact on the current source. Assuming this analysis is correct, I am inclined to scrap my original proposal, shelve my current prototype code, and work instead with Jim Fulton and whoever else to discuss whether and how to modify StructuredText's format and code to extend it to the needs which the DOC-SIG expressed. The value in this approach is: - StructuredText.py (the code) exists and works. (prior art) - There is a fair bit of code which uses StructuredText's markup. (user base) - Much of the work would be postprocessing of StructuredText.py analysis. (modularity) - The features of the current markup which are deemed problematic could be disabled with a runtime switch if the StructuredText community disagrees with my assessment. (configurability) An alternative course of action is to take StructuredText.py and modify and rename it (aka code fork) This is of course less desirable, but would be the efficient way of dealing with either irreconciliable differences of opinion or differing needs (It is possible that the Zope folks do not want to see their code burdened with e.g. line number maintenance code because of performance or other reasons). We also need to know whether the Zope folks would *want* to push StructuredText.py into the Python standard library, which I have always assumed to be a goal for whatever tool we come up with. A final alternative is for me to revise my current (unpublished) manuscript to incorporate some of the things I like about StructuredText which we didn't have (the reference naming scheme mostly), and keep a parallel track in spec and code. Just as a point of note: I do maintain that keeping StructuredText as it currently is without postprocessing is inadequate for intelligent docstring markup, and do not consider that a solution to the problem at hand, although it's a fine everyday strategy in the absence of a solution. I would like to discuss which approach should be followed at the DevDay session. Feel free to email or post feedback between now and the conference, whether or not you'll be there. Assuming a discussion does take place, I'll try to post a summary post-conference. Cheers, David Ascher From chapmanb@arches.uga.edu Mon Jan 24 09:22:30 2000 From: chapmanb@arches.uga.edu (Brad Chapman) Date: Mon, 24 Jan 2000 04:22:30 -0500 Subject: [Doc-SIG] Pythondoc question Message-ID: Hello all! I have just downloaded and started playing with pythondoc. It works beautifully for me for a single module and for the basic test programs in the distribution, but now I would like to try and use it to document my entire program, while is made up of a number of modules over a distributed directory structure. Is there an easy way to run pythondoc on all of the modules in my program at once? I guess this could be done by entering all of the module/file names that need to be pythondoced into the command line, but I would like a reusable way to do this--the program is still under heavy development and I would like to make it easy to keep the module documentation up to date with the program itself. Can the pythondoc.opts file be configured to have the names of all the programs to process? Thanks much for any help anyone can provide, and thanks for all the work on this wonderful program--it is much needed! Brad From klm@digicool.com Tue Jan 25 00:26:34 2000 From: klm@digicool.com (Ken Manheimer) Date: Mon, 24 Jan 2000 19:26:34 -0500 Subject: [Doc-SIG] RE: Docstring grammar: a very revised proposal Message-ID: <613145F79272D211914B0020AFF640191D1D64@gandalf.digicool.com> David Ascher wrote: > Assuming this analysis is correct, I am inclined to scrap my original > proposal, shelve my current prototype code, and work instead with Jim Fulton > and whoever else to discuss whether and how to modify StructuredText's format > and code to extend it to the needs which the DOC-SIG expressed. The value > in this approach is: Cool! David, we would be glad to have this happen. We like StructuredText, and would love to see it widely used and available. And we have very limited time right now, which means we would be very happy to have someone like you/the python community making harmonious changes. I think jim and/or i could field your questions/suggestions, to try to keep us in agreement. Re the specifics in your message: > StructuredText as XML without a DTD: > > Unlike the grammar which was discussed on the doc-sig, StructuredText > does not allow us to specify special syntax for special kinds of text, > such as: signature blocks/tooltip descriptions, doctest.py code, > and keyworded paragraphs. This is a lack of feature rather than a flaw, > and could maybe be fixed by adding a postprocessor which would be > Python-internal-doc specific. I'm not entirely clear about what you're referring to, but we're thinking about a slightly different structure for the StructuredText object that may admit this sort of thing. A base class would just be responsible for parsing paragraphs (including distinguishing bullet paragraphs that aren't newline separated - yay!), then a document-formatting class, maybe abstract, that recognizes generic document features like headers, emphasis, links, etc. The document formatting class could be subclassed by a renderering class, eg an html-formatter or a docstring-formatter. It so happens Jim has an intern looking at doing this restructuring as a fun-ish (relief from C coding) side project. It's not clear we'll get it done, but it is clear we'd be happy to see it, and i think it would allow a whole lot more customizability. > The use of single quotes to markup inline code (as in 'x') can be > surprising. Many current docstrings use 'x' to refer to the > *string* containing the character x, not the variable x. In > StructuredText, the quotes would dissappear in the rendering. With > practice, the current scheme could be used but users would have to > learn to write '"x"' to have their intent carry through to the > renderer. This is probably my biggest problem with StructuredText > because I don't know how to fix it while maintaining > compatibility. Related questions for Jim or Ken are 1) How does > StructuredText parse ''? 2) How can one have a single quote in > verbatim text? I can't answer all your questions. We'd be interested to know what you suggest as an alternative - how would you indicate brief passages? It's possible the generic formatter would be settable to one or the other, or it'd recognize both ticked-code and whatever you want and the renderer would choose which to transform to code, or we'd have an almost generic formatter which could be derived into different flavors of generic formatters, each of which did the respective thing for recognizing short passages. > The tagging of underlined text with _'s is suboptimal. Underlines > shouldn't be used from a typographic perspective (underlines were > designed to be used in manuscripts to communicate to the > typesetter that the text should be italicized -- no well-typeset > book ever uses underlines), and conflict with double-underscored > Python variable names (__init__ and the like), which would get > truncated and underlined when that effect is not desired. Note > that while *complete* markup would prevent that truncation > ('__init__'), I think of docstring markups much like I think of > type annotations -- they should be optional and above all do no > harm. In this case the underline markup does harm. Durn - i did that, and regret it. We're really not wedded to use of underscores for underlined text. > The requirement that a paragraph end with the word example or > examples or :: goes against my natural style, as I often do not > want such word or punctuation before a "displayed" paragraph. > Furthermore, the spec currently doesn't say how the renderer is > supposed to process the :: -- is it displayed as two colons, one, > or none? If the two colons are not displayed by the renderer, > then my objection is diminished, although I would have preferred a > markup which is local to the paragraph which is affected, not the > previous one (cut and paste errors follow too easily). In some > versions in the past at least, both colons were displayed. I'll > leave that as an open question, as additional markup could provide > an alternative which would suit me.r, which does the actual rendering. I think we agree that it'd be nice to have the example cue in the text, rather than before it, but we don't have a suggestion of a natural/uncluttered way to do that. As for the current :: format, to double colon is supposed to be rendered as a double colon. > Missing features: > [references to entities other than URLs; define namespaces for reference targets] Sounds cool. I think.-) > [list items without requring blank lines] Yay! > [tagged paragraphs] Might '::' example-style paragraphs fit into this category? Maybe provisions for special handling of the tag cue (E.g., throwing away "Example:") would enable this to solve our examples problem. > Technical points: > [regex has been deprecated] I think we would be ok with switchover to re if we had some kind of caching FormattedDocument, which may be in the works. But we use StructuredText enough in zope that performance is an issue - and re doesn't have the performance yet! Whoops - gotta run! Looking forward to more on this... Ken Manheimer klm@digicool.com From gerrit@nl.linux.org Thu Jan 27 16:07:16 2000 From: gerrit@nl.linux.org (Gerrit Holl) Date: Thu, 27 Jan 2000 17:07:16 +0100 Subject: [Doc-SIG] Re: lib reference in Unix man format In-Reply-To: <200001271548.KAA04215@trm.bmo.com>; from tlu@bmo.com on Thu, Jan 27, 2000 at 10:48:53AM -0500 References: <200001271548.KAA04215@trm.bmo.com> Message-ID: <20000127170716.A2968@stopcontact.palga.uucp> Hello, Tao Lu wrote on 948966533 in comp.lang.python: > Where can I find the lib reference in Unix man format? Forgive me if this has > been asked before. > > Have been programming in Perl for years, I found those perlfunc/perlop/perlfaq > are very convenient. Any similar work done for Python developers/newbies? This doesn't exist, does it? I think many people would like it if it would be done; the documentation and the howto's are available in quite a lot formats; why not add another one? regards, Gerrit. -- Please correct any bad English you encounter in my email message! -----BEGIN GEEK CODE BLOCK----- http://www.geekcode.com Version: 3.12 GCS dpu s-:-- a14 C++++>$ UL++ P--- L+++ E--- W++ N o? K? w--- !O !M !V PS+ PE? Y? PGP-- t- 5? X? R- tv- b+(++) DI D+ G++ !e !r !y -----END GEEK CODE BLOCK----- From Moshe Zadka Fri Jan 28 06:16:06 2000 From: Moshe Zadka (Moshe Zadka) Date: Fri, 28 Jan 2000 08:16:06 +0200 (IST) Subject: [Doc-SIG] Some Premilinary Thoughts on Syntax Message-ID: Since I won't be back at home until next week, and since the DOC-SIG devday sort of nominated me to suggest a syntax for the documentations, I'll just outline what I think is needed, how I plan on feeling that need, and skectch the specs and software needed. There was a consensus that there should be two syntaxes -- one for the embedded doc-strings, and one for out-of-line documentation. (Note that wherever I refere to doc strings from now on, a doc string is the concatanation of all initialstrings in ..., as opposed to the python interpreter. This is deliberate, and is meant to hve doc strings which can be optimized away). The first thing we would need is to make sure the two markups are semantically equivalent. More precisely, we'll need to figrue out what "element" (to use XML terminilogy) an embedded doc string corresponds to in the OOL (out of line) documentation, and make sure we have a one to one correspondence betweent the syntaxes. At the risk of being flamed to death, I will offer that this means throwing StructureText clean out of the door, as it is impossible to reason about it. The only structured text idea that would be left would be indentation for blocks, because it meashes well with the rest of the code. Then we need a spec to define how an ool document can refer to the documentation inside a module. I'm thinking of a template mechanism, since it generalizes the two common cases -- - complete ool documentation would be a paramteter-less template - complete embedded documentation would be using the default template. The requirement for both of the syntaxes are that they would be very human writable, and yet structurally equivalent to XML. The ool is relatively easy -- we'll use XML plus some of the minimization from XML. Paul Prescod seemed to say something about it in the elevator, and I'm hoping to beat something more concrete out of him. The embedded is up for grabs -- I'm not yet cnvinced it should be human (as opposed to doc-writer) readable, since I think >> import help >> help.help(foobar) is infinitely better then >> print foobar.__doc__ And if it's not, we should be able to use hooks in the interpreter to convert the doc-sig to readable text before it ends up in foobar.__doc__. Disclaimer: These are late-night thoughts more written as notes to myself. I'm not as convinced about things as I sound, so if you have some diagreement, please mail me (personally, prefereably, to forestall the inevitable flamewar) -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From sean@digitome.com Sat Jan 29 10:27:16 2000 From: sean@digitome.com (Sean Mc Grath) Date: Sat, 29 Jan 2000 10:27:16 +0000 Subject: [Doc-SIG] Monty: A structured text syntax idea Message-ID: <3.0.6.32.20000129102716.009cd5c0@gpo.iol.ie> """ idea: para: I was editing some text in Python emacs mode the other day. para: I got to thinking how Python mandatory indentation emph: removes much of the need for delimiters para: Then it occured to me that XML tags are basically delimiters of nested block structures. para: Before I new it, I had written this structured text document, trivially parseable, trivially convertable to XML or whatever and christened it bold: Monty in honour of Python from which the idea came. para: I have started using this format in my docstrings and find Barry's amazing Python editing mode to be a very pleasent - um - structured text authoring tool! """ http://www.pyxie.org - an Open Source XML Processing library for Python From irmina@ctv.es Sat Jan 29 15:20:01 2000 From: irmina@ctv.es (Manuel Gutierrez Algaba) Date: Sat, 29 Jan 2000 15:20:01 +0000 (GMT) Subject: [Doc-SIG] Monty: A structured text syntax idea In-Reply-To: <3.0.6.32.20000129102716.009cd5c0@gpo.iol.ie> Message-ID: On Sat, 29 Jan 2000, Sean Mc Grath wrote: > """ > idea: > para: > I was editing some text in Python emacs mode the > other day. > para: > I got to thinking how Python mandatory indentation > emph: > removes > much of the need for delimiters I like it! Regards/Saludos Manolo www.ctv.es/USERS/irmina /TeEncontreX.html /texpython.htm /pyttex.htm I think we're all Bozos on this bus. -- Firesign Theatre From Moshe Zadka Sun Jan 30 14:04:13 2000 From: Moshe Zadka (Moshe Zadka) Date: Sun, 30 Jan 2000 16:04:13 +0200 (IST) Subject: [Doc-SIG] Monty: A structured text syntax idea In-Reply-To: <3.0.6.32.20000129102716.009cd5c0@gpo.iol.ie> Message-ID: On Sat, 29 Jan 2000, Sean Mc Grath wrote: > I got to thinking how Python mandatory indentation > emph: > removes > much of the need for delimiters Actually, it sounds like a good idea, but I think some tradeoffs can be made. I'll put out a document soon (I've only got it in dead tree format right now) which describes the syntax, and I do use indentation for some of the markup. However, using it for all the markup might create an *roff like monster. Currently, I'm partial for (the horror) brackets for stuff that will be short like [module urllib] and function [func urlopen], and using (double colons) for block delimiting, since we (unlike Python) have to play well with NatLang... I'm commited to documenting at least one Python module with any syntax I suggest before putting out a complete document. cheers! -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From pf@artcom-gmbh.de Sun Jan 30 14:13:17 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Sun, 30 Jan 2000 15:13:17 +0100 (MET) Subject: [Doc-SIG] Monty: A structured text syntax idea In-Reply-To: from Moshe Zadka at "Jan 30, 2000 4: 4:13 pm" Message-ID: Hi all! Moshe Zadka wrote: [...] > I'm commited to documenting at least one Python module > with any syntax I suggest before putting out a complete document. What about using 'Tkinter.py' for that purpose, since it is very well known? Hey ... that was a joke! I just couldn't resist. ;-) Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From gward@cnri.reston.va.us Mon Jan 31 14:21:01 2000 From: gward@cnri.reston.va.us (Greg Ward) Date: Mon, 31 Jan 2000 09:21:01 -0500 Subject: [Doc-SIG] Monty: A structured text syntax idea In-Reply-To: <3.0.6.32.20000129102716.009cd5c0@gpo.iol.ie>; from sean@digitome.com on Sat, Jan 29, 2000 at 10:27:16AM +0000 References: <3.0.6.32.20000129102716.009cd5c0@gpo.iol.ie> Message-ID: <20000131092101.B17073@cnri.reston.va.us> On 29 January 2000, Sean Mc Grath said: > """ > idea: > para: > I was editing some text in Python emacs mode the > other day. > para: > I got to thinking how Python mandatory indentation > emph: > removes > much of the need for delimiters Auughh!!! Shades of troff here. (That's not a good thing.) Newlines are a fine delimiter in a programming language, where the semantic chunks tend to be on the order of 20-60 characters, and we need all the help we can get to guide our eyes. Natural language can have much smaller semantic chunks -- eg. emphasized words -- so artificially splitting lines so often is a waste of vertical real-estate. I think I'll wait for whatever Moshe proposes... (I just hope it uses something B to emphasise text... >grin<) Greg From klm@digicool.com Mon Jan 31 17:49:32 2000 From: klm@digicool.com (Ken Manheimer) Date: Mon, 31 Jan 2000 12:49:32 -0500 Subject: [Doc-SIG] RE: Doc-SIG digest, Vol 1 #134 - 1 msg Message-ID: <613145F79272D211914B0020AFF640191D1D67@gandalf.digicool.com> > Date: Fri, 28 Jan 2000 08:16:06 +0200 (IST) > From: Moshe Zadka > Reply-To: Moshe Zadka > To: doc-sig@python.org > Subject: [Doc-SIG] Some Premilinary Thoughts on Syntax > > [...] > The first thing we would need is to make sure the two markups are > semantically equivalent. More precisely, we'll need to figrue out what > "element" (to use XML terminilogy) an embedded doc string corresponds to > in the OOL (out of line) documentation, and make sure we have a one to one > correspondence betweent the syntaxes. At the risk of being flamed to > death, I will offer that this means throwing StructureText clean out of > the door, as it is impossible to reason about it. The only structured text > idea that would be left would be indentation for blocks, because it > meashes well with the rest of the code. No flames here, i'm only for going with StructuredText if it suits the purpose. But i don't understand your disqualifying criterion. Specifically, i don't see *why* there must be a one-to-one correspondence between the OOL and docstring documentation. I would think the requirement is that all docstring elements map to some OOL elements, but that it's acceptable - probably even desirable - for the collection of docstring elements to be a subset of the OOL collection. Ie, seems to me that there's a lot of stuff that the OOL needs that the docstrings emphatically don't - i'd assume docstrings are pretty localized elements that may need to refer to, but don't need to embody, the larger-scale (chapters, sections, etc) or more specialized (footnotes, tables-of-contents, etc) book structures. If so, i don't see why the StructuredText approach would be disqualified at the outset (colloquialism for "at the start"). And in fact it seems to me that something like StructuredText is necessary to satisfy readability/naturalness, if those are in fact requirements. Ken Manheimer klm@digicool.com From Moshe Zadka Mon Jan 31 20:19:59 2000 From: Moshe Zadka (Moshe Zadka) Date: Mon, 31 Jan 2000 22:19:59 +0200 (IST) Subject: [Doc-SIG] StructuredText suitability for docstrings In-Reply-To: <613145F79272D211914B0020AFF640191D1D67@gandalf.digicool.com> Message-ID: On Mon, 31 Jan 2000, Ken Manheimer wrote: > No flames here, i'm only for going with StructuredText if it suits the > purpose. But i don't understand your disqualifying criterion. > Specifically, i don't see *why* there must be a one-to-one > correspondence between the OOL and docstring documentation. You seemed to have missed my point -- it being that there is (in XML nomencalture) an element type in OOL docs whose content corresponds one-to-one to valid docstrings. Please re-read my post in light of this clarification, and see if you still have objections to it. I think that answers your problems, but then again maybe *I* didn't understand *you*. > If so, i don't see why the StructuredText approach would be disqualified > at the outset (colloquialism for "at the start"). And in fact it seems > to me that something like StructuredText is necessary to satisfy > readability/naturalness, if those are in fact requirements. Well, depends on the type of readability you mean. StructuredText seems a bit too much DWIM (Perlish for "do what I mean") for it to be something I'm too comfortable with, particularily as to how well it can satisfy some "one-to-one" mapping req. which I think we can agree is neccassery for any coherence in the documentation system. -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't.