Mailman 3 July 1996 - Doc-SIG

[PYTHON DOC-SIG] setext in doc strings
by friedric＠rose.rsoc.rockwell.com Aug. 5, 1996

Aug. 5, 1996

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.:-) SETEXT 101 ========== Below is the setext definitions from the BSDI project. Note that not all tags are supported (or needed) in python doc strings. 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 <source> Subject: shown subject-tt (a) (start of a message) minimal mail header [Date: & From:] -------------------- ------------------- --------------- ------------ --- title (1 per text) "Title a title title-tt (b) in distinct position =====" in chosen style -------------------- ------------------- --------------- ------------ --- heading (1+/ text) "Subhead a subhead subhead-tt (c) in distinct position -------" in chosen style -------------------- ------------------- --------------- ------------ --- body text 66-char lines in- lines undented indent-tt (d) [plain not-indented] dented by 2 space and unfolded -------------------- ------------------- --------------- ------------ --- 1+ bold word(s) **[multi]word** 1+ bold word(s) bold-tt (e) a single italic word ~word~ 1 italic word italic-tt (f) 1+ underlined words [_multi]_word_ underlined text underline-tt (g) hypertextual 1+ word [multi_]word_ 1+ hot word(s) hot-tt (h) >followed by text >[space][text] > [mono-spaced] include-tt (i) bullet-text in pos1 *[space][text] [bullet] [text] bullet-tt (j) `_quoted typotag!_` `_left alone!_` quote-tt (k) -------------------- ------------------- --------------- ------------ --- [hypertext link def] ^.. _word URL jump to address href-tt (l) [hypertext note def] ^.. _word Note:("*") ("cause error") note-tt (m) -------------------- ------------------- --------------- ------------ --- 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) ==================== =================== =============== ============ === 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 ========== **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 <pre> 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 ------------------- 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 .. _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. 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. -Robin Friedrich ================= 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

[PYTHON DOC-SIG] Re: Setext followup (Re: Automatic Documentation)
by friedric＠rose.rsoc.rockwell.com Aug. 5, 1996

Aug. 5, 1996

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(a)geog.gla.ac.uk Tue Jul 30 06:38 CDT 1996 |> X-Mailer: exmh version 1.6.7 5/3/96 |> To: Robin Friedrich <friedric(a)rose.rsoc.rockwell.com> |> From: Tony J Ibbs (Tibs) <gaga50(a)udcf.gla.ac.uk> |> Reply-To: gaga50(a)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(a)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. 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. |> |> 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. |> |> 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? |> 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 harder. |> 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 that almost equally well. 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 <A HREF="http://www.python.org/sigs/doc-sig/">doc strings</A>. Instead, I can use doc_strings_ which flow uninterupted by the http reference. .. _doc_strings http://www.python.org/sigs/doc-sig/ |> |> 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? |> |> Please feel free to quote any of this - I will look into trying to join the |> SIG again... |> |> Tibs |> ------------------------------------------------------------------------------- |> Tony J Ibbs (Tibs) [Funded by Laser-Scan] |> Dept. of Geog. & Topo. Science, Uni. of Glasgow, GLASGOW G12 8QQ Scotland |> Tel: (+44)141-330-6649 Fax: (+44)141-330-4894 |> Email: gaga50(a)udcf.gla.ac.uk - goes direct to here, but I may not be here |> tony(a)lsl.co.uk - forwards to where I am, normally works |> T.Ibbs(a)geog.gla.ac.uk - forwards via gaga50, but is prettier |> |> |> OK I will :-) In summary I remain unconvinced that any of the above mentioned issues are problems with using setext in doc strings. -Robin Friedrich ================= 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

[PYTHON DOC-SIG] gendoc 0.5 broken?
by Rolf Ragnarsson July 30, 1996

July 30, 1996

Hi all! I'm a newcomer to Python trying to get a feel for what's available. Recently I came across gendoc and I thought it would fit my programming style well (use a perl tool right now to pull HTML docs out of my C code). Anyway, I installed version 0.5, but whenever I try to run gendoc it complains about a missing module HTMLgen: > gendoc -f ascii -i *.py > Traceback (innermost last): > File "//7/usr/local/bin/gendoc", line 125, in ? > import formatters > File "/usr/local/lib/python/ni.py", line 259, in import_module > m = self.get0(mname) > > ... lines deleted ... > > File "./formatters/HTMLgenFormatter.py", line 45, in ? > import HTMLgen, regex, string > File "/usr/local/lib/python/ni.py", line 262, in import_module > raise ImportError, "No such module %s" % name > ImportError: No such module HTMLgen > As far as I can tell (correct me if I'm wrong) I'm missing something called "Robin Friedrich's HTMLgen module". Where can I lay my hand on this code? Thanks in advance for any pointers! Rolf --- ) Rolf Ragnarsson, http://milou.msc.cornell.edu/~rolf/ ( ( ( B13 Clark Hall, Net: rolf(a)max.msc.cornell.edu ) ) ) Dept. of Physics/LASSP, Voice: (607) 255-0956 ------ Cornell U., Ithaca, NY 14853-2501 Fax: (607) 255-6428 | |_ | | ) Sleep is just a caffeine substitute... |______|/________________________________________ ================= 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] new gendoc uploaded
by friedric＠rose.rsoc.rockwell.com July 17, 1996

July 17, 1996

The gendoc link on the doc sig page (http://www.python.org/sigs/doc-sig) points to the latest (0.5) release of gendoc by Daniel Larsson. Try it you'll like it:-) Daniel is out on vacation until Aug. 5th. You _might_ direct questions/ comments to me in the mean time;-) -Robin Friedrich ================= 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] gendoc 0.4
by Daniel Larsson July 8, 1996

July 8, 1996

I've just uploaded(*) an updated gendoc, 0.4. Changes since last version: - Added Fred L. Drake's changes to support Python 1.4 (not tested yet:-() - Various bug fixes. - Navigation buttons used by the HTMLg formatter (Robin's HTMLgen module needed). (*): Ken, I forgot to make some doc changes before uploading, so I uploaded twice. Forget gendoc.tar.gz, use gendoc.tar.gz.NEW! -- Daniel Larsson, ABB Industrial Systems AB ================= 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

[PYTHON DOC-SIG] Oops...
by Fred L. Drake July 8, 1996

July 8, 1996

Ouch; I suppose this is what I get for being an "early adopter," but... it turns out I released a module in the version of the modified docco which doesn't have everything needed when running Python 1.3. Specifically, the file v1.3/token.py is missing some predicates that are defined in the v1.4/token.py module. These functions can simply be copied over from the 1.4 version of the file, or you can fetch the (fixed) version of the archive file. Sorry! (Yes, at least one person has actually downloaded the package, so I really had to announce this fix....) -Fred -- Fred L. Drake, Jr. fdrake(a)cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 ================= 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 2

[PYTHON DOC-SIG] Fred's modified docco... finally!
by Fred L. Drake July 7, 1996

July 7, 1996

As I promised David Arnold at IPC-IV, I've finally gotten around to cleaning up my modified version of docco and have it working fairly cleanly for both Python 1.3 and Python 1.4b1. I've written some documentation on the conventions it uses for interpreting docstrings; these notes are available at http://weyr.cnri.reston.va.us/progenv/conventions.html. The modified version of docco can be had at http://weyr.cnri.reston.va.us/progenv/docco.tar.gz. There is not a public link to it right now since I'm currently most interested in comments from others in this group on how I'm interpreting the docstrings. Enjoy, and please send feedback! -Fred -- Fred L. Drake, Jr. fdrake(a)cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 ================= 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