From dgoodger@bigfoot.com Wed Aug 1 04:24:15 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 31 Jul 2001 23:24:15 -0400 Subject: [Doc-SIG] reStructuredText Field Lists: Deciding on Syntax Message-ID: [Sending directly to Edward Loper as well. Comments, Edward?] In "usage docstrings and bibliographic field lists" on Fri, 27 Jul 2001, Garth Kidd wrote: > I think we need to support field list option 3 (``reStructuredText.txt`` > revision 1.1.1.1 line 478) to support PEP-0257 style usage docstrings in > Python scripts without preventing script authors from specifying bibliographic > field lists. He goes on to point out problems with field lists vis-a-vis the "special context" of bibiographic fields (syntax alternative 2; the updated section is appended to the bottom of this message), and how it conflicts with the common practice of program "usage" documentation. For example, in a typical script, the docstring will begin: """ Usage: cmdname [options] arg1 arg2 ... ... """ I agree with Garth's analysis of the problem. The syntax for field lists has been at the back of my mind ever since I included it in reStructuredText: although obvious, it's ambiguous and potentially surprising. I've come to the conclusion that the "special case" syntax was misguided, and only unambiguous syntax of some kind (one of alternatives 3, 4, or 5 [new]) is reasonable. - alternative 3: use a directive:: .. fields:: Author: Me Version: 1 - alternative 4: use Javadoc-style:: @Author: Me @Version: 1 @param a: integer - alternative 5: use leading colons:: :Author: Me :Version: 1 :param a: integer (I recently came up this syntax. It seems to have the best balance: unambiguous, obvious, and elegant. I like it best so far.) Please comment; I'd really like to hear people's opinions about this. Any other alternatives out there? Any answers to the questions asked in [1]_ below? /David P.S. Below, I've appended the current "Field Lists" section, including diff marks (diff to release 0.3). Field Lists ----------- DTD elements: field_list, field, field_name, field_argument, field_body. ! Syntax under construction. Comments and suggestions welcome. Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, numbers, and punctuation, except colons (':') and whitespace. Field names are case-insensitive. A single colon and whitespace follows the field name, and this is followed by the field body. The field body may contain multiple body elements. + Why is RFC822 compliance important? It's a universal Internet + standard, and super obvious. Also, I'd like to support the PEP + format (ulterior motive: get PEPs to use reStructuredText as their + standard). But it *would* be easy to get used to an alternative + (easy even to convert PEPs; probably harder to convert + python-deviants ;-). + + Unfortunately, without well-defined context (such as in email + headers: RFC822 applies before any blank lines only), the RFC822 + format is very common in ordinary text. To implement field lists + unambiguously, we need explicit syntax. + Applications of reStructuredText may recognize field names and transform fields or field bodies in certain contexts. Any untransformed fields remain in the field list as the document's first body element. The syntax for field lists has not been finalized. Syntax alternatives: 1. Unadorned RFC822_ everywhere:: Author: Me Version: 1 ! Advantages: clean, precedent (RFC822-compliant). Disadvantage: ! ambiguous (these paragraphs are a prime example). Conclusion: rejected. 2. Special case: use unadorned RFC822_ for the very first or very last ! text block of a document:: """ Author: Me Version: 1 ! The rest of the document... ! """ ! ! Advantages: clean, precedent (RFC822-compliant). Disadvantages: ! special case, flat (unnested) field lists only, still ambiguous:: ! """ + Usage: cmdname [options] arg1 arg2 ... ! We obviously *don't* want the like above to be interpreted as a ! field list item. Or do we? ! """ ! Conclusion: was accepted (although not yet implemented; see below); ! currently reconsidering. 3. Use a directive:: .. fields:: Author: Me Version: 1 ! Advantages: explicit and unambiguous, RFC822-compliant. ! Disadvantage: cumbersome. 4. Use Javadoc-style:: @Author: Me @Version: 1 @param a: integer Advantages: unambiguous, precedent, flexible. Disadvantages: ! non-intuitive, ugly, not RFC822-compliant. ! ! 5. Use leading colons:: ! :Author: Me ! :Version: 1 ! ! Advantages: unambiguous, obvious? (*almost* RFC822-compliant), ! flexible, perhaps even elegant. Disadvantage: no precedent, not ! quite RFC822-compliant. ! ! One special context is defined for field lists [1]_. A field list as ! the very first non-comment block, or the second non-comment block immediately after a title, is interpreted as document bibliographic ! data. No special syntax is required, just unadorned RFC822_ [2]_. The ! first block ends with a blank line, therefore field bodies must be ! single paragraphs only and there may be no blank lines between fields. ! The following field names are recognized and transformed to the corresponding DTD elements listed, child elements of the 'document' element. No ordering is imposed on these fields: - Title: title - Subtitle: subtitle - Author: author - Authors: authors (a list of author elements) - Organization: organization - Contact: contact - Version: version - Status: status - Date: date - Copyright: copyright This field-name-to-element mapping can be extended, or replaced for other languages. See the implementation documentation for details. + .. _[1] Should "bibliographic field lists" be defined at the parser + level, or at the DPS transformation level? In other words, are they + reStructuredText-specific, or would they also be applicable to + another (many/every other?) syntax? + + .. _[2] Note that this "no special syntax required" provision is being + reconsidered. An unambiguous syntax would also remove the + requirement for a bibliographic field list to end with a blank + line. From fdrake@acm.org Wed Aug 1 18:23:20 2001 From: fdrake@acm.org (Fred L. Drake) Date: Wed, 1 Aug 2001 13:23:20 -0400 (EDT) Subject: [Doc-SIG] [development doc updates] Message-ID: <20010801172320.BE5A72879B@cj42289-a.reston1.va.home.com> The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Incremental updates, including some useful improvements in the docs for the re module. From tony@lsl.co.uk Fri Aug 3 11:01:31 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 3 Aug 2001 11:01:31 +0100 Subject: [Doc-SIG] Comments on DPS and reStructuredText In-Reply-To: Message-ID: <001d01c11c03$45791f90$f05aa8c0@lslp7o.int.lsl.co.uk> OK, folks, I finally had time to read through all of David's documents (whilst on holiday last week), and I've now had time to type up the comments. First off, I should say that there are no show-stoppers as far as I'm concerned - I would prefer some things to be slightly different, but would also be prepared to use reST (hope that abbreviation is OK) as it is, if I could not influence any changes. That may not matter much to other people, but is a vast relief to me (it is also, incidentally, the result I expected to find). I've attempted to write the comments up *using* reST, but I'm fairly sure I'll have done it wrong because I was typing rather than looking up reST syntax. I *shall* be working on a "cheat sheet" or quick reference, for my own use if no-one else's - a *very* early version is at http://homepage.ntlworld.com/tibsnjoan/reST/quick_reST.html, but I need to look at the Python quick reference for inspiration on layout, and do more typing. I've lumped my comments up by source, so they are: * DPS comments * comments on PEP 257's example * reST comments * comments on reST "notes" * comments on "problems with structured text" * some notes on reST "modes" I'll email them separately to the list. They're also available in the same directory as the quick reference mentioned above. I still want to write something on "field labels" (what were "paragraph labels") and maybe on descriptive lists, but that will have to be another day. Oh - and if MoinMoin starts to use reST, that would be *brilliant*! Sorry for the vast delay in producing any input - hope this helps... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Fri Aug 3 11:01:36 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 3 Aug 2001 11:01:36 +0100 Subject: [Doc-SIG] Comments on the DPS texts Message-ID: <001e01c11c03$47fae870$f05aa8c0@lslp7o.int.lsl.co.uk> ############ DPS comments ############ Hmm - let's see if *I* can write in reST, without too much reference to the documents (memo to self: prepare cheat sheet). PEP 256 (DPS framework) version 1.1.1.2 of 2001/07/19 ===================================================== .. namespace:: 256 is pep-0256.txt [1]_ .. namespace:: 257 is pep-0257.txt 256:`Abstract`_[1]_, paragraph 1: You don't explicitly mention methods. Whilst a method *is*, technically, a function, I think it *would* be better to include them here as well (as, for instance, is done in the first paragraph of 257:`What is a Doscstring?`_). In the same paragraph, in the second sentence, you say: inside the definition which I think would read better as, for instance: inside their definition (but this one is *very* much a matter of style). 256:`Abstract`_, paragraph 2, last sentence: You say "The issues surrounding docstring procesing have been contentious and difficult to solve". Indeed. 256:`Rationale`_ I think that you should add Edward Loper to the list of previous attempts at writing systems. His approach of rigorous definition, and dissection of differences between systems, is to my mind quite important. Other than that, I think this section is an excellent summary. 256:`Specification`_ The diagram at the end of this is indeed much too wide, and really needs redrawing, preferably as an image (even though PEPs don't currently support that). Footnotes --------- .. [1] Hmm - it is useful in a document like this to be able to refer to targets in another document. I've "invented" the `namespace` directive for this purpose, but I don't pretend to like it, nor do I particularly think that I've got the syntax for *using* a namespace correct. Regard it as a naff convention for these documents only... Miscellaneous notes ------------------- We should explicitly allow control-L (formfeed) in documents. It is *very* useful in navigating around documents which are in plain text, especially in the Emacs family of editors. PEP 257 (Docstring conventions) version 1.2.1.1 of 2001/07/19 ============================================================= .. namespace:: 257 is pep-0257 .. comment:: yes, I know that's a duplicate declaration - I assume that that is allowed and will work? (i.e., have no effect if the same, and override if different). 257:`What is a Docstring?`_ The first paragraph of this, first sentence, gets the list of places a docstring can occur correct - apply elsewhere as appropriate. In the second paragraph after the little two item list, you describe """..""" and r"""..""" strings, but not the Unicode variants thereof. I think they should be explicitly mentioned, as how one gets Unicode into docstrings, or else as not being allowed (for the moment) for docstrings (surely that last is not the situation). 257:`One-line Docstrings`_ Hmm. When discussing the "signature" in C functions - shouldn't the DPS mandate that this signature line should be (a) of a particular format [the obvious one!], and (b) that the tool "looking for" and interpreting code structure should make use of said signature if present. 257:`Multi-line Docstrings`_ Guido's example as presented:: def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the imaginary part (default 0.0) """ if imag == 0.0 and real == 0.0: return complex_zero ... is not valid reST_. Whilst that's not entirely unreasonable (since the DPS is not tied to reST), it would, I think, be consistent if it were recast as such. However, trying to do that has some interesting implications, so I'll address it separately [2]_. 257:`Multi-line Docstrings`_ At the end you say: "This way, Emacs' fill-paragraph command can be used on it." Is this a problem in modern [X]Emacs? - ah, I see it still is. Since presumably we will ultimately be wanting to have an reST mode for [X]Emacs, as a subsidiary mode within Python mode (or however one describes it), I think that this requirement should be removed. Miscellaneous notes ------------------- OK, I remembered why I sometimes want non-breaking spaces. In contexts such as ``PEP 258``, it does not make sense (in the presented text) to split the line between the two "words". This is important for things like ``ISO/IEC 8211`` as well - normal presentation standards require one *not* to split between the two parts. I can see that people may say "so what, put up with it", but since a lot of my coding has *been* with reference to standards, getting this wrong in the presented documentation is *not* something I want to do - it make me look dumb, as if I did not know what I was doing, not something I favour (!). On the other hand, how to get round it? Maybe we just need to allow an escaped space to be a non-breaking space - since I lost the backslash battle, I might as well lose it thoroughly. In which case my examples would be written "PEP\ 258" and "ISO/IEC\ 8211". Now, personally I think that reads horribly in the plain text, but if my aim is actually to produce *documentation* from docstrings, it may be just good enough... References ---------- .. [2]: see pep257example.txt .. _reST: obviously, reStructuredText. PEP 258 (DPS generic implementation details) version 1.1.1.3 of 2001/07/19 ============================================ .. comment:: OK, so I've found an instance of a multi-line header... .. namespace:: 257 is pep-0257 .. namespace:: 258 is pep-0258.txt 258:`Docstring extraction rules`_ item 2.a The same comment applies as in other places about mentioning methods as well as functions. See 257:`What is a Docstring?`_, first paragraph. 258:`Docstring extraction rules`_ item 3 At the end of the first paragraph, you say "Of course, standard Python parsing tools such as the 'parser' library module should be used.". I think that is too strong a statement - it should either say "may be used" or it should say something more like "are likely to be used in general". 258:`Attribute docstrings`_ item 1 Does this really mean to leave functions out? That is, can one really not do:: def fred(): a = 1 """``a`` is a silly name for a value.""" This seems a bit of a limitation to me - admittedly I don't have PEP 224 (or any of the commentary on it) to hand here. 258:`Additional docstrings`_ When you say "this breaks 'from __future__ import'" can you give more context (you don't refer to a PEP, and also I don't off hand remember how __future__ imports work in detail, so an explanation *at hand* would be a very good thing). If it means what I think it means (that the __future__ statement must be the first statement in a module, excepting a docstring (and presumably another __future__!)), it would seem that option 2 is the obvious one to adopt. If there *are* going to be additional docstrings, can I ask that we have some way of *identifying* them - consider a (future usage) of a parser (using a docstring to store parse rules) within something like Zope (where a docstring is/was used to provide other information) -- here one might notionall have three docstrings, and still claim not to be insane. Identifying them in some way would seem absolutely necessary... For instance:: def information_overload(fred): """A simple function with too much metadata. fred -- the only argument, should be Fred's surname """ """.. zope:: """ """.. yapps:: """ (OK, maybe it's a bit cheeky leveraging off directives.) 258:`Choice of Docstring format`_ This sounds sensible to me. I had thought over the implications of allowing the user to specify different formats at different places in a module (and even at different "levels" - e.g., within a class), but it's clearly not worth the hassle, and unlikely to be useful. The default of "plaintext" seems sensible - indeed, it's not clear to me that one need change it *ever*, since plain text is always a valid form of documentation. I suggest format names are something like: - "plaintext" (the default) - "reST" (reStructuredText) - "ST" (StructuredText - for Zope compatibility, and thus maybe deprecated) - "STNG" (StructuredTextNG - ditto) Other names OK, so the DPS is responsible (in some sense) for the __docformat__ name. Should it also be aware of some of the other (semi) standard names that people use - the following are ones I'm aware of: * __author__ * __version__ * __history__ (this is less common) * __copyright__ (I've just made this one up) Whilst these are in the Python, rather than in the docstrings, they clearly *are* part of the documentation, and are clearly things that the user will want a documentation presentation tool to show to them. 258:`Intermediate data structure`_ It should be made clear(er) that the DOM tree is intermediate between the input parser and the output formatter - it is not a requirement for the *internal* workings of either. The first sentence of this section reads as if it means that the input parser *must* use the DOM tree inside itself. 258:`Output management`_ The final sentence: "Use a directory hierarchy ... couldn't run on MacOS)" doesn't make sense to me - please explain it. 258:`Error handling`_ Good. Of course, these correspond to the VMS information, warning, error and fatal message levels (and those might be good names to use for them). -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Fri Aug 3 11:01:42 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 3 Aug 2001 11:01:42 +0100 Subject: [Doc-SIG] Comments on the reST specification Message-ID: <001f01c11c03$4beb8390$f05aa8c0@lslp7o.int.lsl.co.uk> ######################### reStructuredText comments ######################### .. comment:: same conventions used as in the DPS commentary, and doubtless the same formatting mistakes (I really want that cheat sheet - I'll work on it another day). ((For some reason, attempting to print the project history file from PFE on Windows NT caused PFE to fall over. Very odd.)) ((NB: yummy treats can't be sent over the internet - one needs a snail mail address.)) An introduction to reStructuredText version 1.12 of 2001/07/10 ============================================================== .. namespace:: intro is introduction.txt intro:`An introduction to reStructuredText`_ This is a good docuement - I like it. intro:`Goals`_ A tertiary useful goal, for many of us (well, for me at least) is just to have *some* form of structured text, to read *as such*, for use in docstrings, and for reading within docstrings. That is, specifically an enhanced plain text, a set of conventions universally recognised that allow more expressiveness for those of us lazy enough to want it with markup rather than literary skill. intro:`Goals`_ The list of numbered items is a good list of the design goals. I've got a note against the second paragraph of the "Author's note": "There will inevitably be people... ...reasonable people." which says simply "Yes". intro:`History`_ Regarding the paragraph that starts "In March 2001 a flurry", I would point out that for *some* of us, the markup is still preeminent - but a framework approach actually *increases* the chance of the markup being accepted and becoming predominant, so we should be happy as well, in the end. reStructuredText Markup Specification version 1.41 of 2001/07/20 ================================================================ ..namespace:: spec is reStructuredText.txt Hmm - to someone reading the raw text, it can be useful to know whether a link is to a target in the document or outside it. Of course, this can be done (and probably *should* be done, by a good author) by writing the text correctly - e.g.:: as discussed in section `Fred Bloggins`_. spec:`Quick syntax overview`_ In describing paragraphs, you use the term "flush left". To me this means "flush against the left margin". Either "left justified" or (as you use elsewhere) "left aligned" would be better. Tables are good - thanks. Comments - I'll come back to these later on. spec:`Syntax details`_ I'm afraid that diagram doesn't mean much to me - it's too complex for me to digest easily. Unfortunately, I haven't read the DTDs yet, either, so I'll have to trust you on the nesting issues... spec:`Whitespace`_ You don't mention what happens if there are multiple blank lines between paragraphs, etc. I assume that multiple successive blank lines are equivalent to a single blank line, except (of course) within literal blocks. The phrase "one or more" comes to mind... Pedant mode on indentation: you say it is "used to indicate, and only significant in indicating" and give a list of cases. It is, of course, retained (and thus in some important sense significant) inside literal blocks as well (and since its "absence" indicates the *end* of a literal block...). As to spaces versus tabs - this sounds like it will lead to all of the traditional discussions we get on the Python list about whether one can mix spaces/tabs, and whether a tab is *really* 8 or 4 spaces, leading finally to space eating nanoviruses (ick). I'd suggest that this is dangerous territory, and that the behaviour of tabs should be carefully undefined. spec:`Section structure`_ You don't say which characters may be used as "underlines" for section titles. Can I really do:: aaaaaaaaaaaaaaa This is a title aaaaaaaaaaaaaaa Further down you say "nor must any specific section title style be used". I think that "must" would be better as "need". spec:`Bullet lists`_ The first incorrectly formatted example is also indented incorrectly - make it say so! spec:`Enumerated lists`_ The syntax diagram is missing. spec:`Field lists`_ I want to discuss these elsewhere. I think life is getting too complex, and too far away from what I specifically want. spec:`Tables`_ In the example, in the cell that contains lines starting ``-``, does that content count as a list? If so, the cell boundaries (top and bottom) must be acting as the delimiting blank lines - say so. spec:`Footnotes`_ "an left square bracket" - should be "a". "case insensitive single words" is unclear to me - it gets explained later on, so maybe that explanation could be shifted or copied? spec:`Hyperlink targets`_ "whitespace neutral" doesn't mean anything to me. When you say they may contain whitespace, clarify if you include newlines (some people include this as whitespace, some not). Yes, I know the examples later on make it clear, but it would be nice to be clear up front in the text. Is it allowed to use *redundant* backquotes - for instance:: .. _`a b`: .. _`ab`: (I assume so, but it's not obvious.) spec:`Comments`_ Arbitrary text after a ``.. `` is treated as a comment. I don't think this is right. Initially, I didn't see *any* point to having comments, but you'll see I've used them occasionally in these notes. But I think the way to introduce a comment is with a "proper" named directive:: .. comment:: this is a comment, and it continues in the normal manner for a directive. I believe strongly that a directive that does not start in a legitimate manner should be treated as a "warning" (type 1 error?) and that an output processor should (by default) not place its text into the output, although it should allow the option of presenting it in some delimited manner (perhaps in a different colour). Part of this is just that I think a comment (if used) should be explicitly identified as such, but mostly it's for compatibility with Stretch - i.e., I don't want to be able to write a comment of the form:: .. not defined, for some reason and later discover that directives have been extended to make this have behaviour I don't expect. As it is, with the proposed scheme in the document, I can't start comments with text that looks like a hyperlink target, etc., nor with a "word" followed by two colons. That's already too many caveats to remember for what can't be in a "comment". I think we get a more robust format if: 1. Comments are a directive like any other:: .. comment:: some text Heh - it even says what it is! 2. Anything that is not a directive or a hyperlink target or a footnote (I forgot those above - sorry) is of undefined behaviour, and will generate a warning. This allows for extension in all sorts of ways in the future, with minimal restriction. Incidentally, this would also mean that directives can use a single colon as a delimiter - I think this would be easier to remember, but can't say I'm too fussed (presumably a decent parser will warn me every time I forget that second colon - slight sarcasm there, I'm afraid). spec:`Inline markup`_ Item 1 says that inline markup start strings must be immediately preceded by whitespace and zero or more of various characters. This precludes having a start string at the start of a file, and maybe even at the start of a paragraph (depending on how one views the whitespace (blank line) that indicates the start of the second and successive paragraphs). Item 5 mentions '<' and '>', but items 1 and 4 do not. I assume this is a mistake. spec:`Interpreted text`_ I'm not too keen on having the "role" inside the string (as you might guess from my attempt at "namespaces" in these notes). I assume that the compelling reason, for you, is a wish to allow whitespace in the role name (whereas I'd overgeneralise RFC 822, or perhaps XML names, or Python identifiers, or something). Personally, I think:: role:`interpreted text`_ to:: `role: interpreted text`_ because I think the former is easier for *me* to parse (e.g., specifically as something like class:`Fred`_ - the quotes go around the *name* which feels right). Ultimately, of course, this comes down to an issue of taste (all parsing being equal), so I'm prepared to go down grumbling on this one if needs be (but you already know I can grumble for a long time...). By the way, it is not acceptable to leave out a description of how to determine the difference between (for instance):: `role: Fred`_ `role: Fred`_ in some arbitrary application where the former is identifying a role, but the latter is identifying something *called* (legitimately) "role: Fred" - and whilst I can't come up with a concrete example now, this disturbs me greatly (and is perhaps the main reason I prefer to move the role name outwith the string). spec:`Hyperlinks`_ This made more sense when I realised you'd been doing a Grand Unification of setext and ST. But the "_" had to go at one end or the other, and designer gets to choose... spec:`Standalone hyperlinks`_ You need to explain the explicit rules used to detect such an animal, otherwise this is too vague. Miscellaneous notes ------------------- I understand (now) that the two-dots-and-a-space-after-newline convention is taken from setext, but why does it need to be two dots *and a space* - given it must occur after a newline (and optional whitespace, of course), is there a compelling reason for the space, or is it just for compatibility? Would it be better without the space? It is not clear to me whether the output formatter should: a) "fold in" indirect hyperlinks, or b) treat them just the same as internal crossreferences, or Probably both behaviours should be choosable with a command line switch. See http://www.tibsnjoan.co.uk/further2.html for an example of the "folded in" style, and http://www.tibsnjoan.co.uk/further3.html for the same text where external hyperlinks are *not* folded in. Clearly one is better for online viewing as HTML and the other for printing. Python extensions version 1.19 of 2001/07/20 ============================================ .. namespace:: py is pyextensions.txt py:`Option lists`_ I don't think these belong here. These are not *Python* options - these are Unix shell command options (with common GNU extensions). They can clearly be dealt with by other means, and should be so. Alternatively, try defining a new syntax for "tabbed tables" (something like the facilities available in LaTeX) - something that looks like:: .. -a :: Output all .. -b :: Output both (this description is quite long) might sort of work, if I could figure how to introduce it) But ultimately, this is really only doable in a neat manner with "proper" descriptive lists, like:: -a -- Output all -b -- Output both and that's a discussion best held elsewhere. Anyway, they're still not part of a Python specific mode. py:`Doctest blocks`_ Good - this is necessary, and it is indeed Python specific. py:`Interpreted text`_ As said elsewhere, use of `..` (undecorated with "_") to indicate Python "elements" is a neat idea (if one doesn't want to use '#..#'). I agree that the use of roles to disambiguate this is helpful, *but* I've already said elsewhere my problems with the specific way of doing it. I can't help feeling we shouldn't need as *many* roles as you enumerate - how is a poor user to keep track, especially of the ones that aren't part of normal Python terminology (like "instance attribute"). "Class attribute" (for instance) is too long, and "classatt" too horrible - if we're producing these, it means we need to think longer about how to specify Pythonic roles. What is a "warning" or "warning class"? The "argument" role is missing. Specific recommendation: use "name" instead of "variable" (what's the other recommendation that goes with that?). -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Fri Aug 3 11:01:57 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 3 Aug 2001 11:01:57 +0100 Subject: [Doc-SIG] Comments on the reST notes Message-ID: <002101c11c03$54e41d40$f05aa8c0@lslp7o.int.lsl.co.uk> reStructuredText notes version 1.29 of 2001/07/20 ================================================= .. namespace:: notes is rst-notes.txt notes:`Enumerated lists`_ I would say that worrying about "compound enumerators" is not worth the mind space. Let someone provide a convincing demonstration of why they want it before worrying about it. notes:`Literal blocks`_ I don't understand what you are wanting the triple-quotes convention to do - I'm presumably being dumb but the explanation doesn't convey anything to me, nor does it explain why you want to do this. notes:`Indentation of list items`_ .. comment:: NB: not needing to match case in links is *really* a good idea! I think that sloppy indentation should only be tried out when needed (which it sounds like the Wiki folk might want) because of the ramifications you've already discussed elsewhere. (Basically, in the "normal" context, I agree with you that "non-strict indentation isn't such a good idea - and for interests sake, I'm managing OK in XEmacs to type all of this without much support for indentation, even though I'm making heavy use of descriptive lists.) NB: I'm assuming that we do explicitly allow:: 9. This is some text that lines up like this. 10. And obviously this text lines up one space further right. notes:`Horizontal rules`_ The solution is to introduce them into a mode specifically for producing HTML documents, and leave them out of other modes (since other modes may also be used for producing other sorts of output format). notes:`Parser notes`_ Incorrect indentation should: a) generate a warning (level 1?) b) produce a *predictable* (i.e., defined in the documentation) result as a best guess - cf. what I tried to do in docutils, where it makes a consistent best guess based on the preceding indentation levels. Edward Loper may well have useful input on this as well. c) optionally highlight the offending text in some manner, so it is obvious that the indentation is dodgy and should not be trusted (this will help a user trying to interpret output data produced by a careless author who didn't remove warnings!). Note that use in "batch" environments (such as Wikis) will alway require a reasonable best guess, since they produce the visible documentation (HTML) from the internal format, and there is no author to ask if that internal format is in error. -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Fri Aug 3 11:02:03 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 3 Aug 2001 11:02:03 +0100 Subject: [Doc-SIG] Comments on the "problems with structured text" Message-ID: <002201c11c03$582f9ec0$f05aa8c0@lslp7o.int.lsl.co.uk> Problems with StructuredText version 1.32 of 2001/07/20 ======================================================= .. namespace:: prob is problems.txt prob:`Formal Specification`_ "preceed" should be "precede". prob:`Understanding and extending the code`_ Paragraph 1: I'm glad someone else thinks so! Paragraph 2: last sentence: yes, good. prob:`Section structure via indentation`_ Paragraph 1: agreed. List - first item: yep. List - third item: "is indistinguishable from..." - erm, no it isn't (since the docstring will have been processed to sort this out first, one would hope!). Oh - maybe that's not true in ST[NG]. (I thought it was OK in STNG?) prob:`Character escaping mechanism`_ After the paragraph starting "The best choice for this...", maybe add a note along the lines of: The opinion of the BDFL that this is the way to go, whilst not conclusive, should be taken strongly into account. prob:`Bullet list markup`_ Dropping the "o" - sensible. prob:`Enumerated list markup`_ Nested enumerated list without indentation - I'd say this is a bad idea - it's more complex, more ambiguous, and doesn't seem to me to give any realistic gain. prob:`Definition list markup`_ I don't particularly expect to change this, but I want to discuss it elsewhere. I find it interesting that the BDFL proposal sounds like what *I* thought he described as a layout he didn't like, when he was saying he didn't like descriptive lists. But I haven't checked that, and my memory *is* unreliable. prob:`Literal blocks`_ I still think the distinction of whether there's a space before the "::" or not is a bit naff, but it does serve a useful purpose, and David obviously likes it. The "::" on a line by itself thing is also a bit naff (even though I came up with it), but it is also useful, and it does "fall out naturally" (sort of). prob:`Tables`_ This is good. Does the Emacs mode support "====" lines? (I agree that option 2 is not as useful, and should be ignored.) prob:`Inline literals`_ "In the UK, single quotes are used for dialogue in published works." Hmm - no more than double quotes, I'd say - you've been reading old books on printing again, haven't you? As to the argument as to what sort of quotes to use - I think the argument for backquotes *is* compelling. The "TeX" use of directed quotes never actually looks right in plain text using normal fixed width fonts, so is not an option for that reason alone. prob:`Hyperlinks`_ In "Alternatives" item 2, you use the phrase "de-emphasize the URI", which doesn't make any sense to me. Do you mean "stop it being *recognised* as a URL"? (anyway, I do realise it's only commentary describing an option not taken). You don't mention the (rejected) option of enclosing URIs in "<" and ">" (cf. email, etc). One major objection to this was the BDFL's note that it was important to be able to write XML/HTML/SGML in text without needing to quote it, and use of such a convention would make that impossible. In the "Alternatives" section, option 3 makes it clear that you are actually performing something of a Grand Unification of the ideas and techniques from ST and setext (with some new ideas added, of course). I actually think that you should maybe mention (boast about?) this up-front in the description of reST (whilst, of course, pointing out that you are not being bound by the previous "standards" when it does not seem sensible). Later on, the paragraph "The two-dots-and-a-space syntax was generalized by Setext for comments," is useful history, but I think not a justification for *retaining* `.. arbitrary text` as a comment... -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Fri Aug 3 11:02:09 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 3 Aug 2001 11:02:09 +0100 Subject: [Doc-SIG] Suggestions for reST "modes" Message-ID: <002301c11c03$5b9e38a0$f05aa8c0@lslp7o.int.lsl.co.uk> reStructuredText "modes" ======================== "raw" or "plain" mode --------------------- This is the default - nothing special. It should actually be sufficient for a good many documents. Python docstrings ----------------- Adds a way of indicating a Python value: ``self.thing()``, and some form of disambiguating those if necessary. Doctest blocks, as in pyextensions.txt. I think that is *all* that is needed. NB: in the Python source code, have a variable which defines what form the following docstrings take:: __docformat__ = "raw" "raw" is the default, "reST" is reStructuredText, "ST" is StructuredText, etc. ((check all of this - I think I've got it vaguely wrong)) Email ----- Adds RFC style headers, in a single block, at the start of the text. Recognises signature delimiter at the end, and treats that as if it were typed:: -- :: Recognises various common forms of quoting for blocks of text that are being replied to (sorry, the proper term escapes me!). Steal ideas vigorously from the relevant Emacs modes... PEP --- Has a header block similar to that of Email, but with limited keys allowed (i.e., the ones allowed in PEPs). Otherwise, pretty plain reST. A special output formatter is provided to produce "original" PEP format from the reST PEP format (as well, of course, as direct output to HTML, etc.) Wiki ---- Allows any word of the form ``word_`` to be looked up in the document itself, and if it is not found, looks it up as a Wiki link word. Thus one can create a WikiLink_, or indeed a wikilink_. One does not need the to !EscapeThings, because they're not links unless made so. One also doesn't need [this] because one can do this_. May want to provide lazy indentation:: Lists that format like this: 1. This is the first list item and it can continue here. 2. But the second list item *must* be separated from the first by a blank line. This won't be so onerous in a Wiki, I think, where the raw text is *not* the primary means of reading it (heck, if people can put up with things like """"""this means something""""" then they can cope with that limitation!). HTML/XHTML/etc. --------------- May want to provide special support - for instance:: --------------------------------- (i.e., 3 or more hyphens) separated by blank lines before and after means
. A directive to include a diagram, figure, etc. (follow the examples given in Book/paper/document ------------------- Some more directives, such as:: .. newpage:: will be needed. I suspect that a means of marking Chapter, Appendix, etc., explicitly may be needed - maybe by doing:: Chapter: This is a title ======================== This chapter is numbered implicitly. Chapter 3: Another name ======================= But this one *is* chapter 3. And both titles must use the same "underline" because they both call themselves chapters. with some predefined hierarchy (as, for instance, provided by LaTeX). (oh - and diagrams/figures as in HTML mode will be needed as well.) -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Fri Aug 3 11:01:53 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 3 Aug 2001 11:01:53 +0100 Subject: [Doc-SIG] Comments on the PEP 257 example Message-ID: <002001c11c03$5257a600$f05aa8c0@lslp7o.int.lsl.co.uk> Looking at Guido's example docstring ==================================== Guido's example as presented:: def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the imaginary part (default 0.0) """ if imag == 0.0 and real == 0.0: return complex_zero ... is not valid reST_. Whilst that's not entirely unreasonable (since the DPS is not tied to reST), it would, I think, be consistent if it were recast as such. Trying to do this might, for instance, give us:: def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real the real part (default 0.0) imag the imaginary part (default 0.0) """ if imag == 0.0 and real == 0.0: return complex_zero ... Mind you, at this point I think one can see that Guido won't want to *use* a descriptive list for this, as we know he dislikes that appearance (indeed, the original example is much easier to read). It also becomes clear why I wanted "paragraph labels" to work as I had them, so that one can *identify* that one has arguments to be worked on. A title won't do, because one doesn't want a title for the text that might *follow* the arguments... There's more I want to write on this - an updated version will follow at some time... -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From Juergen Hermann" Message-ID: On Fri, 3 Aug 2001 11:01:31 +0100, Tony J Ibbs (Tibs) wrote: >Oh - and if MoinMoin starts to use reST, that would be *brilliant*! It's not if, but when. The when is mainly influenced by the exitence of = an easy to use and/or well documented reusable processing engine. The current formatter interface will be remodelled btw, latest in my holidays (next month). Ciao, J=FCrgen From tony@lsl.co.uk Fri Aug 3 15:33:05 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 3 Aug 2001 15:33:05 +0100 Subject: [Doc-SIG] Comments on DPS and reStructuredText In-Reply-To: Message-ID: <002601c11c29$35202320$f05aa8c0@lslp7o.int.lsl.co.uk> On MoinMoin supporting reStructuredText, Juergen Hermann wrote: > It's not if, but when. The when is mainly influenced > by the exitence of an easy to use and/or well documented > reusable processing engine. In other words, as soon as practically possible, and presumably you'll be a useful input into whether the engine is considered "easy to use". My reason for being enthusiastic is that I have a couple of projects (*neither* of which is likely to be very soon!) which could use a Wiki, and MoinMoin has various Good Things going for it... > The current formatter interface will be remodelled btw, > latest in my holidays (next month). Ah - I remember holidays like that... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From fdrake@acm.org Sat Aug 4 03:03:38 2001 From: fdrake@acm.org (Fred L. Drake) Date: Fri, 3 Aug 2001 22:03:38 -0400 (EDT) Subject: [Doc-SIG] [development doc updates] Message-ID: <20010804020338.338B82879B@cj42289-a.reston1.va.home.com> The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ A variety of updates, including the first installment for the distutils API docs (in "Distributing Python Modules"), and some contributed material on embedding Python (in "Extending and Embedding the Python Interpreter"). There were many other small improvements and bug fixes. From dgoodger@bigfoot.com Sat Aug 4 15:51:21 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Sat, 04 Aug 2001 10:51:21 -0400 Subject: [Doc-SIG] Re: Comments on DPS and reStructuredText In-Reply-To: <001d01c11c03$45791f90$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Thanks, Tony, great input! I guess now it's *my* turn to be overwhelmed. ;-) I'll be replying to your messages over the next few days. BTW, the two SourceForge projects now have CVS and mailing lists set up. Please subscribe to any or all of docstring-develop, docstring-checkins (CVS messages), structuredtext-develop, and structuredtext-checkins. DPS mailing lists are at: http://sourceforge.net/mail/?group_id=26626 reStructuredText mailing lists are at: http://sourceforge.net/mail/?group_id=7050 On "reST": interesting acronym. Pronounced how? As in, "to rest"? Or as "ree-ess-tee"? I've been using RST. on 2001-08-03 6:01 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote: > I've attempted to write the comments up *using* reST, but I'm fairly > sure I'll have done it wrong because I was typing rather than > looking up reST syntax. Mostly spot-on. Apart from the corrections below, I noticed you sometimes added an underscore when you meant to use interpreted text. Underscore means hyperlink. > I *shall* be working on a "cheat sheet" or quick reference, > for my own use if no-one else's - a *very* early version is at > http://homepage.ntlworld.com/tibsnjoan/reST/quick_reST.html, Very useful. Some corrections: - "Inline Markup": ``footnote references: [5]_`` is given, but in footnote 4, "rep77" is the footnote label. - "dot, dot, space": 1. Body row 2: the internal hyperlink is wrong:: .. _example: The ``example_`` above points to this target. It should be:: .. _example: The ``example_`` above points to this target. Anything after the ":" on the hyperlink target is interpreted as a URI: "Internal hyperlink targets have empty link blocks; they point to the next element. Indirect hyperlink targets have an absolute or relative URI in their link blocks." 2. Your footnote 6 says:: [6] It is not clear to me whether the output formatter should "fold in" indirect hyperlinks in this fashion, or whether it should treat them just the same as internal crossreferences, or whether both behaviours should be choosable with a command line switch... After reading your article "Would you trust something you had to pay for?", both versions, I see what you mean. For "fold in", you mean: the normal way HTML hyperlinks work, with arbitrary text (typically underlined and in a different colour) fronting for the URI, which is not visible in the text. For the alternate, you mean: automatically generated footnote references and footnotes, the latter containing the URI as a standalone hyperlink, visible in the text. Let's call this alterate form, "callout". I see how the "callout" form would be useful. How to represent hyperlinks is indeed an issue for the output formatter. For HTML, the default would be to fold them in. Perhaps just clarify that the representation *is* a matter for the output formatter, and you're just displaying one possible representation. That applies to the whole page though. Good article, BTW. - "Lists": 1. Bullet lists: Item 3's "typical result" is missing some text (full stop after "+" to "whitespace."). It should be rendered as a single paragraph. 2. Enumerated lists: "List items should be sequentially numbered, but need not start at 1." It may not be a good idea to start at anything other than 1/A/I: the output format may not support an arbitrary start value. I plan to generate a level-0 warning if a list starts with ordinal-1. 3. Definition lists: The spec (and the parser) require blank lines between definition list items. This requirement could be relaxed, as it has been for other lists. What do you think? > Sorry for the vast delay in producing any input - hope this helps... Helps enormously -- thanks a lot. The more brains this stuff gets filtered through, the better the end result will be. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From ping@lfw.org Sat Aug 4 22:14:41 2001 From: ping@lfw.org (Ka-Ping Yee) Date: Sat, 4 Aug 2001 14:14:41 -0700 (PDT) Subject: [Doc-SIG] Re: Comments on DPS and reStructuredText In-Reply-To: <001d01c11c03$45791f90$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: I know i have been silent on this list for a long time and i apologize for barging in, but something startling just caught my eye: On Fri, 3 Aug 2001, Tony J Ibbs (Tibs) wrote: > I've attempted to write the comments up *using* reST, but I'm fairly > sure I'll have done it wrong because I was typing rather than looking up > reST syntax. Uh, read that sentence again. Am i the only one that finds it a bit frightening? -- ?!ng From dgoodger@bigfoot.com Sun Aug 5 05:38:27 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Sun, 05 Aug 2001 00:38:27 -0400 Subject: [Doc-SIG] Re: Comments on DPS and reStructuredText In-Reply-To: Message-ID: on 2001-08-04 5:14 PM, Ka-Ping Yee (ping@lfw.org) wrote: > I know i have been silent on this list for a long time and i apologize > for barging in, but something startling just caught my eye: > > On Fri, 3 Aug 2001, Tony J Ibbs (Tibs) wrote: >> I've attempted to write the comments up *using* reST, but I'm fairly >> sure I'll have done it wrong because I was typing rather than looking up >> reST syntax. > > Uh, read that sentence again. Am i the only one that finds it a bit > frightening? Why should you? The reStructuredText spec says it should be "easy to read without any prior knowledge of the markup language" (goal #1 from introduction.txt). Nobody said it should be easy to *write* without any prior knowledge. Reading should be transparent; writing takes a little training. A very little, I hope. Kind of like Python. Show a C programmer a Python program, and they will probably be able to understand it. That doesn't mean that they can write one without some learning first. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From garth@deadlybloodyserious.com Sun Aug 5 14:07:24 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Sun, 5 Aug 2001 23:07:24 +1000 Subject: [Doc-SIG] Comments on the DPS texts: __version__ In-Reply-To: <001e01c11c03$47fae870$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Lots of good stuff, which I'll respond to later, but one thing jumped out at me: > * __author__ > * __version__ > * __history__ (this is less common) > * __copyright__ (I've just made this one up) I like __copyright__ a lot. I'm sick of using pydoc.help in the interpreter and having to page through screens of licenses to be able to find out what a module does. Putting it in a separate attribute makes a LOT of sense. I'd also like to see the use of $Revision$ in __version__ deprecated. It just bugs me, for some reason. In particular, I think __version__ in a module's __init__.py should be reserved for the explicitly defined version of the *module* (and thus directly useful for programmatic "if __version__>blah then I can assume certain functionality" tests), not for the revision of __init__.py itself. People who love CVSisms and RCSisms in their code should instead use:: __id__ = "$Id$" We could encourage this usage by providing as part of dps a mechanism which automatically parses __id__ and breaks it out:: $Id: setup.py,v 1.1.1.1 2001/07/21 22:14:04 goodger Exp $ might become (with a little validation from ppdi.dtd): setup.py 1.1.1.1 2001/07/21 goodger Exp Better yet, we could patch the Python inspection mechanism to provide the break-out for us. :) Regards, Garth. From dgoodger@bigfoot.com Sun Aug 5 18:26:28 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Sun, 05 Aug 2001 13:26:28 -0400 Subject: [Doc-SIG] Comments on the DPS texts In-Reply-To: <001e01c11c03$47fae870$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: on 2001-08-03 6:01 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote: > PEP 256 (DPS framework) version 1.1.1.2 of 2001/07/19 > ===================================================== > 256:`Abstract`_[1]_, paragraph 1: > > You don't explicitly mention methods. Added. > inside their definition ^^^^^^ Done. > 256:`Rationale`_ > > I think that you should add Edward Loper to the list of previous > attempts at writing systems. Yes, I'd been meaning to; will do so now. He promised to send the most up-to-date URLs, but then disappeared. Are you out there, Edward? > 256:`Specification`_ > > The diagram at the end of this is indeed much too wide, and really > needs redrawing, preferably as an image (even though PEPs don't > currently support that). Added to the dps-notes.txt To Do list. Will do when (a) it's possible and (b) I have time; not necessarily in that order. > .. [1] Hmm - it is useful in a document like this to be able to refer to > targets in another document. I've "invented" the `namespace` directive > for this purpose, but I don't pretend to like it, nor do I particularly > think that I've got the syntax for *using* a namespace correct. Regard > it as a naff convention for these documents only... So you're suggesting a "namespace" (working name) directive which dynamically defines a base hyperlink, to which the hyperlink itself is appended? Would this apply to hyperlinks only, or also to interpreted text roles? I think something like this would be useful. Garth Kidd brought it up recently as well. I don't know how it could be implemented though. I've downloaded the XLink and XPointer docs, and have a past familiarity with HyTime. Added to the rst-notes.txt To Do list. > We should explicitly allow control-L (formfeed) in documents. ^L is whitespace, and thus permitted. I'll explicitly define what characters constitute whitespace, and make sure the parser knows too. > PEP 257 (Docstring conventions) version 1.2.1.1 of 2001/07/19 > ============================================================= > > .. namespace:: 257 is pep-0257 > > .. comment:: yes, I know that's a duplicate declaration - I > assume that > that is allowed and will work? (i.e., have no effect if > the same, and > override if different). Since the "namespace" directive doesn't exist yet, its semantics can be anything you like! Obvious caveat: to get your semantics, *you've* got to implement it! > 257:`What is a Docstring?`_ > > In the second paragraph after the little two item list, > you describe > """..""" and r"""..""" strings, but not the Unicode variants > thereof. I've added u"""Unicode triple-quoted strings""". Are ru"""raw Unicode strings""" useful? How would you get the Unicode escapes in? > 257:`One-line Docstrings`_ > > Hmm. When discussing the "signature" in C functions - shouldn't the > DPS mandate that this signature line should be (a) of a particular > format [the obvious one!], and (b) that the tool "looking for" and > interpreting code structure should make use of said signature if > present. (a) Sounds good. Care to provide the wording? (b) PEP 257 doesn't care about the DPS, but this could be added to PEP 258. > 257:`Multi-line Docstrings`_ > > Since presumably we will ultimately be wanting to have an reST mode > for [X]Emacs, as a subsidiary mode within Python mode (or however > one describes it), I think that this requirement should be removed. >From dps-notes.txt's To Do list: - Rework PEP 257, separating style from spec wrt DPS. See Doc-SIG from 2001-06-19/20. I think this is another aspect, "tools". I've updated the To-Do. > OK, I remembered why I sometimes want non-breaking spaces. In contexts > such as ``PEP 258``, ... > > On the other hand, how to get round it? Maybe we just need to allow an > escaped space to be a non-breaking space - since I lost the backslash > battle, I might as well lose it thoroughly. In which case my examples > would be written "PEP\ 258" and "ISO/IEC\ 8211". Now the question is how to represent it internally. I suppose we could store all strings as Unicode internally, and use the Unicode non-breaking space character. I haven't gotten into the Unicode encodings, so I'm inclined to put this one off (or let someone else implement it -- someone who cares ;-). > PEP 258 (DPS generic implementation details) > version 1.1.1.3 of 2001/07/19 > ============================================ > > .. comment:: OK, so I've found an instance of a multi-line header... I guess it does have to be supported. Oh, well. > 258:`Docstring extraction rules`_ item 3 > > At the end of the first paragraph, you say "Of course, standard > Python parsing tools such as the 'parser' library module should be > used.". > > I think that is too strong a statement - it should either say "may > be used" or it should say something more like "are likely to be used > in general". Changed to "may". This is an area where I'm looking for help: a docstring extraction module. For interpreted text to work also, it should also extract namespaces, to a point. See docstring/dps/spec/dps-notes.txt, section "Docstring Extractor". > 258:`Attribute docstrings`_ item 1 > > Does this really mean to leave functions out? That is, can one > really not do:: > > def fred(): > a = 1 > """``a`` is a silly name for a value.""" 'a' is a local variable, and not of interest to the outside world. It's an implementation detail, best documented with a comment (or, better yet, with a self-documenting, descriptive name). In other words, 'a' is only of interest to someone reading the code itself, not to someone calling the function, so there's no need to document it externally. > 258:`Additional docstrings`_ > > When you say "this breaks 'from __future__ import'" can you give > more context... Context added. > If it means what I think it means (that the __future__ statement > must be the first statement in a module, excepting a docstring (and > presumably another __future__!)), it would seem that option 2 is the > obvious one to adopt. That would require a change to the Python core, something I'm trying to avoid. I think option 3 ("ignore the problem") is good enough for now. If it comes back to bite us later (after reStructuredText has taken the community by storm and popular demand is undeniable), we can revisit the issue. > If there *are* going to be additional docstrings, can I ask that we > have some way of *identifying* them... I think the use of docstrings as metadata is dying out, now that we have function attributes. I included additional docstrings as a mechanism to reduce runtime usage for voluminous documentation. They're not an absolute requirement though: easy to drop, and easy to put off until later. Sorry, I'm not convinced. Do we really need to identify additional docstrings? Can you come up with a convincing rationale? And then, a good way of identifying them. > 258:`Choice of Docstring format`_ > > The default of "plaintext" seems sensible - indeed, it's not clear > to me that one need change it *ever*, since plain text is always a > valid form of documentation. If some syntax (reStructuredText or another) becomes *the* official docstring syntax, it would be useful to change it. But I agree, "plaintext" is a good default. The only problem is that we *must* specify ``__docformat__ = 'restructuredtext'`` (or whatever) to use the markup. This could be a problem for 3rd party modules. The DPS program could have a syntax-override option. > I suggest format names are something like: > > - "plaintext" (the default) > - "reST" (reStructuredText) > - "ST" (StructuredText - for Zope compatibility, > and thus maybe deprecated) > - "STNG" (StructuredTextNG - ditto) I've been considering a mapping of names, so syntaxes can register their full names and aliases. Names would be case-insensitive. > Other names > OK, so the DPS is responsible (in some sense) for the __docformat__ > name. Should it also be aware of some of the other (semi) standard > names that people use - the following are ones I'm aware of: > > * __author__ > * __version__ > * __history__ (this is less common) > * __copyright__ (I've just made this one up) I don't like to see such namespace pollution. Once we open the door on these names (and admittedly it's already at least partially open), we can't close it. That's one reason why I added field lists to the spec, so they could be leveraged for bibliographic information. Should the DPS support the above? Maybe. I'd prefer that it didn't. That information is documentation, and doesn't need to take up more of the global namespace. If you look at the pydoc output for modules which have these variables, it's very ugly. I'd want to avoid contributing to the further proliferation of these variables. If we support them, any of them, it just encourages the practice. I'd rather leave this up to a BDFL pronouncement, if Guido is willing. > 258:`Intermediate data structure`_ > > It should be made clear(er) that the DOM tree is intermediate > between the input parser and the output formatter - it is not a > requirement for the *internal* workings of either. The first > sentence of this section reads as if it means that the > input parser > *must* use the DOM tree inside itself. Made explicit. Speaking of DOM, I tried using it at first, but decided to take your advice and create a class library, dps.nodes, with one class per element type. The classes have ``asdom()`` methods which convert to xml.dom.minidom. I think the next step for PEP 258 is to move it away from the "generic" toward the "specific", adding details from the reference implementation. In PEP 256 I'd specified that there would be an implementation-specific PEP as well as the generic one, but somehow I doubt anybody else would implement an alternate DPS. > 258:`Output management`_ > > The final sentence: "Use a directory hierarchy ... couldn't run on > MacOS)" doesn't make sense to me - please explain it. Explained: (The files generated by pythondoc used compound file names, like 'packagename.modulename.classname.html', which were often too long for the 38-character MacOS file name length limit. This is one of the reasons pythondoc couldn't run on MacOS). > 258:`Error handling`_ > > Good. Of course, these correspond to the VMS information, warning, > error and fatal message levels (and those might be good names to use > for them). That's news to me. Interesting. Good names, better than what I'd come up with. I did a Google search and came up with this: +-------+-------+--------------+------------------------------------+ | DPS | VMS | | | | Level | Value | Severity | Response | +=======+=======+==============+====================================+ | n/a | 1 | Success | Execution continues, expected | | | | | results | +-------+-------+--------------+------------------------------------+ | 0 | 3 | Information | Execution continues, informational | | | | | message displayed | +-------+-------+--------------+------------------------------------+ | 1 | 0 | Warning | Execution continues, unpredictable | | | | | results | +-------+-------+--------------+------------------------------------+ | 2 | 2 | Error | Execution continues, erroneous | | | | | results | +-------+-------+--------------+------------------------------------+ | 3 | 4 | Severe error | Execution terminates, no output | +-------+-------+--------------+------------------------------------+ (Source: http://www.openvms.compaq.com:8000/73final/5841/5841pro_027.html #error_cond_severity) Also, the "Response" column gives a good explanation of the effect of the warnings. I've added this to the dps/dps-notes.txt To Do list. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Sun Aug 5 18:30:18 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Sun, 05 Aug 2001 13:30:18 -0400 Subject: [Doc-SIG] Comments on the reST specification In-Reply-To: <001f01c11c03$4beb8390$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: on 2001-08-03 6:01 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote: > An introduction to reStructuredText version 1.12 of 2001/07/10 > ============================================================== > > intro:`Goals`_ > > A tertiary useful goal, for many of us (well, for me at least) is > just to have *some* form of structured text, to read *as such*, for > use in docstrings, and for reading within docstrings. I've amended the last sentence of the first paragraph of "Goals", borrowing some of your words, to: The intended purpose of the reStructuredText markup is twofold: - the establishment of a set of standard conventions allowing the expression of structure within plaintext, and - the conversion of such documents into useful structured data formats. > reStructuredText Markup Specification version 1.41 of 2001/07/20 > ================================================================ > > Hmm - to someone reading the raw text, it can be useful to know whether > a link is to a target in the document or outside it. Of course, this can > be done (and probably *should* be done, by a good author) by writing the > text correctly Yes, that's the ticket. Adding to the markup for this isn't worth it. > spec:`Quick syntax overview`_ > > In describing paragraphs, you use the term "flush left". To me this > means "flush against the left margin". Either "left justified" or > (as you use elsewhere) "left aligned" would be better. Fixed. > spec:`Whitespace`_ > > You don't mention what happens if there are multiple blank lines > between paragraphs, etc. Amended. > As to spaces versus tabs - this sounds like it will lead to all of > the traditional discussions we get on the Python list about whether > one can mix spaces/tabs, and whether a tab is *really* 8 or 4 > spaces, leading finally to space eating nanoviruses (ick). I'd > suggest that this is dangerous territory, and that the behaviour > of tabs should be carefully undefined. Or precisely defined, which is how it is now. Any specific suggestions for improvements? > spec:`Section structure`_ > > You don't say which characters may be used as "underlines" for > section titles. The spec says: An underline/overline is a line of non-alphanumeric characters that begins in column 1 and extends at least as far as the right edge of the title text. So any of the RE character set '[!-/:-@[-`{-~]' is valid. Should I spell them all out? Restrict them further? (I know, some of them wouldn't be appropriate, but that's an aesthetic decision.) > Further down you say "nor must any specific section title style be > used". I think that "must" would be better as "need". Done. > spec:`Bullet lists`_ > > The first incorrectly formatted example is also indented > incorrectly - make it say so! OK! > spec:`Enumerated lists`_ > > The syntax diagram is missing. Added. > spec:`Tables`_ > > In the example, in the cell that contains lines starting ``-``, does > that content count as a list? If so, the cell boundaries (top and > bottom) must be acting as the delimiting blank lines - say so. Yes. Said. > spec:`Footnotes`_ > > "case insensitive single words" is unclear to me - it gets explained > later on, so maybe that explanation could be shifted or copied? It gets explained right then & there, in parentheses: Footnote labels are case-insensitive single words (alphanumerics plus hyphens, underscores, and periods; no whitespace). Is this insufficient? Which later explanation are you referring to? > spec:`Hyperlink targets`_ > > "whitespace neutral" doesn't mean anything to me. > > When you say they may contain whitespace, clarify if you include > newlines (some people include this as whitespace, some not). Yes, I > know the examples later on make it clear, but it would be nice to be > clear up front in the text. One problem with writing a spec is that you need to write everything everywhere, and it becomes a chore to write and a bore to read. That's why we have "see this" and "refer to that". I have extracted and expanded the relevant material into a new section, "Hyperlink Names", and added references to other sections. > Is it allowed to use *redundant* backquotes - for instance:: > > .. _`a b`: > .. _`ab`: Yes. Made explicit. > spec:`Comments`_ > > Arbitrary text after a ``.. `` is treated as a comment. > > I don't think this is right. I've been thinking about this also, with regards to the incompatibility of comments (as they are now) and subsequent block quotes: a block quote would be "swallowed up" by the comment. I'd thought of making comments one-liners, as ``#`` is in Python. > Initially, I didn't see *any* point to having comments, but you'll > see I've used them occasionally in these notes. But I think the > way to introduce a comment is with a "proper" named directive:: > > .. comment:: this is a comment, and > it continues in the normal manner > for a directive. This seems right to me too. Let's take it a bit further: we'll limit a comment to a single text block (i.e., up to the next blank line). A "multi-block comment" could use "comment-start" and "comment-end" directives. This would remove the indentation-incompatibility. > I believe strongly that a directive that does not start in a > legitimate manner should be treated as a "warning" (type 1 error?) > and that an output processor should (by default) not place its text > into the output, although it should allow the option of presenting > it in some delimited manner (perhaps in a different colour). Putting the unimplemented directive's block into a literal block inside a level-1 (or 2) system warning should do the trick. > Part of this is just that I think a comment (if used) should be > explicitly identified as such, but mostly it's for compatibility > with Stretch What's "Stretch"? Link? > I think we get a more robust format if: > > 1. Comments are a directive like any other:: > > .. comment:: some text > > Heh - it even says what it is! Yes, explicit. Which brings the syntax full-circle, since the dot-dot-space syntax is now called "explicit markup". > 2. Anything that is not a directive or a hyperlink target or a > footnote (I forgot those above - sorry) is of undefined > behaviour, and will generate a warning. > > This allows for extension in all sorts of ways in the future, > with minimal restriction. I'm just about convinced. I'll ponder it some more. Any further arguments or counterarguments anyone? > Incidentally, this would also mean that directives can use a single > colon as a delimiter - I think this would be easier to remember Perhaps. > spec:`Inline markup`_ > > Item 1 says that inline markup start strings must be immediately > preceded by whitespace and zero or more of various characters. This > precludes having a start string at the start of a file, and maybe > even at the start of a paragraph (depending on how one views the > whitespace (blank line) that indicates the start of the second and > successive paragraphs). I've amended the definition to explicitly allow start and end cases. > Item 5 mentions '<' and '>', but items 1 and 4 do not. I > assume this is a mistake. Correct; already corrected. > spec:`Interpreted text`_ > > I'm not too keen on having the "role" inside the string (as you > might guess from my attempt at "namespaces" in these notes). I > assume that the compelling reason, for you, is a wish to allow > whitespace in the role name (whereas I'd overgeneralise RFC 822, > or perhaps XML names, or Python identifiers, or something). > > Personally, I think:: > > role:`interpreted text`_ > > to:: > > `role: interpreted text`_ (Note: you don't need trailing underscores here. That turns them into hyperlinks.) > because I think the former is easier for *me* to parse (e.g., > specifically as something like class:`Fred`_ - the quotes go around > the *name* which feels right). Definitely food for thought. I'll mull this over; opinions welcome. > By the way, it is not acceptable to leave out a description of how > to determine the difference between (for instance):: > > `role: Fred`_ > `role: Fred`_ > > in some arbitrary application where the former is identifying a > role, but the latter is identifying something *called* > (legitimately) "role: Fred" - and whilst I can't come up with a > concrete example now, this disturbs me greatly (and is perhaps the > main reason I prefer to move the role name outwith the string). For the second, do you mean this? :: `role\: Fred` I agree that placing the role outside of the backquotes would alleviate this problem, but the tradeoff is that roles become single words. Maybe that's not so bad though. > spec:`Standalone hyperlinks`_ > > You need to explain the explicit rules used to detect such an > animal, otherwise this is too vague. I refer to RFC2396; I don't want to repeat it all. I've added this to "Standalone Hyperlinks": Two forms of URI are recognized: - absolute URIs beginning with a scheme ('http:', 'ftp:', 'mailto:', 'telnet:', etc.), and - standalone email addresses ('user@host'). Standalone email addresses are treated as if they had a 'mailto:' prefix. > Miscellaneous notes > ------------------- > I understand (now) that the two-dots-and-a-space-after-newline convention is > taken from setext, but why does it need to be two dots *and a space* - given it > must occur after a newline (and optional whitespace, of course), is there a > compelling reason for the space, or is it just for > compatibility? Would it be better without the space? Ellipses ('...') are common in text, and possible at the beginning of a paragraph. Two dots is not nearly so common. I'd venture to say that its use in text is a mistake. I seem to recall that Pascal used it for ranges, but that wouldn't adversely affect us here. > Python extensions version 1.19 of 2001/07/20 > ============================================ > > py:`Option lists`_ > > I don't think these belong here. I've been considering merging the Python extensions into the main spec, and merging the DTDs. I'd like to keep them separate for now to allow for non-Docstring contexts. But option lists are not only for Python, so maybe I'll move them over anyhow. > These are not *Python* options - these are Unix shell command > options (with common GNU extensions). They can clearly be dealt with > by other means, and should be so. By "by other means", do you mean such as the example you gave, below? I think that option lists are common enough (some form is in most every command-line program I've ever written), and I'd like to keep them. Unless there's something *problematic* about parsing them, I don't see the problem having them available. Of course, anyone who wants to use alternatives (tables, bullet lists, definition lists), is free to do so. > Alternatively, try defining a new syntax for "tabbed tables" > (something like the facilities available in LaTeX) - something > that looks like:: > > .. -a :: Output all > .. -b :: Output both (this description > is quite long) Excuse me, but, ugh. > py:`Interpreted text`_ > > As said elsewhere, use of `..` (undecorated with "_") to indicate > Python "elements" is a neat idea (if one doesn't want to use > '#..#'). > > I agree that the use of roles to disambiguate this is helpful, *but* > I've already said elsewhere my problems with the specific way of > doing it. > > I can't help feeling we shouldn't need as *many* roles as you > enumerate - how is a poor user to keep track, especially of the ones > that aren't part of normal Python terminology (like "instance > attribute"). The way I envisage it happening is that, in Python docstring mode, the parser has access to the namespace of the object being documented, and can determine the correct interpretation through namespace lookups. (No, I haven't implemented it yet, and yes, I know it ain't gonna be easy.) Isn't "instance attribute" part of Python terminology? That's what *I* call them. Variables set in the class definition are class attributes, those set in methods are instance attributes, etc. Is there a more common set of names? > "Class attribute" (for instance) is too long, and "classatt" too > horrible - if we're producing these, it means we need to think > longer about how to specify Pythonic roles. Suggestions welcome. > What is a "warning" or "warning class"? New to Python 2.1, they're like exceptions that don't terminate the program. > The "argument" role is missing. No, it's omitted on purpose. "Parameters" are the names in function/method definitions. "Arguments" are like local variables, not requiring API documentation. > Specific recommendation: use "name" instead of "variable" (what's > the other recommendation that goes with that?). Maybe. But "name" is such an overloaded concept. The Python RefMan refers to them as "identifiers (names)". (As to your question: I dunno, what?) -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From garth@deadlybloodyserious.com Sun Aug 5 23:26:08 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Mon, 6 Aug 2001 08:26:08 +1000 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: > > Arbitrary text after a ``.. `` is treated as a comment. > > > > I don't think this is right. > > I've been thinking about this also, with regards to the > incompatibility of comments (as they are now) and subsequent block > quotes: a block quote would be "swallowed up" by the comment. I'd > thought of making comments one-liners, as ``#`` is in Python. Please, no! :) Just think of the mess when someone re-wraps a long directive and the .. markers get evenly distributed. Yeccch. In any case, people might *want* to hand large amounts of text to a directive: .. sidebar:: This text will have its ident trimmed and then will be passed to a new Parser() instance, the output to be used as a side-bar to the current body text. Thank the various and sundries that we didn't have to prefix each and every line with a ``..``. And now, so that the next text is treated as a blockquote in the main body rather than as a blockquote in the sidebar, we dedent (outdent?) explicitly with a comment. .. This comment will be represented in the output, but could just as easily be an empty comment, which would outdent without adding a node to the tree. Here's the block quote in the main text. > > way to introduce a comment is with a "proper" named directive:: > > > > .. comment:: this is a comment, and > > it continues in the normal manner > > for a directive. Hmmm. > This seems right to me too. Let's take it a bit further: we'll limit a > comment to a single text block (i.e., up to the next blank line). A > "multi-block comment" could use "comment-start" and "comment-end" > directives. This would remove the indentation-incompatibility. The Python community hasn't historically been enthusiastic about requiring explicit start and end delimiters, and I'm very concerned that we're making reST documents with comments look cluttered and ugly for no real benefit. One of the reasons I'm so enthusiastic about reST is that the syntax is wonderfully clean to read as a document. :: .. This is a comment is clean. :: .. comment:: This is a comment. .. comment-start:: This is also a comment, but the moment I needed a few more characters than a single line would support I was forced to use a completely different syntax for comments. .. comment-end:: is, IMHO, not. :: .. This is a comment that is longer than a single line could contain given the text editor used to create the document. Explicit end delimiters are not required unless the next node in the output is a block quote whose parent is the same as this comment, in which case a single empty comment can act as a suitable terminator. .. is clean and explicit, uses identation as syntax, doesn't require un-Pythonlike start or end delimiters, and reads well in the plaintext, all in the best tradition of the 0.2.2 reST spec. > Yes, explicit. Which brings the syntax full-circle, since the > dot-dot-space syntax is now called "explicit markup". The consistency hobgoblin is about to walk up and demand that since you've eliminated the only *other* special case for .., you must make hyperlink targets and footnotes explicit:: .. footnote:: tag, this is some footnote text .. linktarget:: `link text`, target Suddenly, directives will have leapt from being a placeholder for whatever behaviour some *consumer* of the parser might need, to being an integral part of the reST syntax for everyday users. > I'm just about convinced. I'll ponder it some more. Any further > arguments or counterarguments anyone? Please, let's keep directives as something day to day users of the reST markup format *never need to use*. Honestly, since I read the reST text I've thought that we could remove the directives directory entirely and add an optional argument to the parser initializer which supplied a dictionary of directives that the consumer wanted to supply the parser. The parser itself didn't seem to need any directives for itself because the reST format was so complete and tidy. Even the namespaces concept can be done by the consumer, a-la Wiki link resolution. This whole comments as directives thing makes camels look elegant by comparison. As you said of another idea: Excuse me, but, ugh. Ugliness doesn't belong in reST. Explicit comment directives are ugly. QED. >> Incidentally, this would also mean that directives can use a single >> colon as a delimiter - I think this would be easier to remember Can't we do that already? :) Regards, Garth. From garth@deadlybloodyserious.com Mon Aug 6 01:00:57 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Mon, 6 Aug 2001 10:00:57 +1000 Subject: [Doc-SIG] Re: Comments on DPS and reStructuredText In-Reply-To: Message-ID: > > I've attempted to write the comments up *using* reST, but I'm fairly > > sure I'll have done it wrong because I was typing rather > > than looking up reST syntax. > > Uh, read that sentence again. Am i the only one that finds it a bit > frightening? Remember your first time with HTML? :) My biggest problem whilst trying to write reST was renumbering footnotes, actually. reST is [currently] clean enough that I could paste most email messages into it and get something sensible out. Add specific parsing for quoted text (``>``), and it'd do just fine. Hmmm. :) Tony's very first post would have come out pretty much as he expected. The bullet list would have come out in a blockquote, but what the hey. Regards, Garth. -- Garth T Kidd Mobile: +61-411-596-593 Consulting Systems Engineer, Aust/NZ Direct: +61-2-9779-5614 Network Appliance http://www.netapp.com/ From dgoodger@bigfoot.com Mon Aug 6 05:18:19 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 00:18:19 -0400 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: [I wrote] >> I'd thought of making comments one-liners, as ``#`` is in Python. on 2001-08-05 6:26 PM, Garth T Kidd (garth@deadlybloodyserious.com) wrote: > Please, no! :) Just think of the mess when someone re-wraps a long > directive and the .. markers get evenly distributed. Yeccch. You misunderstand. I'm talking about comments only, not directives. > ... This comment will be represented in the output, but could just as > easily be an empty comment, which would outdent without adding a > node to the tree. No, an empty comment *will* add a node to the tree. > .. This is a comment that is longer than a single line could contain > given the text editor used to create the document. Explicit end > delimiters are not required unless the next node in the output > is a block quote whose parent is the same as this comment, in > which case a single empty comment can act as a suitable terminator. > > .. So we special-case the empty comment (== two dots & [optional] space *only* on the first line?) to *not* consume subsequent indented blocks? > The consistency hobgoblin is about to walk up and demand that since > you've eliminated the only *other* special case for .., you must make > hyperlink targets and footnotes explicit:: > > .. footnote:: tag, this is some footnote text > > .. linktarget:: `link text`, target Actually, I *was* thinking about this, adding explicit directives for footnotes and hyperlink targets. But I would leave the ``.. _whatever:`` and ``.. _[whatever]`` syntax as shortcuts. Don't panic; read on. >>> Incidentally, this would also mean that directives can use a single >>> colon as a delimiter - I think this would be easier to remember > > Can't we do that already? :) No, because of comments like ``.. Danger: panic imminent!``. Anyhow, don't worry (yet). I'm just thinking out loud about interesting alternatives that *might* solve a tiny little wart, but possibly at the expense of introducing a much larger mole. Any proposed change will get a full hearing first. Thanks for your input. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Mon Aug 6 05:18:47 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 00:18:47 -0400 Subject: [Doc-SIG] Comments on the PEP 257 example In-Reply-To: <002001c11c03$5257a600$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: on 2001-08-03 6:01 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote: > Guido's example as presented:: > > def complex(real=0.0, imag=0.0): > """Form a complex number. > > Keyword arguments: > real -- the real part (default 0.0) > imag -- the imaginary part (default 0.0) > > """ > if imag == 0.0 and real == 0.0: return complex_zero > ... > > is not valid reST_. Whilst that's not entirely unreasonable (since > the DPS is not tied to reST), it would, I think, be consistent if > it were recast as such. I wouldn't want to show any bias, or conflict of interest. :-) Perhaps if recast as:: Keyword arguments: - real: the real part (default 0.0) - imag: the imaginary part (default 0.0) > It also becomes clear why I wanted "paragraph labels" to work as I > had them, so that one can *identify* that one has arguments to be > worked on. A title won't do, because one doesn't want a title for > the text that might *follow* the arguments... Please elaborate, with examples if possible. > There's more I want to write on this - an updated version > will follow at some time... I look forward to it. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Mon Aug 6 05:19:16 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 00:19:16 -0400 Subject: [Doc-SIG] Comments on the reST notes In-Reply-To: <002101c11c03$54e41d40$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: on 2001-08-03 6:01 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote: > reStructuredText notes version 1.29 of 2001/07/20 > ================================================= > > notes:`Enumerated lists`_ > > I would say that worrying about "compound enumerators" is not worth > the mind space. Let someone provide a convincing demonstration of > why they want it before worrying about it. That's why it's in the notes file. :-) > notes:`Literal blocks`_ > > I don't understand what you are wanting the triple-quotes convention > to do Basically, to easily allow the construction of something like your "Quick Reference". Write the construct once, see it twice: once raw, once processed. But it's probably a lame idea. That's why it's in the notes file too. :-) I've added a header and intro explaining that these ideas are "of questionable probability". > notes:`Indentation of list items`_ > > NB: I'm assuming that we do explicitly allow:: > > 9. This is some text > that lines up like this. > > 10. And obviously this text > lines up one space further right. I assume the indentation above was what you meant? That the "10" text lines up one space further right because "10" is one character wider than "9"? But the text lines of each element line up with each other? (Due to tabs & email clients, I couldn't tell where everything was supposed to line up.) If my assumption is correct, then yours is too. > notes:`Horizontal rules`_ > > The solution is to introduce them into a mode specifically for > producing HTML documents, and leave them out of other modes > (since other modes may also be used for producing other sorts of > output format). reStructuredText is not a page layout language. I'm reluctant to add these, at least for now. > notes:`Parser notes`_ > > Incorrect indentation should: > > a) generate a warning (level 1?) I'm thinking that I'll leave it alone. There's nothing preventing a block quote from containing another block quote. We shouldn't prevent a block quote from beginning with a nested block quote either. > Note that use in "batch" environments (such as Wikis) will alway > require a reasonable best guess, since they produce the visible > documentation (HTML) from the internal format, and there is no > author to ask if that internal format is in error. But surely the author gets a chance to correct their input? I'm going to leave the "guessing" out for now; others can add it later if it proves necessary. I want reStructuredText to be as deterministic as possible all on its own. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Mon Aug 6 05:19:32 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 00:19:32 -0400 Subject: [Doc-SIG] Comments on the "problems with structured text" In-Reply-To: <002201c11c03$582f9ec0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: on 2001-08-03 6:02 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote: > Problems with StructuredText version 1.32 of 2001/07/20 > ======================================================= > > prob:`Formal Specification`_ > > "preceed" should be "precede". How embarrassing. > prob:`Character escaping mechanism`_ > > After the paragraph starting "The best choice for this...", maybe > add a note along the lines of: Added: (On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash escapes, saying, "'nuff said. Backslash it is." Although neither legally binding nor irrevocable nor any kind of guarantee of anything, it is a good sign.) > prob:`Enumerated list markup`_ > > Nested enumerated list without indentation - I'd say this is a bad > idea - it's more complex, more ambiguous, and doesn't seem to me > to give any realistic gain. Deleted from problems.txt, but I've left it in rst-notes.txt. > prob:`Literal blocks`_ > > I still think the distinction of whether there's a space before the > "::" or not is a bit naff, but it does serve a useful purpose, and > David obviously likes it. > > The "::" on a line by itself thing is also a bit naff (even though I > came up with it), but it is also useful, and it does "fall out > naturally" (sort of). Perhaps it's better to think of "::" as pure markup, which disappears from the processed output as would the asterisks in *emphasis*. As a special case, if the "::" ends a paragraph preceded by non-whitespace, we keep one ":" in place. Is that less naff? :-) > prob:`Tables`_ > > This is good. Does the Emacs mode support "====" lines? No, not yet. Unfortunately, the table.el code is hard-coded to '-' now, and I haven't had time to brush up my elisp to tackle the modification. Any elispers out there who'd like to take this one on? > prob:`Inline literals`_ > > "In the UK, single quotes are used for dialogue in > published works." > > Hmm - no more than double quotes, I'd say - you've been reading old > books on printing again, haven't you? No, honest! :-) Every time I read a novel published or printed in the UK, dialogue is single-quoted. > prob:`Hyperlinks`_ > > In "Alternatives" item 2, you use the phrase "de-emphasize the URI", > which doesn't make any sense to me. Do you mean "stop it being > *recognised* as a URL"? No, I meant "downplay" or "minimize". When you stick a URI in the middle of a sentence, it tends to interrupt the flow. Putting it in paretheses alleviates that a little. > You don't mention the (rejected) option of enclosing URIs in "<" and > ">" (cf. email, etc). One major objection to this was the BDFL's > note that it was important to be able to write XML/HTML/SGML in text > without needing to quote it, and use of such a convention would make > that impossible. The "Problems" document was really my working notes for the development of the reStructuredText syntax. I missed a few alternatives. I'm wondering whether I should let "Problems" stand, or maintain it as a record of further ideas and rejected alternatives. > In the "Alternatives" section, option 3 makes it clear that you are > actually performing something of a Grand Unification of the ideas > and techniques from ST and setext (with some new ideas added, of > course). I never really thought of it that way. You make it sound so important! :-) > I actually think that you should maybe mention (boast > about?) this up-front in the description of reST (whilst, of course, > pointing out that you are not being bound by the previous > "standards" when it does not seem sensible). I sort-of do. From introduction.txt, first paragraph: reStructuredText_ is a proposed revision and reinterpretation of the StructuredText_ and Setext_ lightweight markup systems. And the paragraph before the "Author's Note" in the "Goals" section: Also, it is not the goal of reStructuredText to maintain compatibility with StructuredText_ or Setext_. reStructuredText shamelessly steals their great ideas and ignores the not-so-great. Do you think this should be combined and/or reiterated somewhere? > Later on, the paragraph "The two-dots-and-a-space syntax was > generalized by Setext for comments," is useful history, but I think > not a justification for *retaining* `.. arbitrary text` as a > comment... True. Your comments elsewhere have been duly noted and are being pondered in my subconscious as you read this. (Kinda creepy, huh? Like a trans-Atlantic mental remote procedure call.) -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Mon Aug 6 05:19:53 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 00:19:53 -0400 Subject: [Doc-SIG] Comments on DPS and reStructuredText In-Reply-To: Message-ID: on 2001-08-03 10:19 AM, Juergen Hermann (jh@web.de) wrote: > On Fri, 3 Aug 2001 11:01:31 +0100, Tony J Ibbs (Tibs) wrote: >> Oh - and if MoinMoin starts to use reST, that would be *brilliant*! > > It's not if, but when. Excellent. Glad to hear it. > The when is mainly influenced by the exitence of > an easy to use and/or well documented reusable processing engine. It's coming along, as fast as my spare time can handle. Garth Kidd is contributing. Would anybody like to join in? > The current formatter interface will be remodelled btw, latest in my > holidays (next month). I'd be very interested in any input you'd have on what the DPS/Formatter interface could do to help. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Mon Aug 6 05:27:57 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 00:27:57 -0400 Subject: [Doc-SIG] Suggestions for reST "modes" In-Reply-To: <002301c11c03$5b9e38a0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Thanks, Tony. Good ideas. I think these should actually be DPS modes, with parser support. I'll add them to dps-notes.txt (for now). David From klm@zope.com Mon Aug 6 06:04:02 2001 From: klm@zope.com (Ken Manheimer) Date: Mon, 6 Aug 2001 01:04:02 -0400 (EDT) Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: Hi, all. I've got some ideas about wiki and structured text i've been meaning to put forward for a while, finally have a moment, and tony's mention that gives me a great lead in... On Fri, 3 Aug 2001, "Tony J Ibbs (Tibs)" wrote: > reStructuredText "modes" > ======================== > [...] > Wiki > ---- > Allows any word of the form ``word_`` to be looked up in the document > itself, and if it is not found, looks it up as a Wiki link word. > > Thus one can create a WikiLink_, or indeed a wikilink_. One does not > need the to !EscapeThings, because they're not links unless made so. One > also doesn't need [this] because one can do this_. Wiki name misfires are probably among the biggest sources of user irritation i see - making their cues more explicit, as tony suggests, is a real good idea. Even with this explcit cue i would not want to then relax the wiki name form, however. Their constrained form (CamelCase, no whitespace or punctuation, etc), is not just recognizable, if makes them more recollectable, even reconstructable. Words and phrases in arbitrary form don't have this virtue - there's many more ways to spell the same thing. Further, in systems like Zope where the page names are useful in URLs for getting directly to the pages, "%20" for spaces and other punctuation presents big, ugly obstacles. In general, i'm interested in applying some of wiki's low-impedence features for general use in the Zope content management framework. I've got (languishing) some notes for a proposal along these lines - see http://cmf.zope.org/Members/klm/ReducingImpedence . I'd be interested to know whether the syntax i'm considering there would conflict with reST. The short story: - WikiName unadorned is just regular text, not specially recognized. - [WikiName] is a wiki name - it must be camel case, no whitespace, etc. - [Any Old Phrase] or [word] or [Word], etc, are plain text, not specially recognized. - If you must, you can use doubled '[[...]]' braces to force arbitrary phrases to WikiName-hood. I haven't gotten to learning reST, and am not sure whether square braces already have some special significance. I'd love to reserve them for the purpose of wiki names ("common names"), since that's sorta congruent to the way they're used in wikis (at least, ZWiki). (I'm not sure if and how reST will be fit into Zope, but i'd certainly like to keep that option open.) Ken Manheimer klm@zope.com From tony@lsl.co.uk Mon Aug 6 09:07:40 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 09:07:40 +0100 Subject: [Doc-SIG] Re: Comments on DPS and reStructuredText In-Reply-To: Message-ID: <004301c11e4e$dd104d40$f05aa8c0@lslp7o.int.lsl.co.uk> Ka-Ping Yee wrote: > On Fri, 3 Aug 2001, Tony J Ibbs (Tibs) wrote: > > I've attempted to write the comments up *using* reST, but I'm fairly > > sure I'll have done it wrong because I was typing rather > than looking up > > reST syntax. > > Uh, read that sentence again. Am i the only one that finds it a bit > frightening? Ah - I see what you mean. Yes, as written it *does* make it sound like I think reST is difficult to remember - but one has to remember that I've been working on different versions of the "same" thing for some time, and thus am quite likely to mistype between different versions. In particular, fingers that are used to typing '..' to mean literal text must now learn to type ``..``, and my "dearly beloved" #..# has likewise been replaced. Also, I keep getting the target end of links wrong (e.g., whether one needs a colon after [footnote] at the target end) - this *may* show a slight problem in the format, or just in my fingertips. *And* I was typing quite a lot of text fairly fast, so I'd have been making mistakes in any syntax... So I'm *not* saying that reST is hard (for me) to learn - I'm intimating that (a) I'm a confused person in this field for historical reasons, and (b) that I am one of the people who *really* needs a quick reference to hand for just this purpose. On the whole, reST has very little markup - there's - *..* and **..** (traditional by now) - `..`_ or word_ for links (OK - one simple thing to learn) - ``..`` for literals and some layout stuff. Doesn't mean I can't get it wrong! I'd be surprised if I hadn't used `..` to mean an inline literal somewhere. (and, of course, the XEmacs mode I was using was putting tabs in when I didn't think it was, which is another matter - looks bad in Outlook at my end, anyway). The *great* thing is that it leaves 'normal' quote marks alone. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 09:19:29 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 09:19:29 +0100 Subject: [Doc-SIG] Re: Comments on DPS and reStructuredText In-Reply-To: Message-ID: <004401c11e50$83a462d0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > I guess now it's *my* turn to be overwhelmed. ;-) I'll be replying to > your messages over the next few days. Hmm - just got in this morning (Monday) and it's my turn to be flooded back at - that's OK. > BTW, the two SourceForge projects now have CVS and mailing > lists set up. Hmm. Nice in theory, but not much use to me in practise - I don't have any useful access to CVS. I'll look into the mailing lists. Humph - more mailing lists. > On "reST": interesting acronym. Pronounced how? As in, "to rest"? Or > as "ree-ess-tee"? I've been using RST. I tend to think of it as "arr ee ess tee", and then find there's a song coming to mind (but that's doubtless my warped mind, and even if I could hum it at you you probably wouldn't recognise it with my bad humming - I'll have to try to ask my other half if she can figure out what it is...). I'm afraid RST sounds very boring to me. With respect to the quick reference - thanks for the comments. > - "Inline Markup": ``footnote references: [5]_`` is given, but in > footnote 4, "rep77" is the footnote label. Ah - these and the like are because I was going through a phase change in where the references *pointed to* when I stopped editing the document - the footnotes for the first table, or the table that describes hyperlink targets. No surprise it's confused. I haven't done any more work on the thing, but I *may* go with TeX as my first format, just because it lets me describe the page layout properly (which I can't, of course, do in HTML). > After reading your article "Would you trust something you had to > pay for?", both versions, I see what you mean. For "fold in", you > mean: the normal way HTML hyperlinks work, with arbitrary text > (typically underlined and in a different colour) fronting for the > URI, which is not visible in the text. For the alternate, you > mean: automatically generated footnote references and footnotes, > the latter containing the URI as a standalone hyperlink, visible > in the text. Let's call this alterate form, "callout". OK - it's useful to have a term for it. This is, of course, the way that the reST user has had to type it. > I see how the "callout" form would be useful. How to represent > hyperlinks is indeed an issue for the output formatter. For HTML, > the default would be to fold them in. That's what I assumed would be sensible. > Perhaps just clarify that > the representation *is* a matter for the output formatter, and > you're just displaying one possible representation. That applies > to the whole page though. OK. > Good article, BTW. Thanks. It was written for what would have been a very interesting fanzine, but somehow it never materialised. > 2. Enumerated lists: "List items should be sequentially numbered, > but need not start at 1." It may not be a good idea to start at > anything other than 1/A/I: the output format may not support an > arbitrary start value. I plan to generate a level-0 warning if a > list starts with ordinal-1. Hmm. Can we think of any "obvious" output formats that *don't* give this control? It seems to me that an informational note from the parser makes sense, but that it should be "allowed", and the output phase should insert a warning (level 1) if it cannot satisfy the request. BTW, I think it's a Bad Idea to issue a level 0 for something that might cause representation "errors" (i.e., doing something the user doesn't expect). Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 09:23:21 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 09:23:21 +0100 Subject: [Doc-SIG] Comments on the DPS texts: __version__ In-Reply-To: Message-ID: <004501c11e51$0d870020$f05aa8c0@lslp7o.int.lsl.co.uk> Garth T Kidd [mailto:garth@deadlybloodyserious.com] wrote: > I'd also like to see the use of $Revision$ in __version__ > deprecated. Agreed - I think this is horrible too. Moreover, it's *really* a "bad pun" (in the programming sense) - it isn't *really* the software's version, as you say. > People who love CVSisms and RCSisms in their code should > instead use:: > > __id__ = "$Id$" Well, people who use CVS/RCS may well have good reasons for wanting to keep these around. But I think "__id__" is wrong - instead, make it explicit:: __cvsid__ = "$Id" or perhaps even:: __revisionid__ = "$Id" Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 09:27:36 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 09:27:36 +0100 Subject: [Doc-SIG] Re: Comments on DPS and reStructuredText In-Reply-To: Message-ID: <004601c11e51$a5d860d0$f05aa8c0@lslp7o.int.lsl.co.uk> [followups trimmed - just going to Doc-SIG] Garth T Kidd [mailto:garth@deadlybloodyserious.com] wrote: > Tony's very first post would have come out pretty much as he expected. > The bullet list would have come out in a blockquote, but what the hey. Ah - depends on your email client. There were (by mistake) tabs lurking in various places in the documents, so in, for instance, Outlook , some of it looks very silly. As to blockquotes and lists - I'm personally undecided whether:: Some text. 1. A list should put the list in a blockquote or not, particularly since I often like that form in the "raw text" over the (textually) equivalent:: Some text. 1. A list I *suspect* that this may be a hint at a requirement for a qualifier on the output software... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 09:30:55 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 09:30:55 +0100 Subject: [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: <004701c11e52$1c8738a0$f05aa8c0@lslp7o.int.lsl.co.uk> > Thanks, Tony. Good ideas. Thanks. One of the advantages of DPS is it formalises some of what was in the back of my head at the start of the year, which is that one *would* want to apply this stuff to other places one was writing (email being an *obvious* example). Having "modes" formally defined up front (and the ability to add new ones) is a Good Thing, thus (STNG was half-way there, with the idea of overloading classes, but that's not quite the same thing). > I think these should actually be > DPS modes, with parser support. I'll add them to > dps-notes.txt (for now). OK. In a way, since you're clearly intending that adding new "modes" be not too hard, the number of modes initially present in the original package isn't too important. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 09:53:44 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 09:53:44 +0100 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: <004801c11e55$4c901910$f05aa8c0@lslp7o.int.lsl.co.uk> OK - I'm in *no* way the official Wiki person here (erm - Garth started this I think?) but that sort of consideration has never stopped me jumping in with two left feet before... Ken Manheimer [mailto:klm@zope.com] wrote: > Wiki name misfires are probably among the biggest sources of user > irritation i see - making their cues more explicit, as tony suggests, > is a real good idea. Oh, I don't know - the few times I've used a Wiki, I find the "?" links rather cute (but, of course, I *am* one of those people who like filling them in, and if someone has left potentially facetious "uncured" links, then they deserve what they get...). > Even with this explcit cue i would not want to then relax the > wiki name form, however. It is rather cute. > Further, in systems like Zope where the page names are useful > in URLs for getting directly to the pages, "%20" for spaces > and other punctuation presents big, ugly obstacles. Agreed (although that's a problem with URIs, not the user). > The short story: > > - WikiName unadorned is just regular text, not specially recognized. Makes sense. > - [WikiName] is a wiki name - it must be camel case, no > whitespace, etc. > > - [Any Old Phrase] or [word] or [Word], etc, are plain text, not > specially recognized. > > - If you must, you can use doubled '[[...]]' braces to force > arbitrary phrases to WikiName-hood. > > I haven't gotten to learning reST, and am not sure whether square > braces already have some special significance. They mean footnotes - so [1]_ is a footnote reference (a la PEPs, sort of). > I'd love to reserve > them for the purpose of wiki names ("common names"), since that's > sorta congruent to the way they're used in wikis (at least, ZWiki). OK - here's my take on this (warning: I'm not a longterm Wiki user!). The canonical "this is a link" meme in reST is word_ or `two words`_ (i.e., using backquoted strings before the underline if there is a space within the link term). Thus it would be natural to say that links that are not satisfied in the document (as those two above are - see below) should be *potential* Wiki links - i.e., that the Wiki engine should be free to consider them. As I understand it, the "traditional" Wiki scheme is that: - ``CamelWord`` is a link - we'd thus do that as "CamelWord_" - ``!CamelWord`` is not a link - we'd do that as "CamelWord" - ``[notcamelword]`` is a link - we'd naturally do *that* as "notcamelword_" What you seem to be saying is that you'd like to try to stop the user from doing the last one. Since it's easy for them to do it in a traditional Wiki anyway, I'm not sure that's a good way to go in reST, but... Another reST/DPS concept is that of "warning levels" (I think of them as equivalent to the old VMS info/warn/error/fatal levels, but David labels them 0/1/2/3). It should, I hope, be "normal" for levels 1 and up to insert appropriate information in the output so that the user can tell that the error has occurred (certainly for 2 and up). *So* - if one says that non-CamelWords are not the preferred option, it would be "reST-compatible" to flag them with a (visible) warning in the output. Alternatively, one might require that the user click a checkbox on the Wiki interface page (for instance) to enable such links in their page - after all, the Wiki software is in charge of processing the intermediate DOM tree to produce the final HTML, so it can decide what to do with the links on a "supported/not supported" manner for each page. This last might be the way to go within ZWiki, if the default state for the button is unchecked. .. _[1] this is the footnote from above. .. _word: an in document target for our word. .. _`two words`: ditto for out two words. .. comment:: Note there is *no* in document target for the link ``CamelWord_``, nor for ``notcamelword_``. > (I'm not sure if and how reST will be fit into Zope, but i'd certainly > like to keep that option open.) Although not the same structure as STNG, and not using the same DTDs, reST/DPS will be producing a DOM tree as its "intermediate output phase", just like STNG does. So one can leverage off that (hah - anyone suggesting going DTD -> XMLSchema -> XSLT -> STNG-SMLSchema -> STNG-DTD peobably has too much time on their hands!). I assume it would be fairly easy to adapt to using reST instead of ST/STNG. (Hmm - potentially two Pythonesque Wikis going to reST [2]_ - this could be Nice). .. [2] Erm, I didn't mean that to sound the way it can be read! Tibs (David - maybe we *should* be having a colon after a footnote target - I find it very confusing not to - I keep typing them and then removing them. Since one can (sort of) consider them as being like "`" and "`" around a multi-word link name, does that make sense?) -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 10:09:33 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 10:09:33 +0100 Subject: [Doc-SIG] VMS status messages (honestly, it *is* on topic!) Message-ID: <004d01c11e57$81cedb50$f05aa8c0@lslp7o.int.lsl.co.uk> David wrote: > I did a Google search and came up with this: +-------+-------+--------------+------------------------------------+ | DPS | VMS | | | | Level | Value | Severity | Response | +=======+=======+==============+====================================+ | n/a | 1 | Success | Execution continues, expected | | | | | results | +-------+-------+--------------+------------------------------------+ | 0 | 3 | Information | Execution continues, informational | | | | | message displayed | +-------+-------+--------------+------------------------------------+ | 1 | 0 | Warning | Execution continues, unpredictable | | | | | results | +-------+-------+--------------+------------------------------------+ | 2 | 2 | Error | Execution continues, erroneous | | | | | results | +-------+-------+--------------+------------------------------------+ | 3 | 4 | Severe error | Execution terminates, no output | +-------+-------+--------------+------------------------------------+ OK - but there's some "colloquial" background missing from that. VMS status messages, as output, are of the form:: %--, for instance:: %SYSTEM-E-NOSUCHFILE, No such file as "FRED.TXT;7" (this is a made up message, not a *real* NOSUCHFILE - I can't be bothered to look up the exact message). The component identifies what program/module the message was produced by, can be used to look it up, or talk about it, and is implied by , but may contain "variable bits", like the file name above. is a one letter code indicating which of the severity levels this message belongs to. And *these* are S, I, W, E and F. Hence Success, Information, Warning, Error and Fatal (even though "formal speak" might call that last "Severe error"). Of course, one can choose which levels of message to see, and which levels to catch (ah, the joys of DCL programming). Anyway, the gist is that the word "fatal" is a useful one, and it carries the correct implication of "help, I'm going to fall over now, look out for bits of stuff strewn all over the place". And, as you say, the terms are easier to remember than the numbers. Tibs (gone all nostalgic now) -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 10:30:29 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 10:30:29 +0100 Subject: [Doc-SIG] Compatibility with Stretch/comments Message-ID: <004e01c11e5a$6e79cad0$f05aa8c0@lslp7o.int.lsl.co.uk> Me: > Part of this is just that I think a comment (if used) should be > explicitly identified as such, but mostly it's for compatibility > with Stretch David: > What's "Stretch"? Link? Interestingly, it doesn't seem to be in the Jargon file (at least, not under C or S). OK. The Stretch computer was an IBM machine. IBM were very keen on keeping later machines compatible with earlier machines. Sometimes this was a bit silly. Having done some searching myself: See http://www.computer.org/history/looking/r30006.htm and note the text: Werner Buchholz (1990) was a member of the IBM 701 design team and prolific documenter of those early designs, including the later Stretch computer (a.k.a. the IBM 7030). (the name isn't relevant here, but the computer name and the tag "early" are), and: Bob O. Evans (1991) was an influential IBM manager committed to compatibility, a concept that led to the IBM System/360 family of machines. I caught the phrase off other computer programmers, around the Cambridge University labs, so it has a (shall we say) venerable history (i.e., it's quite old). Basically, as I understand it, it means "compatible with earlier things, even if that's going a bit far" - the implication being that "for compatibility with Stretch" was being used as a reason for keeping features long after any chance of code that had worked on Stretch still being around, and long after the feature was out-of-date. In the place I used it, I was just trying to imply that decisions we make now can have an impact on usage a very long way down the line, and what seems like a harmless decision now (oh, let's make "explicit markup" we don't recognise be comments) might be awkward a long way off, whereas labelling something EXPLICITLY as a comment both does what it says (heh! it's a comment! it says so!) and is guaranteed *not* to have such future effects. It also solves the "when does a comment end" problem (it ends when it ends by the normal rules for directive text, of course). As to whether a comment is allowed in a particular place or not - well, I think they'er a marginal construct at best, so don't much care. But I bet the question of whether a *directive* is allowed is much more interesting, and *will* need solving, so by my scheme that will also solve your comment worry. (gosh, is that a good enough summary? you did ask for more arguments - the above is almost lucid!). As to single colons after directives - I'd like to back off on that. I think that we should be able to say, instead: - explicit markup (hmm - not *quite* sure about this term, but at least it's a form of words) that goes:: .. _: text is some form of link target - explicit markup that goes:: .. :: is a directive. - explicit markup that does something else is undefined. Put like that, I think that the difference between ``_something:`` and ``something::`` *is* a useful distinction, so I'd now vote (a) to keep the double colons, but (b) to require a colon after a footnote ``]`` as well (as I think I said in another email). Hmm - work beckons - Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 11:08:20 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 11:08:20 +0100 Subject: [Doc-SIG] More on directives and comments Message-ID: <005001c11e5f$b867a090$f05aa8c0@lslp7o.int.lsl.co.uk> Sorry for lack of proper references in the following - I just want to write a quick note before I forget it. I (think) I agree with Garth that directive forms of target links would be overkill. I also think it would be difficult to do (he was worrying about "over the top" tendencies to consistency - I *think* he's overworrying?). So I'd vote for targets being targets and directives being directives. I can drum up reasons if I have to, but I'll only bother if it seems needed... I think he and I will have to disagree about how obvious and natural it is that:: .. Some text which has two dots at the start is a "comment" (if reST is *meant* to be human-readable in the "raw", with as much status for that form as for any post-processed form, then the idea of a "comment" is odd enough that it definitely wouldn't come to mind as the first thing I'd think of! - I'd assume it was meant to be an introductory ellipsis with a dot left off). Luckily, stylistic decisions are best made by a "leader" who takes comments on board and weighs them up - so either David, or (in ultimate) Guido, I guess. I'll still argue for:: .. comment:: This is a comment, obviously *But* I would argue that there is an advantage to be had in defining one (exactly one, count them!) directive in the reST spec itself. Directives are meant to be uncommon, things one doesn't normally need. So one doesn't really want any in reST, because that would imply that we have missed something that is *not* uncommon. On the other hand, if there is a construct that can be used "properly" in reST, there should be a decent example. I would contend that comments are this uncommon but, at the same time, sensible to have in reST, example. As I've said before, comments are *not* something one would normally put into (for instance) docstrings - one doesn't *normnally* embed metadata in text that is to be read "as such" (well, maybe some of us do, but then maybe we're odd, and we probably talk to ourselves as well). So comments are "uncommon" in that sense - not an everyday event. But clearly there is (at least some) demand for them - citing setext's provision for them, Garth seems to like them, David kept them in, and even I've used them in my notes on the specs. Which means that using them as our canonical example directive is a Good Thing - not least because it lets us find any "bugs" in how we're defining directives. (there, David, another argument in favour! are we there yet?) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 6 13:42:57 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 6 Aug 2001 13:42:57 +0100 Subject: [Doc-SIG] How to pronounce reST Message-ID: <005201c11e75$51c5d0d0$f05aa8c0@lslp7o.int.lsl.co.uk> [No, no, it *really* is on topic, really] Aha - eventually I thought of the right keywords to give to Google (namely, 'spelling songs' - simple, eh?). And the page http://www.flakmag.com/misc/spell.html gives me *exactly* what I want - when I write "reST" I'm actually thinking of the tune to RESPECT - to quote from the above page: """Aretha Franklin, on the other hand, brings us an unambiguous and positive model for a spelling song when she belts out her battle-worn classic, "Respect." In essence, "Respect" can be viewed as the perfect spelling song: It's the one raging success housed within the tattered genre. When Aretha sings: R-E-S-P-E-C-T Find out what it means to me R-E-S-P-E-C-T Take care, TCB* we are rooted to the spot, and transfixed by the power of her voice. Each musically boosted letter is a nail through the heart, compelling us to focus on Aretha's voice with everything we've got. Originally written by gifted songsmith Otis Redding, "Respect" is one of the first (and last) spelling songs to really get it right — the staccato, rolling cadence of the letters is defiant, strong and clearly intelligible.""" So, there we are - reST is pronounced just the same way as the "RESP" in RESPECT, and (if one is capable of it) to the same tune. I vote for it as the canonical abbreviation - after all, what more compelling argument could one want. We've got reST, we've got the "one raging success within a tattered genre" (well, one can dream). I rest my case. Tibs (glad to have gotten *that* sorted out) r e S T is the key... -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Well we're safe now....thank God we're in a bowling alley. - Big Bob (J.T. Walsh) in "Pleasantville" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From dgoodger@bigfoot.com Mon Aug 6 15:07:54 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 10:07:54 -0400 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: on 2001-08-06 1:04 AM, Ken Manheimer (klm@zope.com) wrote: > I haven't gotten to learning reST, and am not sure whether square > braces already have some special significance. In conjunction with a trailing underscore (meaning 'hyperlink'), square brackets mean footnote references. ``[1]_`` is a reference to footnote #1. Square brackets are also used in the footnote itself:: .. [1] This is footnote #1. Other than that, they have no significance in reStructuredText. I examined square brackets as an alternative syntax for hyperlinks, but rejected them for the same reason I rejected single quotes for inline literals: they're too common in ordinary text. The reStructuredText way to do WikiLinks is with a single trailing underscore:: Here is a WikiLink_. The Wiki software can determine what to do if the link is not defined, possibly based on the text being CamelCase or not. If a "WikiLink" page is not defined, the Wiki software can start up a new editor to create one; it's an application issue. > (I'm not sure if and how reST will be fit into Zope, but i'd certainly > like to keep that option open.) I hope it does fit (once it's ready), and I'm glad you're keeping the possibility open. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From Juergen Hermann" Message-ID: On Mon, 06 Aug 2001 00:19:53 -0400, David Goodger wrote: >I'd be very interested in any input you'd have on what the DPS/Formatte= r >interface could do to help. The most important feature is that is has abstraction of input and output. That means (for me) that it takes a string or a file-like object= for input, and create a SAX-like stream of output events. Ciao, J=FCrgen From garth@deadlybloodyserious.com Tue Aug 7 02:47:23 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 11:47:23 +1000 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: <004801c11e55$4c901910$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Some quick WikiNotes: >> Further, in systems like Zope where the page names are useful >> in URLs for getting directly to the pages, "%20" for spaces >> and other punctuation presents big, ugly obstacles. > > Agreed (although that's a problem with URIs, not the user). Wikis are pleasantly relaxed beasts, and as such I'd be entirely happy for *my* Wiki to concatenate all words in the link text, strip punctuation, and perform a case-insensitive search for matching page names. That's just me, though. Fortunately, the choice doesn't have to be made by the reST parser. Link resolution is up to the application. Some WikiClone developers might choose to always be relaxed, others might decide to be WikiFascists and insist that CamelCase always be used, and still others might leave it as a configurable option for the WikiOwner to decide on. In bullets for easy readability: * reST defines any single word with a trailing underscore as a link. * reST also defines any ```backquoted phrase``` with a trailing underscore as a link. * The WikiClone application can decide whether or not a given link resolves to a heading in the document, another part of the document, a footnote, another WikiPage, another part of another WikiPage, a page on another Wiki via InterWiki, whatever the application wants. In short, WikiNames are Somebody Else's Problem. > Thus it would be natural to say that links that are not > satisfied in the document (as those two above are - see below) > should be *potential* Wiki links - i.e., that the Wiki engine > should be free to consider them. Absolutely. > which can cache the XML version of the parser output Yup! This is where the decision to *not* have reST resolve links really shines. The parser output for a particular page doesn't change regardless of what happens to other pages in the Wiki. When someone asks for the page, the formatter simply runs the XML through an appropriate transform (resolving links at run-time) and splits it out. Schrodinger's links, anyone? :) David, it just occurred to me that [most? all?] directives should simply be parsed and embedded in the output for the application to handle. > *So* - if one says that non-CamelWords are not the preferred > option, it would be "reST-compatible" to flag them with a > (visible) warning in the output. That's up to the formatter, not the parser. It doesn't make much difference to the users of the system, but it keeps the parser a whole lot simpler. Pile a lot of WikiUsers and ask them about tweaking the page naming standard, and you'll end up with MuchWailingAndGnashingOfTeeth that could last for weeks. Let's let them thrash on their time, not ours. :) > (David - maybe we *should* be having a colon after a footnote > target - I find it very confusing not to - I keep typing them and > then removing them. That happens to me, too. Regards, Garth. From garth@deadlybloodyserious.com Mon Aug 6 23:00:58 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 08:00:58 +1000 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: > > Please, no! :) Just think of the mess when someone re-wraps a long > > directive and the .. markers get evenly distributed. Yeccch. > > You misunderstand. I'm talking about comments only, not directives. Directives will chew everything until an outdent, but comments won't? I'm obviously still misunderstanding. > No, an empty comment *will* add a node to the tree. My imagination must be cramped. Why? I mean, apart from that being the spec. :) > So we special-case the empty comment (== two dots & > [optional] space *only* on the first line?) to *not* consume > subsequent indented blocks? Yes. Exactly. My apologies to everyone for not making that bit clear. I was so completely blinded by how useful an empty comment could be to outdent that it *completely* escaped me that it was a special case and that people would have a lot of difficulty understanding what I was blathering on about if I didn't spell that out. > Actually, I *was* thinking about ... adding explicit directives for > footnotes and hyperlink targets. But I would leave the ``.. > _whatever:`` and ``.. _[whatever]`` syntax as shortcuts. Don't > panic; read on. Indignant panic has a certain righteous glow to it at the time. :/ > Anyhow, don't worry (yet). I'm just thinking out loud about > interesting alternatives that *might* solve a tiny little wart, > but possibly at the expense of introducing a much larger mole. That's my guess. Yep. Regards, Garth. From garth@deadlybloodyserious.com Mon Aug 6 23:01:01 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 08:01:01 +1000 Subject: [Doc-SIG] Comments on the PEP 257 example In-Reply-To: Message-ID: > - real: the real part (default 0.0) > - imag: the imaginary part (default 0.0) Complete side-track: inspect.getargspec() will hand you the defaults. Regards, Garth. From garth@deadlybloodyserious.com Mon Aug 6 23:01:05 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 08:01:05 +1000 Subject: [Doc-SIG] Suggestions for reST "modes" In-Reply-To: <002301c11c03$5b9e38a0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: > Wiki > ---- > Allows any word of the form ``word_`` to be looked up in the document > itself, and if it is not found, looks it up as a Wiki link word. Conveniently, the reST parser leaves it up to whomever calls it to actually resolve links (even to footnotes!). > May want to provide lazy indentation:: Oh, boy, have we been through this in the archives. :) I still think that we can do without the blank line between list items without getting silly, but it's not exactly keeping me up nights. > Book/paper/document > ------------------- > Some more directives, such as:: > > .. newpage:: > > will be needed. I suspect that a means of marking Chapter, Appendix, > etc., explicitly may be needed [...] ``.. section::``, anyone? Regards, Garth. From dgoodger@bigfoot.com Tue Aug 7 02:57:18 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 21:57:18 -0400 Subject: [Doc-SIG] Comments on the PEP 257 example In-Reply-To: Message-ID: on 2001-08-06 6:01 PM, Garth T Kidd (garth@deadlybloodyserious.com) wrote: >> - real: the real part (default 0.0) >> - imag: the imaginary part (default 0.0) > > Complete side-track: inspect.getargspec() will hand you the defaults. Unfortunately, we can't rely on inspect.getargspec(), as it only applies to "live" objects, such as imported modules. The DPS is *not* going to import modules (unless, perhaps, it's asked very nicely and explicitly first). -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From garth@deadlybloodyserious.com Tue Aug 7 02:57:34 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 11:57:34 +1000 Subject: [Doc-SIG] Re: Comments on DPS and reStructuredText In-Reply-To: <004601c11e51$a5d860d0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: > As to blockquotes and lists - I'm personally undecided whether:: > > Some text. > > 1. A list > > should put the list in a blockquote or not, particularly since I often > like that form in the "raw text" over the (textually) equivalent:: > > Some text. > > 1. A list I had to train myself out of indenting bullets by a space. Thankfully, it didn't take long. > I *suspect* that this may be a hint at a requirement for a > qualifier on the output software... It should be easy enough to convert the parser output to DOM, walk the tree, look for any blockquotes containing just one list, and collapse them. I'm reluctant to argue in favour of reST doing that automatically because I regularly have to quote someone else's bullet lists. Regards, Garth. From dgoodger@bigfoot.com Tue Aug 7 03:53:03 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 06 Aug 2001 22:53:03 -0400 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: on 2001-08-06 6:00 PM, Garth T Kidd (garth@deadlybloodyserious.com) wrote: >>> Please, no! :) Just think of the mess when someone re-wraps a long >>> directive and the .. markers get evenly distributed. Yeccch. >> >> You misunderstand. I'm talking about comments only, not directives. > > Directives will chew everything until an outdent, but comments won't? > > I'm obviously still misunderstanding. I'd like to keep everything orthogonal, if possible. One-liner comments seem less attractive to me today, so it's probably "comment" directives or the status quo. Give me a few days to mull it over. In the meantime, can you come up with a way to assuage Tony's concerns regarding simple ``.. `` comment starts? Specifically: 1. The inability to start a comment with ``_target text:`` or ``directive::``. 2. The concern about future comment-breaking (!), if we ever introduce another explicit markup construct. (I don't foresee the need now, but that's to be expected.) >> No, an empty comment *will* add a node to the tree. > > My imagination must be cramped. Why? I mean, apart from that being the > spec. :) I want the output to have a one-to-one correspondence to the input, so that round trips are possible (without cheating by looking at the "rawsource" attribute). (That's why I rejected that part of the patch. :-) I indend to have an output formatter which produces reStructuredTest. >> So we special-case the empty comment (== two dots & >> [optional] space *only* on the first line?) to *not* consume >> subsequent indented blocks? > > Yes. Exactly. OK, interesting idea. What about an empty comment start followed by an indented non-blank line? :: .. Is this part of the comment or not? -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From garth@deadlybloodyserious.com Tue Aug 7 05:09:43 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 14:09:43 +1000 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: >>> You misunderstand. I'm talking about comments only, not directives. >> >> Directives will chew everything until an outdent, but >> comments won't? >> >> I'm obviously still misunderstanding. > > I'd like to keep everything orthogonal, if possible. One-liner > comments seem less attractive to me today, so it's probably > "comment" directives or the status quo. Give me a few days to > mull it over. Status quo requires less code change. :) > In the meantime, can you come up with a way to assuage Tony's concerns > regarding simple ``.. `` comment starts? Specifically: > > 1. The inability to start a comment with ``_target text:`` or > ``directive::``. Tony also said at first he couldn't imagine using comments at all. :) This is another one of those "make the common case difficult to make a rare case easier" tradeoffs. As usual, my position is that we should keep the common case easier unless the rare case becomes downright impossible. Any experienced reST author will know that anything beginning ``.. _`` will be interpreted as a link and that a comment starting with a single-word identifier followed by a double colon will be treated as a directive. The workarounds are, to me, simple: * My top-of-mind reason to start a comment with an underscore is when referring to an identifier that happens to start with an underscore. In my body text, I'd be using ```target``` or ````target```` when referring to identifiers, so the obvious way to refer to an underscored identifier in a comment would be:: .. `_hide_me` is a messy workaround, but backquotes aren't. * Similarly, if I'm referring to a directive:: .. ``comment::`` is dingo-ugly, and should be spurned. * If I needed to go another level meta, I'd dodge the extra set of backquotes and use a literal block:: .. :: ``comment``:: is dingo-ugly is a bit harsh. Comments are, of course, passed to the output as an unparsed block of text (no paragraphs, no literal blocks, etc), but the important factors have been preserved: * anyone reading the document should find it pretty obvious what's going on, and * the techniques should be intuitive to experienced reST authors. In the IDG Books' "reStructuredText Markup for Dummies", using literals to make sure your comments are parsed as comments would be a single-paragraph "Remember" or "Tip". It's not a problem worth the hassle of making everyone type ``.. comment::` for every comment. I don't think it's even worth the bother of making an optional ``comment::`` directive -- the literals are quicker to type, so I'd certainly be using literals if given an option. > 2. The concern about future comment-breaking (!), if we ever introduce > another explicit markup construct. (I don't foresee the need now, > but that's to be expected.) I see a potential problem with directive arguments. Maybe it's just the overload on the operastor, but to me whatever comes after the ``::`` is a literal argument to the directive. If the directive has multiple paragraphs, my mental model says they're all parsed as a literal block (sans the directive marker). The parser says different:: .. sidebar:: this is some text this is a second para comes out as:: this is a second para not as I expect, which would be:: this is some text this is a second para ... which I could then. I think my mental model runs that way because it is slightly more consistent (to my poor addled brain, at least) with the comment equivalent, for which:: .. this is some text this is a second para comes out as:: this is some text this is a second para To bring directives, comments, and explicit directive-driven comments in line with each other, I think we should: * Retain ``.. [anything which doesn't parse as a link or directive`` as being implicitly equivalent to ``.. comment:: [anything...`` [Actually, let's not. See below.] * Add a ``comment::`` directive if people can't bear making something consistent with a directive that doesn't actually exist. :) * Remove the literal block node from the directive. That way I can revisit a multiple-paragraph implicit comment directive and convert it into a sidebar by inserting ``sidebar:: `` at the beginning of the first line in the first paragraph of the comment. Very clean. The question then becomes: What happens if I want to say "sidebar=right" or "sidebar=left"? :: .. sidebar side=left:: text... .. sidebar left:: text... .. sidebar(side=left):: text... .. sidebar(side="left"):: text... .. ... Ewwww. Ugly. The reason for ``data=`` abruptly becomes clear. Good call, David. :) I'll settle for inserting ``sidebar::`` and a couple of newlines (or, it turns out, just one -- see below) as a solution for my "convert comment to sidebar" case. >>> No, an empty comment *will* add a node to the tree. >> My imagination must be cramped. Why? > I want the output to have a one-to-one correspondence to the > input, so that round trips are possible (without cheating by > looking at the "rawsource" attribute). Good call. > I indend to have an output formatter which produces reStructuredTest. Yaay! >>> So we special-case the empty comment (== two dots & >>> [optional] space *only* on the first line?) to *not* consume >>> subsequent indented blocks? >> >> Yes. Exactly. > > OK, interesting idea. What about an empty comment start followed by an > indented non-blank line? :: > > .. > Is this part of the comment or not? According to the parser, yes. :) .. My girlfriend hates it when I dodge like that, but the joke's on me. I've been tapping away on this message for so long the food hall downstairs will have almost nothing left by now. I agree with the parser. There being no outdent, that's part of the comment, for sure, which means my empty comment special case needs a blank line after it. I'm more worried about how the parser handles:: $ ./quicktest.py .. directive:: is it? => is it? ... which places a natural limit on just how directive arguments can get if the author is unfortunate enough to have a crummy text editor. The most obvious workaround doesn't:: $ ./quicktest.py .. directive:: blah\ blah blah is it? => blah blah is it? Hmmm. :: $ ./quicktest.py this\ that => this that Okay, that explains it. Maybe I just made up that bit about using backslashes for line continuation. Worth adding to the spec, or is that another accident waiting to happen? Regards, Garth. From dgoodger@bigfoot.com Tue Aug 7 05:57:41 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 07 Aug 2001 00:57:41 -0400 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: on 2001-08-06 9:47 PM, Garth T Kidd (garth@deadlybloodyserious.com) wrote: > David, it just occurred to me that [most? all?] directives should simply > be parsed and embedded in the output for the application to handle. Depends on the directive. Directives themselves are a reStructuredText invention. For example, I'm thinking of a set of "admonition" directives. You could write:: .. Caution:: Mad scientist at work! And that would resolve to this parser output (XMLish):: Mad scientist at work! How the directive parses its text block is up to the directive. In the "caution" case above, the text block is parsed as usual, recognizing body elements such as paragraphs. Another directive might include its block as a literal block, insert up a named file and process further, run a program, or do something else. This has to be handled in the parser context, so the directive has access to the services of the parser itself. For directives which require further processing later on, the "directive" element could be used; it which can contain any body elements. This is how unrecognized directives will be handled. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 7 05:57:45 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 07 Aug 2001 00:57:45 -0400 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: <004801c11e55$4c901910$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: on 2001-08-06 4:53 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote: > (David - maybe we *should* be having a colon after a footnote target - I > find it very confusing not to - I keep typing them and then removing > them. Since one can (sort of) consider them as being like "`" and "`" > around a multi-word link name, does that make sense?) My reasons for no colon after a footnote label: - Footnote labels don't use colons in common usage. - To differentiate footnotes from hyperlink targets. Hyperlink targets point to an internal element or an external URI; they "map" the hyperlink name to the location. The colon is a mnemonic for "maps to". Footnotes *contain* the information being referred to from elsewhere; no mapping is taking place. - The brackets (in conjunction with the leading underscore) are enough to signify the role of the footnote label. ``.. _[label]:`` would be excessive. - Precedence from StructuredText. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 7 06:19:35 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 07 Aug 2001 01:19:35 -0400 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: on 2001-08-07 12:09 AM, Garth T Kidd (garth@deadlybloodyserious.com) wrote: > Status quo requires less code change. :) That never stopped me before! > In the IDG Books' "reStructuredText Markup for Dummies", I'm gonna be rich! Unless somebody gets to the Dummies people before me. Gotta stop coding, and start writing the damn book... > I see a potential problem with directive arguments. Maybe it's just the > overload on the operastor, but to me whatever comes after the ``::`` is > a literal argument to the directive. If the directive has multiple > paragraphs, my mental model says they're all parsed as a literal block > (sans the directive marker). How the directive block is parsed is entirely up to the directive. > * Remove the literal block node from the directive. I don't follow you. Explain please? > .... which places a natural limit on just how directive arguments can get > if the author is unfortunate enough to have a crummy text editor. If the directive is expecting more than a word or two of "arguments", it could easily be specified to accept arguments on the successive lines (and even use keyword arguments):: .. complex-directive:: arg1=val1 arg2=val2 Here's the directive block data... Don't forget, no directives have yet been coded, so the interface has not been established. What you see now is the generic, "unrecognized" directive output, which uses a literal block because it's whitespace-preserving and because the parser doesn't know what else to do. Your directive can parse its block however it likes. See my reply (to you) containing a "caution" directive for another possibility. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From garth@deadlybloodyserious.com Tue Aug 7 06:20:52 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 15:20:52 +1000 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: One thing I keep forgetting to point out with regards to directives is that I expect the application to run the [non-argument] contents through the parser again, hence ``sidebar::`` as my canonical example. It could just as easily be ``pagefooter::`` or ``pullquote::``. I think comments might also end up run through the parser sometimes. If I were using reST as my markup of choice for a collaborative document development system, document consumers wouldn't want to see comments but fellow authors probably would. Thinking of this has also reminded me of a use for marking text with directives: annotations. There's a whole snake-pit of issues in there, though, and unless paragraphs get obscenely long the next best thing is a normal directive. [1]_ .. annotation:: gtk ... or maybe not. Hmm. Y'know, I have a sneaking suspicion that to make things easier for authors someone would end up using author ids as directive types... Regards, Garth. .. _[1] This might be a limitation that makes the implementation a lot more useful. Microsoft Word's annotations are a complete pain because you can't view them inline, which makes sense because their "position" is an arbitrary text selection. If an annotation can only be put between paragraphs, viewing them inline is a *lot* easier. From garth@deadlybloodyserious.com Tue Aug 7 06:20:54 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 15:20:54 +1000 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: >> (David - maybe we *should* be having a colon after a footnote target > > My reasons for no colon after a footnote label: ... remind me: I think we should make footnote identifiers (excepting the square brackets) implicit hyperlink targets in their own right. Amongst other things, annotations and sidebars would then be able to refer to footnotes. Regards, Garth. -- Garth T Kidd Mobile: +61-411-596-593 Consulting Systems Engineer, Aust/NZ Direct: +61-2-9779-5614 Network Appliance http://www.netapp.com/ From garth@deadlybloodyserious.com Tue Aug 7 06:32:18 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 15:32:18 +1000 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: > > David, it just occurred to me that [most? all?] directives > > should simply be parsed and embedded in the output for the > > application to handle. > > Depends on the directive. [...] For example, I'm thinking of a > set of "admonition" directives. You could write:: > > .. Caution:: Mad scientist at work! Excellent example. Implementation wise, I'm thinking the application hands the parser a dictionary of directives mapping directive identifiers to functions (or otherwise callable objects). The parser calls the function with the argument string (currently ``::`` to end of line), the block it just pulled out of the text, and the parent node. The function returns either a node or None. Finally, the parser either inserts the new node or a directive element. A short-cut: if the directive identifier maps to a string, the parser parses the contents and inserts an element with the string as the element name. If the directive identifier maps to None, use the directive identifier as the element name. I can see that being handy for people. An extension: the application might instead hand the parser a function which takes as arguments the directive type, arguments, and block, and return either a node, None, or a string as per the short-cut above. That'd support the [cheeky] "cheat and use userids as directive types for annotations" idea nicely. It'd also let me do pull quotes in two lines of code (!). That said, I still have no idea how the ~2500-3000 lines of parser code work, so maybe that's the World's Most Broken Idea, in which case deem requests for thrown lines included. :) > For directives which require further processing later on, the > "directive" element could be used; it which can contain any body > elements. This is how unrecognized directives will be handled. Currently, directives always contain literal blocks. Are you planning to change that? Regards, Garth. From dgoodger@bigfoot.com Tue Aug 7 06:33:12 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 07 Aug 2001 01:33:12 -0400 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: on 2001-08-07 1:20 AM, Garth T Kidd (garth@deadlybloodyserious.com) wrote: > One thing I keep forgetting to point out with regards to directives is > that I expect the application to run the [non-argument] contents through > the parser again, hence ``sidebar::`` as my canonical example. It could > just as easily be ``pagefooter::`` or ``pullquote::``. The directive code can parse its block however it likes. > I think comments might also end up run through the parser sometimes. I don't think so. :-) -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 7 06:34:25 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 07 Aug 2001 01:34:25 -0400 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: on 2001-08-07 1:20 AM, Garth T Kidd (garth@deadlybloodyserious.com) wrote: > .... remind me: I think we should make footnote identifiers (excepting > the square brackets) implicit hyperlink targets in their own right. > Amongst other things, annotations and sidebars would then be able to > refer to footnotes. They already are:: This is how you refer to a footnote: [label]_. You can do this any number of times, from anywhere. I know it's broad daylight down under, but I have *got* to get some sleep. O-yasumi nasai! -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From garth@deadlybloodyserious.com Tue Aug 7 07:09:21 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Tue, 7 Aug 2001 16:09:21 +1000 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: Go to sleep! :) > > I think we should make footnote identifiers (excepting the square > > brackets) implicit hyperlink targets in their own right. Amongst > > other things, annotations and sidebars would then be able to > > refer to footnotes. > > They already are:: > > This is how you refer to a footnote: [label]_. > > You can do this any number of times, from anywhere. Let's say that I'm trying to use reST in a system designed to facilitate development of a document that will eventually be printed as a book, and the author has made a footnote:: Compatriots described him as "tired and emotional" [1]_. .. _[1] or, as they say in showbiz, drunk. To be as transparent as possible to the reST-using authors, the HTML might be something along these lines:: Compatriots described him as "tired and emotional" [1]_ [... later ...]
1 or, as they say in showbiz, drunk.>
We might need a later footnote to refer to the footnote. With the existing syntax, that's easy, as you point out:: He merrily [5]_ wandered outside to the garden and continued .. _[5] or, as they say in showbiz, tired and emotional. See also footnote [1]_. Unfortunately, in the printed representation that'll come out as:: 5 or, as they say in showbiz, tired and emotional. See also 1 footnote . Oops. If we unify the namespace and treat the square brackets as delimiters only, not part of the identifier, a printable representation is easy: .. _[5] or, as they say in showbiz, tired and emotional. See also footnote 1_. That syntax is slightly less ghastly than the workaround: .. _footnote 1: .. _[1] or, as they say in showbiz, drunk. .. _[5] or, as they say in showbiz, tired and emotional. See also `footnote 1`_. Hmmm. I might be guilty of making the common case more difficult, here, by trying to combine the namespace. The workaround frankly isn't that difficult now that I look at it. Regards, Garth. From tony@lsl.co.uk Wed Aug 8 09:05:57 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 09:05:57 +0100 Subject: [Doc-SIG] Slightly newer version of quickref Message-ID: <007001c11fe0$f4657630$f05aa8c0@lslp7o.int.lsl.co.uk> Unfortunately I was off work yesterday with a (luckily not very) sick child, so didn't get a chance to attack my backlog of Doc-SIG messages. And of course there are more today (mind you, that's a *healthy* sign). I *did* have time to make the next iteration of the quick reference - still far from perfect (perhaps even far from useful), but the new version is again at: http://www.tibsnjoan.co.uk/reST/quick_reST.html For what it's worth, whilst I still have reservations about comments, field thingies and descriptive lists, the *rest* of reST seems a Good Thing - as I've said before, leaving "proper" quotes available as such is perhaps the best thing about it. I'll try to find time to comment on all the things I want to comment on as and when - trouble is, it takes time to read and digest the various threads so my comments can at least purport to make sense! Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ In Python it's clearer to talk about "names" and "bindings" rather than "variables" and "values"... "you can't change the binding of a name in your caller's namespace" doesn't leave much room for misunderstanding. (Greg Ewing) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 09:47:52 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 09:47:52 +0100 Subject: [Doc-SIG] Hyperlink targets and roles In-Reply-To: Message-ID: <000001c11fe6$cf5ef310$f05aa8c0@lslp7o.int.lsl.co.uk> Ok - first of the first batch of comments. I'll try to split things out into sensible threads. If I don't reply to one of your own comments, please feel (moderately) free to assume enthusiastic agreement... David Goodger wrote: > So you're suggesting a "namespace" (working name) directive which > dynamically defines a base hyperlink, to which the hyperlink itself > is appended? Would this apply to hyperlinks only, or also to > interpreted text roles? Well, *actually* I'm not proposing something I'd describe in those terms. I'd describe it as defining a role, from the point of definition onwards in the document, which can be used as "shorthand" to indicate that the hyperlink given is actually in another document, and not in this one. So the term "namespace" is really a bit misleading. I'm *not* convinced this is something we need to worry about in the first release of DPS/reST - it's just convenient when commenting on stuff. Anyway, what I had was essentially of the form:: .. namespace:: is (you can already see it wasn't very thoroughly thought out! - and I still think "namespace" is the wrong term). And yes, I guess that we would then see:: :`somelink`_ as translating (in HTML terms) to:: # (although modulo the "normal translation rules" for that are imposed by the output formatter - e.g., the "name" for footnote ``[1]`` might be "footnote1"). > I think something like this would be useful. Garth Kidd brought it up > recently as well. I don't know how it could be implemented > though. I think that what I want could be implemented just as simply as above - it would *assume* that there were appropriate targets defined in the referenced document, and this (in turn) would assume that the output formatter for HTML put in all the implied targets (i.e., title links, etc.) even if they weren't used *within the document*. I am *not* proposing something as complex as XLink and XPointer - *that* should wait until (a) we see that we have a *need* for something so complex, and (b) we have a mature reST to put them into (I personally doubt we'll need it). Hmm - maybe we need to do the definition more like:: .. lookup:: in or even:: .. role:: lookup in (you can see why I'd rather not worry about it for the moment) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 09:50:29 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 09:50:29 +0100 Subject: [Doc-SIG] C signatures in C code docstrings In-Reply-To: Message-ID: <000101c11fe7$2d346740$f05aa8c0@lslp7o.int.lsl.co.uk> With respect to the C "signature" line at the front of docstrings in C code, David Goodger wrote: > (a) Sounds good. Care to provide the wording? > > (b) PEP 257 doesn't care about the DPS, but this could be added to PEP > 258. OK. Please put a note in the appropriate place that this will be added, and I will provide wording at some point (but it would help to have a place to *put* the wording first, so I can try to make it fit in). (I can specify some heuristics for recognising as well, or you can just look at earlier versions of my own code, which had some such in) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 09:55:25 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 09:55:25 +0100 Subject: [Doc-SIG] Non-breaking spaces In-Reply-To: Message-ID: <000201c11fe7$dd832370$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > Now the question is how to represent it internally. I suppose we could > store all strings as Unicode internally, and use the Unicode > non-breaking space character. I haven't gotten into the Unicode > encodings, so I'm inclined to put this one off (or let someone else > implement it -- someone who cares ;-). I think that the following would be useful: 1. Put a note on the description of how character escaping (i.e., use of "\\") works, that *at some time in the future* an escaped space may be a non-breaking space. 2. *Perhaps* consider noting that this *might* also be true for an escaped newline (although I'm much more doubtful of this). There's no real reason for people to escape such things unless they *are* doing something odd, so this should be safe enough. Then, sometime down the line, I might try to implement it. As for representation - chunk up the sequence of adjacent non-breaking spaces into one node in the DOM tree, and make it be text with the "retain spaces as spaces" attribute set (damn, can't remember it, but it's a standard thing to do - q.v. how HTML handles literals). (inside your *own* code, I'd be tempted to have a node that was called "non_breaking_spaces" and had an integer stored therein! - at least at first hack) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 09:57:25 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 09:57:25 +0100 Subject: [Doc-SIG] Docstring extraction module In-Reply-To: Message-ID: <000301c11fe8$2500fce0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > This is an area where I'm looking for help: a docstring extraction > module. For interpreted text to work also, it should also extract > namespaces, to a point. See docstring/dps/spec/dps-notes.txt, section > "Docstring Extractor". I *thought* that Ka-Ping Yee was working on pydoc to allow it to cope with not importing the module to be looked at? Otherwise, consider HappyDoc, which I think does a lot of what you want... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 10:00:22 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 10:00:22 +0100 Subject: [Doc-SIG] Additional docstrings In-Reply-To: Message-ID: <000401c11fe8$8eb0f500$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > I think the use of docstrings as metadata is dying out, now that we > have function attributes. I included additional docstrings as a > mechanism to reduce runtime usage for voluminous documentation. > They're not an absolute requirement though: easy to drop, and easy to > put off until later. > > Sorry, I'm not convinced. Do we really need to identify additional > docstrings? Can you come up with a convincing rationale? And then, a > good way of identifying them. Unfortunately, I think it will be around for a while. Zope has legacy reasons, and (sorry, forgot his name) who does one of the parses was arguing heavily some while back that he *wants* to put his parsing info in a docstring. This last didn't look like it would go away - he did *not* like the fact that using a function attribute meant an assignment, and one that has to come after the function at that (it is not visually associated with the function at all well). On the other hand, we may be able to put off worrying about this for the moment - and the chances of one entity wanting more than *two* docstrings is hopefully remote. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 10:08:39 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 10:08:39 +0100 Subject: [Doc-SIG] Attributes and also namespace pollution In-Reply-To: Message-ID: <000501c11fe9$b69ce0a0$f05aa8c0@lslp7o.int.lsl.co.uk> Two "odds and ends" things left... David Goodger wrote: > > 258:`Attribute docstrings`_ item 1 > > > > Does this really mean to leave functions out? That is, can one > > really not do:: > > > > def fred(): > > a = 1 > > """``a`` is a silly name for a value.""" > > 'a' is a local variable, and not of interest to the outside world. > It's an implementation detail, best documented with a comment (or, > better yet, with a self-documenting, descriptive name). In other > words, 'a' is only of interest to someone reading the code itself, > not to someone calling the function, so there's no need to document > it externally. Ah - hits forehead and says "d'oh". Yes, I should have thought of that. On the other hand, that's a Good explanation - is it worth adding it as a footnote for other fools like me? (hmm - probably not) > > Other names > > OK, so the DPS is responsible (in some sense) for the > > __docformat__ name. Should it also be aware of some > > of the other (semi) standard names that people use > > - the following are ones I'm aware of: ... > I don't like to see such namespace pollution. Once we open the door on > these names (and admittedly it's already at least partially open), we > can't close it. That's one reason why I added field lists to the spec, > so they could be leveraged for bibliographic information. Hmm. Personally, I like them ("namespace pollution" - only if one doesn't like them!) - and they've historically provided a neat solution to a problem given lack of docstrings. Also, I don't think your field lists are powerful enough to cope with these (authors, for instance, can get quite long and complex). But that's a discussion I've still to start properly (hah - time). > Should the DPS support the above? Maybe. I'd prefer that it didn't. > That information is documentation, and doesn't need to take up more of > the global namespace. Hmm - there *is* an argument for having particularly important things that one needs to know abot a module accessible using (for instance) ``dir``, without having to use special tools. Does distutils/catalog stuff use any of these? I'm afraid I can't remember. > If you look at the pydoc output for modules > which have these variables, it's very ugly. Not an argument - at the moment, the pydoc output for *everything* is ugly - that's because it's an early version of the tool, optimised for *finding* information, not for presenting it well. Things will change. > I'd want to avoid > contributing to the further proliferation of these variables. If we > support them, any of them, it just encourages the practice. > > I'd rather leave this up to a BDFL pronouncement, if Guido is willing. I definitely think this is a matter on which to seek BDFL guidance - it is clearly a matter of the style of the language-as-a-whole. Since I assume he's not got the time to pay attention to Doc-SIG at the moment, will you ask him? (I trust you to present both sides of the argument!). Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 10:12:12 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 10:12:12 +0100 Subject: [Doc-SIG] reST - spaces and tabs In-Reply-To: Message-ID: <000601c11fea$35bc5d70$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger replied to me: > > As to spaces versus tabs - this sounds like it will > > lead to all of > > the traditional discussions we get on the Python list > > about whether > > one can mix spaces/tabs, and whether a tab is *really* 8 or 4 > > spaces, leading finally to space eating nanoviruses (ick). I'd > > suggest that this is dangerous territory, and that the behaviour > > of tabs should be carefully undefined. > > Or precisely defined, which is how it is now. Any specific > suggestions for improvements? Hmm - Python has had it precisely defined for years, and that hasn't stopped the flames. I would be tempted *very strongly* to say that spaces should be used, and the behaviour of tabs within reST is undefined. It might also be worth seeking some BDFL/Tim Peters advice on this one point - I'd trust their feeling over mine. But it's not something I'll fight too long over. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 10:15:25 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 10:15:25 +0100 Subject: [Doc-SIG] reST: Section titles and "underlining" In-Reply-To: Message-ID: <000701c11fea$a8c0f1f0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > > You don't say which characters may be used as "underlines" for > > section titles. > > The spec says: > > An underline/overline is a line of non-alphanumeric characters > that begins in column 1 and extends at least as far as the right > edge of the title text. Hmm - I misread slightly. > So any of the RE character set '[!-/:-@[-`{-~]' is valid. Should I > spell them all out? Restrict them further? (I know, some of them > wouldn't be appropriate, but that's an aesthetic decision.) Ah - but that set of characters is *not* implied by "non-alphanumeric characters" - you left out, for instance, DEL (to be a pedant - erm, which I am). I would prefer that it explicitly list the characters, yes, and I'd also prefer that it not mention REs in doing so! Oh - thinks - so one can also do:: Section title +-+-+-+-+-+-+ OK, in that case please make it really obvious that this is allowed (I don't remember any of the examples showing this sort of thing). Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Just the facts, ma'am My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 10:21:10 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 10:21:10 +0100 Subject: [Doc-SIG] reST: standalone hyperlinks In-Reply-To: Message-ID: <000801c11feb$7670e3d0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote (well, some if it is me): > > spec:`Standalone hyperlinks`_ > > > > You need to explain the explicit rules used to detect such an > > animal, otherwise this is too vague. > > I refer to RFC2396; I don't want to repeat it all. I've added this to > "Standalone Hyperlinks": > > Two forms of URI are recognized: > > - absolute URIs beginning with a scheme ('http:', 'ftp:', > 'mailto:', > 'telnet:', etc.), and > > - standalone email addresses ('user@host'). > > Standalone email addresses are treated as if they had a 'mailto:' > prefix. Referring to the URI spec is not sufficient, since traditionally people have used ad-hoc schemes to detect URIs (particularly since the REs to detect them properly get, well, somewhat complex). I don't particularly care what heuristic is used, so long as (a) it handles the common cases (uncommon cases can be done with other means), and (b) it is clearly documented how it works (oh, and (c) it is unsurprising). If you *are* handling all of RFC2396, you still need an executive summary at some point! Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 10:39:47 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 10:39:47 +0100 Subject: [Doc-SIG] reST: Option lists and descriptive lists In-Reply-To: Message-ID: <000901c11fee$0fcf83e0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > By "by other means", do you mean such as the example you gave, below? > I think that option lists are common enough (some form is in most > every command-line program I've ever written), and I'd like to keep > them. Unless there's something *problematic* about parsing them, I > don't see the problem having them available. Of course, anyone who > wants to use alternatives (tables, bullet lists, definition lists), is > free to do so. Hmm. I think that if you can't use descriptive lists to represent option lists naturally, then that is a signal that descriptive lists are wrong. At which point we need to stand back and think again. And the way to do *that* is to take lots of examples and to look for commonality. [Of course, below I take two examples and stand on top of them. Oh well.] > > Alternatively, try defining a new syntax for "tabbed tables" > > (something like the facilities available in LaTeX) - something > > that looks like:: > > > > .. -a :: Output all > > .. -b :: Output both (this description > > is quite long) > > Excuse me, but, ugh. Well, yes, but it's a quickly typed in first suggestion, and anyway those colons should have been dots (typo). So, the examples we have are things like:: -a Output them all -b or -both Output just two and things like:: first -- the first argument second -- the second argument and we need to make sure that they read well in the "raw text". *I* would contend that the first can be phrased like the second and still look OK - that is, as:: -a -- Output them all -b or -both -- Output just two is that contentious? (i.e., do we agree that one unified form would serve for both, whatever that form might be). I *still* don't know the solution for descriptive lists, but I do feel that:: name description is one of the worse ways of presenting them, in generality - although it does have its uses sometimes. But its use of screen estate vertically is Not a Good Thing. I do agree (by now) that ``--`` is sensible within text as well - but that doesn't mean we have to discard its use for descriptive lists (where it is fairly natural) if we can discern (reasonably) unambiguously that that is what we are doing. Hmm - a strawman (in itself a bit yucky proposal) for such disambiguation... Let us consider what happens if a block (paragraph) starts with a single "word" followed by a double hyphen, where a "word" is one of a word (!), or a single inline markup entity. So we would have:: word -- the simple case *emphasised text* -- counts as one "word" `some non-emphasised text` -- some grouped text `even a link`_ -- 'cos it's still one "word" It *does* seem to require blank lines to be unambigous, but by the "a list has to have at least two elements rule" (which I think you give for enumerated lists) I think this *could* work - whether it is too horrible for words is another matter... Hmm - I'm still not happy with that. More thought needed... On the other hand, for the case of parameter lists which are *mainly* meant for interpretation by the command line user, what's wrong with just allowing a user who wants that to do:: Usage:: fred.py -a all -b or -both just the two Does what is primarily wanted, and doesn't require an extra construct... Tibs (sure he could argue things better, unsure of where he's going, but uncomfortable with where we started...) -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 10:48:07 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 10:48:07 +0100 Subject: [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: <000a01c11fef$39e924f0$f05aa8c0@lslp7o.int.lsl.co.uk> Garth T Kidd wrote (in response to me): > > May want to provide lazy indentation:: > > Oh, boy, have we been through this in the archives. :) I know - that's why I said "may"! > I still think that we can do without the blank line > between list items without getting > silly, but it's not exactly keeping me up nights. Oh - I had it down as one of those "we know how to do this if it's ever needed, so ignore and/or leave to someone else" issues. > > Book/paper/document > > ------------------- > > Some more directives, such as:: > > > > .. newpage:: > > > > will be needed. I suspect that a means of marking Chapter, Appendix, > > etc., explicitly may be needed [...] > > ``.. section::``, anyone? I suspect facetiousness (!) but it may come to that. On the other hand, detecting that the user has said:: Section: Fred ============= may be enough - this has the advantage (as I *thought* I said somewhere) of allowing one also to support:: Section 3: Fred =============== when one wants to tie-down a section number (as one does in "proper" documents, sometimes). I think it looks better with a convention like this, rather than with directives. If one is going to discuss the proper uses for David's field labels, and related concepts, I think this sort of thing will come in as well (must do that discussion some time). Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 10:59:57 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 10:59:57 +0100 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: <000b01c11ff0$e11f46e0$f05aa8c0@lslp7o.int.lsl.co.uk> OK - I had been intending to write scads on comments and directives and stuff, but I've just been reading the thread on comments and directives between Garth and David, and I don't think I need to. It sounds like sensible things are being thunk, and I'm quite willing to stand on the sidelines and let the two of you sort it out (gosh - I started out thinking Garth was going off in a weird direction, but now find myself following it with pleasure). Just one note - *do* we need ``.. comment::`` if we are going to retain ``.. `` as *meaning* comments? I'm not sure that proliferation of entities is a good thing if it's not necessary (even if it's an entity I suggested at the start). A separate note, though - I *don't* like having a blank comment represented as:: .. (see the problem? that trailing space is damned difficult to see, and terribly easy to leave out in consequence). On the other hand, I don't object at all to *not allowing* a blank comment! (Garth - if it's an annotation it isn't a comment - it's just some text that may or may not be visible in the final output, depending on arguments to the output formatter. Or so I would think) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 11:06:57 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 11:06:57 +0100 Subject: [Doc-SIG] Colons and footnotes (was RE: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes") In-Reply-To: Message-ID: <000c01c11ff1$db79da60$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > My reasons for no colon after a footnote label: > > - Footnote labels don't use colons in common usage. > > - To differentiate footnotes from hyperlink targets. Hyperlink targets > point to an internal element or an external URI; they "map" the > hyperlink name to the location. The colon is a mnemonic for > "maps to". > Footnotes *contain* the information being referred to from > elsewhere; > no mapping is taking place. > > - The brackets (in conjunction with the leading underscore) are enough > to signify the role of the footnote label. ``.. _[label]:`` would be > excessive. > > - Precedence from StructuredText. All good reasons (you can tell there's a "but" coming, can't you!). *My* reason for suggesting using them was, however, entirely orthogonal, and was simply that it is one less thing to remember, if *all* hyperlink targets start with ``.. _`` and end with ``:``. Now, this is convenience for the author, so not necessarily our preeminent goal, but two of us at least keep typing the things and then having to remenber to remove them (so, two out of a scientifically selected sample of, erm, how many...). How it is presented in output text is, of course, up to the formatter. (hmm - I don't *really* see that [1]_ and 1_ are *that* distinct as concepts - we've chosen to special case the [1] case, and we don't in fact allow (for instance) (1)_ without backquoting it, but still) Anwyay, on with the show - this is minor stuff (even if *important* minor stuff) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 11:33:04 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 11:33:04 +0100 Subject: [Doc-SIG] Comments on the reST notes In-Reply-To: Message-ID: <000d01c11ff5$816c46d0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > > notes:`Horizontal rules`_ > > > > The solution is to introduce them into a mode specifically for > > producing HTML documents, and leave them out of other modes > > (since other modes may also be used for producing other sorts of > > output format). > > reStructuredText is not a page layout language. I'm reluctant to add > these, at least for now. Oh, by no way should they be in "plain" reST - but I would advocate support in (for instance) the HTML-preparation mode of reST (indeed, I do, and that is the correct place for it). > > notes:`Parser notes`_ > > > > Incorrect indentation should: > > > > a) generate a warning (level 1?) > > I'm thinking that I'll leave it alone. There's nothing preventing a > block quote from containing another block quote. We shouldn't prevent > a block quote from beginning with a nested block quote either. Hmm - so one allows:: This is some text. This *looks* like it might be indented wrongly, but... ...in fact this blockquote is OK, so it isn't. Does that "fall out" ok with your current parser? If this *is* allowed (and, as you say, it does make sense) then I think that the "proper" reST documentation should make a note that it will work, in the section on blockquotes. > > Note that use in "batch" environments (such as Wikis) will alway > > require a reasonable best guess, since they produce the visible > > documentation (HTML) from the internal format, and there is no > > author to ask if that internal format is in error. > > But surely the author gets a chance to correct their input? I'm going > to leave the "guessing" out for now; others can add it later if it > proves necessary. I want reStructuredText to be as deterministic as > possible all on its own. Ah - different assumptions. You're assuming that the "author" gives a toss - that they come in to edit a Wiki page (for instance) and actually bother to read it afterwards to make sure it makes sense. I bet this isn't always so. I'm assuming that the reader should be given a chance to make sense out of what a poor author wrote, by use of some simple heuristic, even whilst flagging the text as in error. Of course, your comment on block quotes above may remove much of the reason for this. As to determinism - my prototype had such "guessing" built in, but the documentation declared it up front, and after guessing the output formatter could flag it as "guessed - maybe wrong". Which is all I'm asking for. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 8 11:48:33 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 8 Aug 2001 11:48:33 +0100 Subject: [Doc-SIG] Comments on the "problems with structured text" In-Reply-To: Message-ID: <000e01c11ff7$ab551e70$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > > "preceed" should be "precede". > > How embarrassing. Hmm - bear in mind I'm the one who posted documents with tabs in them! Spelling happens. > Perhaps it's better to think of "::" as pure markup, which disappears > from the processed output as would the asterisks in *emphasis*. As a > special case, if the "::" ends a paragraph preceded by non-whitespace, > we keep one ":" in place. > > Is that less naff? :-) Not particularly - but I wasn't saying the description was naff, or that it wasn't a good way of doing things - it's just that it's a little more ad-hoc than one might wish in a perfect life (it's not "intuitive"). On the other hand, it does give good return for little learning effort, it's not likely to go wrong, and it ain't worth trying to iron out with something more clever and less easy to use. So "naff" is relative. > > prob:`Tables`_ > > > > This is good. Does the Emacs mode support "====" lines? > > No, not yet. Unfortunately, the table.el code is hard-coded to '-' > now, and I haven't had time to brush up my elisp to tackle the > modification. Any elispers out there who'd like to take this one on? It *might* be worth emailing the person who wrote/maintains the code to see if they are interested (and, of course, it gives them egoboo since we're using their module as a contributing reason for adopting this format). > > prob:`Inline literals`_ > No, honest! :-) Every time I read a novel published or printed in the > UK, dialogue is single-quoted. Gosh - I clearly don't notice, but then I read a mix of books (and most SF/fantasy, for instance, is US-published). > The "Problems" document was really my working notes for the > development of the reStructuredText syntax. I missed a few > alternatives. I'm wondering whether I should let "Problems" > stand, or maintain it as a record of further ideas and rejected > alternatives. I think that a "Historical background" document, containing the pros and cons of past arguments, would be a good thing - partly for the same reason we have "refused" PEPs, and partly just 'cos that sort of thing *can* be neat. Of course, it's yet more work to saddle you with. > > that you are actually performing something of a > > Grand Unification of the ideas and techniques > > from ST and setext > > I never really thought of it that way. You make it sound so > important! :-) Hmm - you haven't watched the Doc-SIG for as long as I have. I don't particularly care *who* gets a product out (you, me, Edward) so long as we get one, and preferably one I like. Managing to get *this* near is a Good Thing, and being able to do it by pulling together the very first two threads of the Doc-SIG on this matter (!) is clearly something Very Clever to pull off. > I sort-of do. From introduction.txt, first paragraph: > > reStructuredText_ is a proposed revision and reinterpretation of > the StructuredText_ and Setext_ lightweight markup systems. True - I'd forgotten that by the time I got to this document. > And the paragraph before the "Author's Note" in the "Goals" section: > > Also, it is not the goal of reStructuredText to maintain > compatibility with StructuredText_ or Setext_. reStructuredText > shamelessly steals their great ideas and ignores the not-so-great. > > Do you think this should be combined and/or reiterated somewhere? No - it's actually already OK. It just didn't stick in my mind. > (Kinda creepy, huh? Like a trans-Atlantic mental remote > procedure call.) Hmm - maybe we shouldn't go there! Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From garth@deadlybloodyserious.com Wed Aug 8 23:49:39 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Thu, 9 Aug 2001 08:49:39 +1000 Subject: [Doc-SIG] Hyperlink targets and roles In-Reply-To: <000001c11fe6$cf5ef310$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: > Anyway, what I had was essentially of the form:: > > .. namespace:: is > > (you can already see it wasn't very thoroughly thought out! - and I > still think "namespace" is the wrong term). And yes, I guess that we > would then see:: > > :`somelink`_ > > as translating (in HTML terms) to:: > > # My experience with InterWiki links tells me that we don't want a delimiter between the namespace base and the extension. The user can put the ``#`` at the tail-end of the base if appropriate. If we implement namespaces, I expect to often see ``/``, ``?``, ``?something=`` and ``&something=`` at the tail end of the base. Can we call namespaces something... well, less spacey? They're named link target bases, and I'm not sure "space" gives us much of a benefit. When I hear you talk about namespaces being involved with links in reST, I start thinking that there's a footnote namespace and a default link target namespace but just in case you have documents created by aggregation you can give each chapter its own link target namespace to avoid collision. I'll call 'em linkbases for the rest of this message to see how it sounds. If your application needs linkbases, currently you don't even need roles. Just look for linkbase directives and then parse link targets to see if they begin with a particular base name and a colon. Let's say someone specifies the following text: .. linkbase:: dictionary=http://www.dictionary.com/cgi-bin/\ dict.pl?term= .. Hmmm. If we adopt backslashed line extension, we should trim whitespace up to the indentation level of the block. Look out for the fnords_! .. _fnords: dictionary:fnord What you get back from reST (assuming backslashed line continuation and ignoring the comment):: Look out for the fnords ! dictionary:fnord When you see the linkbase directive, add the linkbase to your table. When you see the ````, note that it starts with a valid identifier followed by a colon and that identifier matches a linkbase, and parse it accordingly. Wikis would pre-load their linkbase tables with the InterWiki list. Yet again, reST's clean design has ensured that you can implement what you need without having to change a line of parser code. :) Regards, Garth. -- Garth T Kidd Mobile: +61-411-596-593 Consulting Systems Engineer, Aust/NZ Direct: +61-2-9779-5614 Network Appliance http://www.netapp.com/ From garth@deadlybloodyserious.com Wed Aug 8 23:59:54 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Thu, 9 Aug 2001 08:59:54 +1000 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: My bad: > A short-cut: if the directive identifier maps to a string, the parser > parses the contents and inserts an element with the string as the > element name. If the directive identifier maps to None, use the > directive identifier as the element name. I can see that > being handy for people. Unfortunately, it means that a reStructuredText environment *without* those directive specifications loaded wouldn't be able to spit out valid reStructuredText given the node tree or XML. I'm not sure how much of a problem that is, but it bears considering. I suspect I'm currently leaning in the direction of parser-loaded directives having the ability to "hook" the parser to alter the way it interprets the input [examples]_, but not affecting the composition of the parser output in such a way that would make it impossible for an `OOB` reST engine to reverse-engineer from the XML or node tree some valid reST input that would create the same output. .. _[examples] For example, automatically wrapping Python identifiers in literals or implementing "lazy" paragraph identation rules for people with crummy editors. .. _OOB: Out of the box, ie without any directives loaded. Now, how on Earth do we render this link target, or any other non-URI link target that hasn't been rescued by some directive? I'm using it as a footnote. Hmmm. Regards, Garth. From garth@deadlybloodyserious.com Thu Aug 9 00:10:08 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Thu, 9 Aug 2001 09:10:08 +1000 Subject: [Doc-SIG] Suggestions for reST "modes" In-Reply-To: <000a01c11fef$39e924f0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: > > > will be needed. I suspect that a means of marking > > > Chapter, Appendix, etc., explicitly may be needed [...] > > > > ``.. section::``, anyone? > > I suspect facetiousness (!) but it may come to that. I'm not being facetious_. "Section" is the generic term most Microsoft Word users would use to describe a chapter or appendix. An application handling a "section" directive doesn't need to worry about having an insufficiently large list of words used in headings to describe a new section. Chapter and Appendix are obvious. `Fit the First` isn't. .. facetious: well, not there, anyway. :) .. _Fit the First: `The Hunting of the Snark: an Agony in Eight Fits`_, by Lewis Carroll. .. _`The Hunting of the Snark: an Agony in Eight Fits`: http://www.snark.de/carroll/snark/ > Section 3: Fred > =============== What if we want to discuss Proposition 23? :: Proposition 23: Discussion ========================== Oops. :) Regards, Garth. From garth@deadlybloodyserious.com Thu Aug 9 00:10:10 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Thu, 9 Aug 2001 09:10:10 +1000 Subject: [Doc-SIG] Colons and footnotes (was RE: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes") In-Reply-To: <000c01c11ff1$db79da60$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: > *My* reason for suggesting using them was, however, entirely > orthogonal, and was simply that it is one less thing to remember, > if *all* hyperlink targets start with ``.. _`` and end with ``:``. Yep. That's pretty much it for me. Permitting or mandating colons also removes the requirement for footnote target identifiers to not include the square brackets, as I'd hopefully be able to distinguish between a footnote reference and a link to a footnote like so:: This line has a footnote reference. [1]_ This line refers to the footnote `[1]`_ Hmmm. Or maybe I should just dig my heels in and insist upon removing the square brackets from the identifier. :) Regards, Garth. From garth@deadlybloodyserious.com Thu Aug 9 00:18:44 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Thu, 9 Aug 2001 09:18:44 +1000 Subject: [Doc-SIG] Comments on the reST notes In-Reply-To: <000d01c11ff5$816c46d0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: > This is some text. > > This *looks* like it might > be indented wrongly, but... > > ...in fact this blockquote is > OK, so it isn't. > > Does that "fall out" ok with your current parser? Yep:: This is some text. This looks like it might be indented wrongly, but... ...in fact this blockquote is OK, so it isn't. > You're assuming that the "author" gives a toss - that they come in to > edit a Wiki page (for instance) and actually bother to read it > afterwards to make sure it makes sense. I bet this isn't always so. > > I'm assuming that the reader should be given a chance to make > sense out of what a poor author wrote, I'm pretty sure that even if the XML above were translated to HTML, a reader would be able to figure out that there was some crummy indentation. If a community suffered enough from documents with crummy indentation from authors who never bothered to go back and read their contributions, I suspect they'd add a "click here to read the original reST" button. :) Regards, Garth. From tony@lsl.co.uk Thu Aug 9 09:59:44 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 9 Aug 2001 09:59:44 +0100 Subject: [Doc-SIG] Hyperlink targets and roles In-Reply-To: Message-ID: <001901c120b1$a1e38fb0$f05aa8c0@lslp7o.int.lsl.co.uk> Garth T Kidd wrote (in reply to me): > > Anyway, what I had was essentially of the form:: > > > > .. namespace:: is > > > > (you can already see it wasn't very thoroughly thought out! - and I > > still think "namespace" is the wrong term). And yes, I guess that we > > would then see:: > > > > :`somelink`_ > > > > as translating (in HTML terms) to:: > > > > # > > My experience with InterWiki links tells me that we don't want a > delimiter between the namespace base and the extension. The > user can put the ``#`` at the tail-end of the base if appropriate. > If we implement namespaces, I expect to often see ``/``, ``?``, > ``?something=`` and ``&something=`` at the tail end of the base. Gosh - that's altogether more ambitious than I wanted to be - you're clearly trying to allow the full flurry of HTML references to be done via reST, whereas I was just wanting to allow someone to reference a *specific* label in a different file. To my mind, if someone wants to do:: http://whatever/thing?fred then they can either included it as an explicit reference, or use the indirection mechanisms. But I've not used InterWiki - why and how do people do this there? Anyway, my proposed new role *does* just identify a file, and the role translation and the label *can* be separeted by "#" in the resultant HTML, 'cos that's the limit of my ambition. Trying to implement all the wonders of queries in URIs and so on is too much ambition for reST (now, and maybe forever), I think - and if I *did* want to do that, I'd be looking at leveraging off Xlink/Xpointer/etc anyway, not off the URI specs (they're *so* much more powerful, especially in the neat ability to regard the target document as tree and/or stream at the same time - if you haven't looked at them, I recommend it. Thinking of XML documents as two differing structures at the same time is fun!). > Can we call namespaces something... well, less spacey? Yes, namespace is a poor choice - I've been doing XML related stuff lately, is my only excuse, and couldn't come up with something (anything) better at the speed I was typing. > They're named link target bases, Well, actually I think they're documents, and I think we should perhaps try to eschew the low level description (link, etc) in the directive. Perhaps:: .. reference:: fred is "fred.txt" might work. Anyway, since I'm not *particularly* proposing to ask for these in early versions of reST, I'm not worrying too much about this. "linkbase" sounds too low level to me - "base" is very non-obvious to me. > When I hear you talk about namespaces being involved with > links in reST, I start thinking that there's a footnote namespace > and a default link target namespace Erm - no, that's a different use of the word namespace. As you say. Ho hum. > I'll call 'em linkbases for the rest of this message to see how it > sounds. > > If your application needs linkbases, currently you don't even need > roles. [explanation omitted] What you're saying is that one can adopt conventions that allow one to parse this after reST has finished with the document. Which is so (indeed, if reST works *at all* like stpy worked, it will be doing a succession of refinements of its own internal datastructure, one by one, and this is equivalent to just another one). But we've *got* roles, and they are thus an obvious thing to use for this purpose - a role amends its associated interpreted text, and if that interpreted text is being used as a link, then the obvious thing for a role to do is to amend that link. And one of those obvious things is saying "look in another document". Maybe we need to be more explicit:: .. linkrole:: "fred" means "fred.txt" (in case you hadn't guessed, I *much* prefer words to symbols in the body of the definiton of such things - but that's a separate argument). Of course, this was also all gist to my argument that role *use* should be done as:: role:`thing` rather than:: `role: thing` Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Thu Aug 9 09:43:10 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 9 Aug 2001 09:43:10 +0100 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: <001801c120af$51bc38e0$f05aa8c0@lslp7o.int.lsl.co.uk> Garth T Kidd wrote: > I suspect I'm currently leaning in the direction of parser-loaded > directives having the ability to "hook" the parser to alter the way it > interprets the input [examples]_, but not affecting the composition of > the parser output in such a way that would make it impossible for an > `OOB` reST engine to reverse-engineer from the XML or node tree some > valid reST input that would create the same output. I'm a bit worried that directives are being used for two different purposes (and I *think* they may be getting confused). The first, and traditional (by its name) purpose is to act as a pragma that changes the behaviour of the text (or maybe just the text after that point in the document stream). An example would be:: .. mode:: HTML which is attempting to enable the various extensions needed to prepare an HTML document. The second usage is as a way of adding new "commands" to reST - for instance:: .. newline:: .. section:: Garth's section title *One* of the uses of the pragma directives is to load definitions for the command directives (the other example of a use for a pragma directive is the "enable lazy indentation" one). I think we need to distinguish these two usages - perhaps the names I've used help. For command directives, one clearly looks up the directive name to see if there is a method defined for it. If there is, one executes that method on the directive's body, and inserts the resultant data as a node with its tag taken from the directive name. If there is not, one emits the directive name and body as a - I think that is what David proposes? Possibly flagged with a Warning. That works well in practise, I think. For instance:: .. fred:: Some {funny} text. might generate:: Some funny text. if recognised, but:: Unrecognised directive "fred" Some {funny} text. (erm - I haven't even *tried* to write sensible XML for those - but I hope the idea is evident). In the second case, regenerating the original text is clearly possible. In the first, it's more of a problem, since we don't know how to reverse map . Either we say "tough, if the directive understander loaded didn't have a reverse mechanism, we can't do it", or we require people to always provide a reverse engine. I'd opt for the optional route, myself - if people are writing their own directive understanders, then we can't really mandate that they should provide the reverse mechanism. It does suggest to me that pragma directives must insert a node in the DOM tree, though, so that one can *know* what engines one needs to use to regenerate reST. For pragma directives, if the directive is not recognised, I think that the directive *itself* should be emitted as a node, and that it should be flagged as an Error. That gives the user some hint of why their document looks odd (!). > .. _OOB: Out of the box, ie without any directives loaded. Now, how on > Earth do we render this link target, or any other non-URI > link target > that hasn't been rescued by some directive? I'm using it as a > footnote. Hmmm. Presumably one should not lose the footnote - it is still text, after all. Emit it with a warning that it is not referenced? Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Thu Aug 9 09:21:44 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 9 Aug 2001 09:21:44 +0100 Subject: [Doc-SIG] Colons and footnotes (was RE: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes") In-Reply-To: Message-ID: <001701c120ac$531da500$f05aa8c0@lslp7o.int.lsl.co.uk> Garth T Kidd wrote (after me): > > *My* reason for suggesting using them was, however, entirely > > orthogonal, and was simply that it is one less thing to remember, > > if *all* hyperlink targets start with ``.. _`` and end with ``:``. > > Yep. That's pretty much it for me. Permitting or mandating colons also > removes the requirement for footnote target identifiers to not include > the square brackets, as I'd hopefully be able to distinguish between a > footnote reference and a link to a footnote like so:: > > This line has a footnote reference. [1]_ > > This line refers to the footnote `[1]`_ > > Hmmm. Or maybe I should just dig my heels in and insist upon removing > the square brackets from the identifier. :) Hmm. Excuse my thinking out loud (slowly) below. It may be easier to consider "natural" (there's a poor word to use in a debate!) implementation of such links in HTML. Given the raw text:: This is a footnote [1]_. I had been expecting HTML *something* like:

This is a footnote[1]. to be generated (note I've chosen to lose the space before the footnote - this may or may not be sensible in practice). This, of course, implies the existence of something like:: [1] The footnote. at some place. *Clearly* (!) if one knew the "rule" for making up footnote names one could refer to the footnote by that name elsewhere, but that's implementation dependent (unless we *specify* such rules - but it's still messy). But why did I prepend "footnote" to the "1"? It was exactly because I had assumed that we wanted a different namespace (heh, in the programming sense, this time) for different types of link. What *you* are proposing, I think, is just to drop that assumption. So if the HTML generated was instead something like::

This is a footnote[1]. then one could equally have reST text like:: And this also refers to footnote 1_. and they would work. So the issue is: Do we want different sorts of hyperlink to occupy different namespaces, or the same namespace. Personally, I don't mind. Looks like Garth votes for no, so what does David think? Whatever the decision, it should then be written up in the relevent spec. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Thu Aug 9 10:00:05 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 9 Aug 2001 10:00:05 +0100 Subject: [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: <001a01c120b1$aebd8240$f05aa8c0@lslp7o.int.lsl.co.uk> Garth T Kidd responded: > > > ``.. section::``, anyone? > > > > I suspect facetiousness (!) but it may come to that. > > I'm not being facetious_. "Section" is the generic term most Microsoft > Word users would use to describe a chapter or appendix. Ah - no, missed my target. The facetiousness I suspected was in your using a directive to do the task, when (I thought) general agreement was that directives were for *unusual* things, which this clearly would not be (in a document production mode). And "section" is also common in LaTeX, of course (my earlier background being odd things at University, followed by Runoff, followed by TeX and LaTeX). > An application handling a "section" directive doesn't need > to worry about having an insufficiently large list of words > used in headings to describe a new section. Chapter and > Appendix are obvious. `Fit the First` isn't. There's a different argument here (which is related to my worries about field lists as well), namely how one knows which things are legitimate (well defined) and which are not. I've always assumed that somewhere someone will have defined a dictionary of names and meanings for such things. But I'll try to address this elsewhere, maybe today (tomorrow is a Zoo trip, so isn't on). > What if we want to discuss Proposition 23? :: > > Proposition 23: Discussion > ========================== > > Oops. :) Well, depends on how one implements it! One either doesn't "know" Proposition as a keyword, or perhaps one has to escape the ":" if one really wants a colon. But maybe that is a *real* show-stopper, and directives *are* the way to do this. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Thu Aug 9 10:31:55 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 9 Aug 2001 10:31:55 +0100 Subject: [Doc-SIG] Field lists and label blocks Message-ID: <001b01c120b6$213913d0$f05aa8c0@lslp7o.int.lsl.co.uk> Markup versus meaning ===================== Almost all of reST is dealing with markup - presentation. This is even true for the hyperlink stuff - allowing one to click on a link is *really* a presentation issue. The exceptions are directives and field lists. Directives, being a general escape mechanism, are possibly *anything* (so I'll ignore them here!). Field lists are the one example of attempting to allow "data mining" within a document stream, by embedding *meaningful* tags such as Author or Version. I would contend that we could produce a perfectly reasonable first version of reST with just the markup elements. Directives seem to be useful, and the people involved all have affection for them, so they're in too. But field lists are a different kettle of fish. They're for a different purpose, and require a separate justification. Of course, historically I have argued *for* such a purpose, but I wouldn't particularly mind making them mode dependent - I'll argue this below. Field lists =========== In reStructuredText.txt, David describes Field lists. As I understand it, the basic concept is to allow the user to enter text of the form (broadly):: : (the actual syntax being undecided as yet). The name *will* be RFC822 compliant (which is good). All of the examples show the as being confined to the rest of the line - that is, no line breaks allowed. Proposed use examples are basically those one might expect in email (and thus also PEPs), and some attempt to allow specifying things like authors, copyright, etc., within a document. Label blocks ============ In http://www.tibsnjoan.co.uk/docutils/fat.html, I describe label blocks (sorry - the document doesn't have internal labelling, so I can't give a direct link). Label blocks are defined as:: : where is hand-defined as a case-insensitive Python identifier in which hyphens are also allowed (is that RFC822?). Label blocks have some implementation details, though: 1. A paragraph is only a label block if is found in a dictionary of valid names, otherwise it's just a normal paragraph (maybe with a Warning being issued). 2. The "definition" associated with a name indicates whether is restricted to the rest-of-line, or whether it may be longer (technically, whether its DOM tree node may have children). Specific examples would be:: Author: Guido van Rossum Authors: * Guido van Rossum * Tim Peters 3. The "definition" also indicates which forms of DOM node the children may be - for instance, bullet list, paragraph, etc. In an reST context, I would replace the single colon by two, and I would add a rule that if children are allowed and present, then a blank line is not allowed after the - i.e., as in cells within a table, the line prepares one for a new block. When do we want these ideas? ============================ Field lists and label blocks are both about being able to extract *meaning* from a document stream, rather than just presentation. I would contend that they do not, thus, belong in the base document format at all, but in the particular modes where they are useful. Note that making this decision means we can get reST *itself* out the door faster, that we get a simpler reST document (a Good Thing), and that the decisions about how to do such things can be application dependent, and thus easier to design and reach agreement on. Let's consider proposed modes for a minute: * Email - clearly field lists map well to the initial headers of an email. In fact, I think one should say that for email mode, one adopts the *rules* for the headers for an email, as they are presented in the relevant RFCs. * PEPs - the start of a PEP is a series of field lists, and they look as if they are modelled heavily on email headers. I would suggest the PEP headers be supported exactly as they are defined in the PEP documentation. * HTML and document preparation modes - I'm not at all convinced of the need for any such construct here. Certainly an HTML document doesn't have such specialised items (oh, there are things like

, but they aren't really the same). If one wants to do equivalent in HTML, one needs to look at tags. And if one wants to write LaTeX or somesuch, then there is no need for field lists as proposed. * Python - well, this is the meat of it. I would contend (see below!) that field lists are not adequate to do useful things in Python docstrings. I would either leave them out entirely (*not* necessarily a bad idea), or else provide something more powerful. If we make field lists or whatever mode dependent, then it is only in the Python case that we have any decisions to make. Life gets simpler. Why field lists aren't enough ============================= Field lists attack the problem of single line entities, such as "Author". But they don't adapt well to (obvious) extensions like "Authors", nor do they provide leverage for things like "History" where there may be multiple paragraphs (and I, for one, would also like to be able to do things like "Dedication"). I think that a reformed label block *would* work, allowing examples like:: Author:: Tony Ibbs Authors:: * David Goodger * Garth T. Kidd Dedication:: In memory of my father. He would have appreciated the joke that I would have gotten a lot further with this a lot sooner if he hadn't died. Arguments:: ``fred`` is the first argument. ``jim`` is the second. Are we overloading "::" too much? Well, it's use in directives is justified partially on the grounds that we've already got it to hand (!). And if someone mistakenly inserts a blank line after a line, then they get a literal block, which is a fairly harmless error. Enough already, Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From garth@deadlybloodyserious.com Fri Aug 10 02:58:34 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 11:58:34 +1000 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: <001801c120af$51bc38e0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Interesting thinking on how to distinguish pragma and command directives! To minimise the impact on reversability, my current take is that pragma directives (at minimum) have to be represented in the output as directive tags, and -- if they hook the parser to extend what it can output -- should contain elements describing what extended elements can now be produced. That way, an OOB parser can at *minimum* say "this element was loaded by the Fnord extension, but not having the Fnord extension loaded (or it not supporting reversability) I can't reproduce its original input". "Simple" command directives like ``sidebar::``, where the directive block is parsed and inserted under a directive of a the same name as the extension, could be documented as such in the declaration of which extensions are used in the document, in which case the parser can always reproduce the original input. > myself - if people are writing their own directive understanders, then > we can't really mandate that they should provide the reverse > mechanism. No, but we should make sure that at least the parser can figure out which extension was responsible for the unknown element, and complain appropriately when trying to re-generate the input. Any takers on a standard method of embedding the original input? Maybe all non-simple directive-driven output *should* be resident in a directive tag:: Simple extensions have no code associated with them, and implicitly declare a single directive of the same name. Such directives generate an output element of the extension name with the argument attribute as per generic directive tags, and contain pretty much any valid reST markup. Reversability is simple: if you see a tag named for a previously declared simple extension, reverse its contents and embed them in an appropriate directive. line 1,2 to 35,2 line 1,6 to 430, 1 ... > It does suggest to me that pragma directives must insert a node in the > DOM tree, though, so that one can *know* what engines one needs to use > to regenerate reST. Amen. >> .. _OOB: Out of the box, ie without any directives loaded. >> Now, how on Earth do we render this link target, or any >> other non-URI link target that hasn't been rescued by >> some directive? I'm using it as a footnote. Hmmm. > > Presumably one should not lose the footnote - it is still text, after > all. Emit it with a warning that it is not referenced? Do you see any square brackets? :) Actually, it's not in our interest to try and resolve links -- that's the application's problem, which is why we don't need to extend the parser to handle WikiLinks or InterWikiLinks. We should, however, define whether or not footnotes and normal links share the same space, etc. I'm currently thinking that a link to a non-URI (and otherwise unres... Damn. * Let's say we want to use non-URI link targets as automatically numbered footnotes, which I think is pretty nifty. Explicitly named footnotes are still perfect_ for citing references, but authors are freed from the tyranny of having to avoid footnote number collisions. .. perfect: Perfection is great! And, since this link target doesn't have anything resembling a URI in it, it's an auto numbered footnote, right? How would anyone else make a non-footnote link to it? I have no idea. That said, I'm happy to make that particular rare case harder or impossible if it frees me from the need to make up unique identifiers for every footnote. I use a *lot* of footnotes. I'm sure David still has nightmares about my first few messages to this list. :) .. Yes, there's a loophole. Read on. * If ``perfect_`` above is to become a footnote, the parser needs to know before it finishes its work that it needs to spit out a footnote tag, not a link target tag. * In turn, that means we can't wait until the parser finishes for the application to parse the link target and figure out whether it resolves or not. * Therefore, we need a way for applications to specify a resolver function to the parser. The function would be called when the parser can't make sense of a target, i.e. when:: * The target text is not a URI, *and* * The target text itself doesn't parse as a link. If a target turns out to be a reST link, ie it's a single word or backquoted string followed by an underscore, the parser should treat it as an indirect link. That would let me refer to a section called ``Extremely Long Heading`` as ``ELH_`` as follows:: See ELH_ for more details. .. _ELH: `Extremely Long Heading`_ That would otherwise be a footnote, but a pretty boring one. :) * The edge case is footnotes that accidentally resemble something that the external resolver recognises. I think that's probably just too bad. In summary: + The application should provide the parser with a function to handle resolution of links the parser can't otherwise figure out; (Note that this is a complete reversal of my previous position on link resolution :) + If the external link resolver can't figure it out, reST should treat it as an automatically numbered footnote; and + I'm still going on about indirect links, even though I suspect that they're already in the spec. I lack the time right now to wade through and check. Bueller? Regards, Garth. From garth@deadlybloodyserious.com Fri Aug 10 03:23:55 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 12:23:55 +1000 Subject: [Doc-SIG] Hyperlink targets and roles In-Reply-To: <001901c120b1$a1e38fb0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: >> My experience with InterWiki links tells me that we don't want a >> delimiter between the namespace base and the extension. The >> user can put the ``#`` at the tail-end of the base if appropriate. >> If we implement namespaces, I expect to often see ``/``, ``?``, >> ``?something=`` and ``&something=`` at the tail end of the base. > > Gosh - that's altogether more ambitious than I wanted to be - you're > clearly trying to allow the full flurry of HTML references to be done > via reST, whereas I was just wanting to allow someone to reference a > *specific* label in a different file. Why restrict it? Once you get used to using InterWiki to let you say WikiName:WikiPage to refer to any page on another Wiki, you get annoyed when you have to go to any more effort than Amazon::B00000F169 to refer to Dark Star on DVD, Google:Goodger to search for Goodgers on the Internet, reSTBug:443275 to refer to a tracker item, Jargon:fnord to look up "fnord" in the Jargon File, and so on. If reST linkbases turned out to be exclusively for the use of referring to a named A element in a destination HTML document, I think any potential WikiUsers would go just a little batty. :) Of course, if this is an extension then it's up to the application to make the rules. If linkbases become a part of the reST spec, however, I feel we should just append the trailing part to the base and let the user specifiy any required delimiter at the tail end of the base. > Anyway, my proposed new role *does* just identify a file, and the role > translation and the label *can* be separeted by "#" in the resultant > HTML, 'cos that's the limit of my ambition. :) I don't think this needs a role:: .. linkbase:: reSTBug = http://sf.net/tracker/\ index.php?func=detail&group_id=7050&atid=107050&aid= Check out `reSTBug:443275`_ for details. Or, check out the `test refactoring tracker entry`_. .. _test refactoring tracker entry: reSTBug:443275 > Trying to implement all the wonders of queries in URIs and so > on is too much ambition for reST (now, and maybe forever), That's why we dodge entirely and just let the user specify some leading text as the base to which we'll directly append whatever else they specify later. We don't have to understand any of it at all. > "linkbase" sounds too low level to me - "base" is very non-obvious to > me. For some reason, I immediately thought the solution was to just call it ``base``. :) > What you're saying is that one can adopt conventions that allow one to > parse this after reST has finished with the document. ... or, now that I've figured I can abuse non-URI links as automatically numbered footnotes, figure it out whilst reST is still parsing the document. > But we've *got* roles, and they are thus an obvious thing to use for > this purpose - a role amends its associated interpreted text, and if > that interpreted text is being used as a link, then the obvious thing > for a role to do is to amend that link. Hmmm. You never know, you might convince me. :) > Maybe we need to be more explicit:: > > .. linkrole:: "fred" means "fred.txt" I'll meet you half way:: .. linkrole:: fred=fred.txt# .. linkrole:: reSTBug=http://sf.net/tracker/\ index.php?func=detail&group_id=7050&atid=107050&aid= Check out `reSTBug:443275`_ for details. Or, check out the `test refactoring tracker entry`_. .. _test refactoring tracker entry: `reSTBug:443275`_ Or, check the documentation under `fred:test refactoring`_ Seem reasonable? Well, except for worrying about how roles get in the way of people linking to `ST: TNG`? > (in case you hadn't guessed, I *much* prefer words to symbols in the > body of the definiton of such things - but that's a separate > argument). Yep. > Of course, this was also all gist to my argument that role > *use* should> be done as:: > > role:`thing` Amen! Some more stuff to roll around: * Can we deal with roled links with no backquotes? :: reSTBug:443275_ * If our trailing portion has spaces, where do we put the backquotes? :: fred:`this part of the document`_ or :: `fred:this part of the document`_ Regards, Garth. From dgoodger@bigfoot.com Fri Aug 10 04:07:11 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:11 -0400 Subject: [Doc-SIG] Slightly newer version of quickref In-Reply-To: <007001c11fe0$f4657630$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote on 2001-08-08 4:05 AM: > I *did* have time to make the next iteration of the quick > reference... > > http://www.tibsnjoan.co.uk/reST/quick_reST.html Although it's a great resource, I think it has grown too large to be usable as a quick reference. Perhaps a quickref page (like the first version, just the yellow bits) with links to a separate details page (full explanations)? How about adding links to the project home page? Better yet, how about adding the quickref *to* the project? Please let me know your SourceForge ID (get a free account if you don't already have one), and I'll add you as a developer. We can put the quickref into the project docs. Once the parser is done, we can *do* the quickref with reStructuredText. Bugs: - "Inline Markup", third paragraph of blue section:: Markup characters can be escaped with backslash ("\\") - for instance, "\*" - or by enclosing them in 1. We don't need a double-backslash here. A Python habit? 2. "*" (inside quotes) need not be escaped. Rephrase as, "- as \*in this example* -". - "Inline Markup", end of blue section:: For instance, consider ``this example, which has lots of spaces``. That won't work. The second line is indented relative to the first, and will currently be recognized as a definition list. The unclosed backquotes will generate a warning (level 1). The sentence ending the preceding paragraph doesn't make sense in this context: "Spaces at the *start* of a line are counted relative to the left margin of the current paragraph." Perhaps the same bug. - "Inline Markup", yellow block following "The correct form for inline markup is:". There are omissions and small errors here. Why not just copy the text from the spec verbatim? Into the "Details" page though, please. - "Links". This is still wrong:: Internal crossreferences, like example_. .. _example: This is an example crossreference target. The target should be:: .. _example: This is an example cross reference target. - "Definition lists". Still waiting for an answer on: The spec (and the parser) require blank lines between definition list items. This requirement could be relaxed, as it has been for other lists. What do you think? Your example has no blank line between definition list items. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:12 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:12 -0400 Subject: [Doc-SIG] Re: reST: standalone hyperlinks In-Reply-To: <000801c11feb$7670e3d0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-08 5:21 AM: > Referring to the URI spec is not sufficient, since traditionally > people have used ad-hoc schemes to detect URIs (particularly since > the REs to detect them properly get, well, somewhat complex). I've expanded the overview a bit in reStructuredText.txt: """ Two forms of URI are recognized: 1. Absolute URIs. These consist of a scheme, a colon (':'), and a scheme-specific part whose interpretation depends on the scheme. - The scheme is the name of the protocol, such as 'http', 'ftp', 'mailto', or 'telnet'. The scheme consists of an initial letter, followed by letters, numbers, and/or '+', '-', '.'. - The scheme-specific part of the resource identifier may be either hierarchical or opaque. - Hierarchical identifiers begin with one or two slashes and may use slashes to separate hierarchical components of the path. Examples are web pages and FTP sites: http://www.python.org ftp://ftp.python.org/pub/python - Opaque identifiers do not begin with slashes. Examples are email addresses and newsgroups:: mailto:someone@somewhere.com news:comp.lang.python With queries, fragments, and %-escape sequences, URIs can become quite complicated. A reStructuredText parser must be able to recognize any absolute URI, as defined in RFC239_. 2. Standalone email addresses, which are treated as if they were ablsolute URIs with a 'mailto:' scheme. Example:: someone@somewhere.com Punctuation at the end of a URI is not considered part of the URI. """ I don't think the spec needs to be any more detailed than this. (If you do, please write the text! I'm sick of reading that RFC.) If the reader wants to know more, they can follow the links to the RFC. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:13 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:13 -0400 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: <000b01c11ff0$e11f46e0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-08 5:59 AM: > Just one note - *do* we need ``.. comment::`` if we are going to > retain ``.. `` as *meaning* comments? Nope. You forget about ``.. comment::`` and I'll forget all about ``.. hyperlink::`` and ``.. footnote::``. Deal? > A separate note, though - I *don't* like having a blank comment > represented as:: > > .. > > (see the problem? that trailing space is damned difficult to see, and > terribly easy to leave out in consequence). I've redefined explicit markup starts to be two periods followed by whitespace, which includes a newline (end of line). Ditto for the space after bullets & enumerators. > On the other hand, I don't object at all to *not allowing* a blank > comment! I think they're useful, in the rare case that you've got a comment or directive (anything expecting indented text) followed by a block quote. The blank comment serves to terminate the comment or directive; otherwise the block quote would be swallowed up. A tiny but practical wart. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:14 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:14 -0400 Subject: [Doc-SIG] Comments on the "problems with structured text" In-Reply-To: <000e01c11ff7$ab551e70$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: [Tony, on tables and header rows] > It *might* be worth emailing the person who wrote/maintains the code > to see if they are interested (and, of course, it gives them egoboo > since we're using their module as a contributing reason for adopting > this format). I wrote to the developer, Takaaki OTA, some time ago, asking for advice on how to change it. He showed me how hard-coded hyphens were, and didn't seem interested in adding support for header rows. I'll write again, this time posting to the mailing list (http://table.sourceforge.net). [on problems.txt] > I think that a "Historical background" document, containing the pros > and cons of past arguments, would be a good thing - partly for the > same reason we have "refused" PEPs, and partly just 'cos that sort > of thing *can* be neat. Of course, it's yet more work to saddle you > with. When I have time, I'll update it. But it's low-priority. [on the Grand Unification Theory] > Hmm - you haven't watched the Doc-SIG for as long as I have. I have read through much of the archives, though. This debate dates back to 1996 on Doc-SIG. It may go back further, elsewhere. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:12 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:12 -0400 Subject: [Doc-SIG] Re: Attributes and also namespace pollution In-Reply-To: <000501c11fe9$b69ce0a0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: [David] > I'd rather leave this up to a BDFL pronouncement, if Guido is > willing. [Tony] > I definitely think this is a matter on which to seek BDFL guidance - Added to the DPS To Do list. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:12 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:12 -0400 Subject: [Doc-SIG] Re: C signatures in C code docstrings In-Reply-To: <000101c11fe7$2d346740$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote on 2001-08-08 4:50 AM: > 257:`One-line Docstrings`_ > > Hmm. When discussing the "signature" in C functions - shouldn't the > DPS mandate that this signature line should be (a) of a particular > format [the obvious one!], and (b) that the tool "looking for" and > interpreting code structure should make use of said signature if > present. [David] > > (a) Sounds good. Care to provide the wording? > > > > (b) PEP 257 doesn't care about the DPS, but this could be added to > > PEP 258. [Tony] > OK. Please put a note in the appropriate place that this will be > added, and I will provide wording at some point (but it would help > to have a place to *put* the wording first, so I can try to make it > fit in). For (a), the text should be a new list item at the end of the "One-Line Docstrings" section of PEP 257. For (b), make a new section "C Extension Function/Method Signatures"? > (I can specify some heuristics for recognising as well, or you can > just look at earlier versions of my own code, which had some such > in) OK, please specify or tell me where I should look. Thanks. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:13 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:13 -0400 Subject: [Doc-SIG] Re: reST: Option lists and descriptive lists In-Reply-To: <000901c11fee$0fcf83e0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-08 5:39 AM: > Hmm. I think that if you can't use descriptive lists to represent > option lists naturally, then that is a signal that descriptive lists > are wrong. Rather than trying to shoehorn option lists into definition/descriptive lists, I'm trying to provide for them in a natural way. Lists of command-line options, such as found in man pages and '--help' usage output, are not the same as definition lists. > At which point we need to stand back and think again. And the way to > do *that* is to take lots of examples and to look for commonality. That's what I have done. I've looked at a lot of man pages and '--help' usage output, and I see option lists as described in the spec. > *I* would contend that the first can be phrased like the second and > still look OK - that is, as:: > > -a -- Output them all > -b or -both -- Output just two > > is that contentious? (i.e., do we agree that one unified form would > serve for both, whatever that form might be). Sure, one unified form could be used for both options and arguments, but that's not what *is* being used. If there's a perfectly good and unambiguous model out there, why not use it? > I *still* don't know the solution for descriptive lists, but I do > feel that:: > > name > description > > is one of the worse ways of presenting them, in generality - > although it does have its uses sometimes. But its use of screen > estate vertically is Not a Good Thing. So come up with a better, unambiguous alternative, and fame & fortune will be yours. (Well, maybe not fortune. Not much fame either, I'm afraid. A bit of egoboo is all we open-sourcers can expect.) > I do agree (by now) that ``--`` is sensible within text as well - but > that doesn't mean we have to discard its use for descriptive lists > (where it is fairly natural) if we can discern (reasonably) > unambiguously that that is what we are doing. I don't see how we can. [example omitted] > It *does* seem to require blank lines to be unambigous, but by the > "a list has to have at least two elements rule" (which I think you > give for enumerated lists) I think this *could* work Please note that I've removed the "two or more elements" rule. If it looks like an enumerated list item, it is one. > On the other hand, for the case of parameter lists which are *mainly* > meant for interpretation by the command line user, what's wrong with > just allowing a user who wants that to do:: > > Usage:: > > fred.py > > -a all > -b or -both just the two Nothing wrong with it. And until option lists (in whatever form) are implemented, that's all that *is* available. The option list construct is convenient and unambiguous, and (AFAICT, not having implemented it yet) ought to work well. Why all the resistance? -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:12 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:12 -0400 Subject: [Doc-SIG] Re: reST: Section titles and "underlining" In-Reply-To: <000701c11fea$a8c0f1f0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-08 5:15 AM: > > > You don't say which characters may be used as "underlines" > > > for section titles. I've amended reStructureText.txt, "Section Structure", as follows:: An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. Specifically, an underline/overline character may be any non-alphanumeric printable 7-bit ASCII character [1]_. In a footnote I list them all specifically. > Oh - thinks - so one can also do:: > > Section title > +-+-+-+-+-+-+ No, just one character, repeated, per underline. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:14 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:14 -0400 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: <001801c120af$51bc38e0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-09 4:43 AM: > I'm a bit worried that directives are being used for two different > purposes (and I *think* they may be getting confused). I don't see much difference between "command directives" and "pragma directives"; command directives simply don't act on any data. The big difference I see is one of scope. A true pragma (global directive?) will affect the entire parser session, whereas a local directive only affects its text block. > For pragma directives, if the directive is not recognised, I think > that the directive *itself* should be emitted as a node, > and that it should be flagged as an Error. That gives the user some > hint of why their document looks odd (!). Yes, this is the plan. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:13 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:13 -0400 Subject: [Doc-SIG] Comments on the reST notes In-Reply-To: Message-ID: [Tony, on horizontal rules] > Oh, by no way should they be in "plain" reST - but I would advocate > support in (for instance) the HTML-preparation mode of reST (indeed, > I do, and that is the correct place for it). But they'd still need support in the intermediate data structure (dps.nodes & the DTD). [Tony, on batch environments (like Wikis) and "guessing"] > You're assuming that the "author" gives a toss [Garth] > I'm pretty sure that even if the XML above were translated to HTML, > a reader would be able to figure out that there was some crummy > indentation. If a community suffered enough from documents with > crummy indentation from authors who never bothered to go back and > read their contributions, I suspect they'd add a "click here to read > the original reST" button. :) I don't know how Wikis work. When somebody posts a new message I would expect it to say "Error in message: please correct" until there are no errors, then show the processed version to the user and allow them to post or edit their message. In any case, this is an application issue. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:15 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:15 -0400 Subject: [Doc-SIG] Re: Non-breaking spaces In-Reply-To: <000201c11fe7$dd832370$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: I've added a To Do for this. /David From dgoodger@bigfoot.com Fri Aug 10 04:07:12 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:12 -0400 Subject: [Doc-SIG] Hyperlink targets and roles In-Reply-To: <001901c120b1$a1e38fb0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Name: maybe "baselink" or "basedoc" or "baseref"? [Garth] > If your application needs linkbases, currently you don't even need > roles. Just look for linkbase directives and then parse link targets > to see if they begin with a particular base name and a colon. Let's > say someone specifies the following text: > > .. linkbase:: dictionary=http://www.dictionary.com/cgi-bin/\ > dict.pl?term= ... > Look out for the fnords_! > > .. _fnords: dictionary:fnord ... > When you see the linkbase directive, add the linkbase to your table. > When you see the ````, note that it starts with a valid > identifier followed by a colon and that identifier matches a > linkbase, and parse it accordingly. I like the idea of putting the base document reference in the target rather than in the text as a prefix to the hyperlink itself. It reads better, which is the whole point of indirect hyperlinks in the first place. However, there is a problem with the above approach: 'dictionary:' looks just like a URI scheme ('http:', 'mailto:', etc.). It needs differenct syntax. Something like:: .. _fnords: (dictionary)fnord or an optional first argument:: .. _fnords: dictionary fnord And I would parse this into something like:: fnord > .. Hmmm. If we adopt backslashed line extension, we should trim > whitespace up to the indentation level of the block. We don't need backslashed line extension. I've implemented hyperlink targets to collect all text on the same line as the markup start and on subsequent indented lines, up to the first blank line, strip them of whitespace left & right, and concatenate. For example, these are all equivalent:: .. _target: http://a.very. long.host.name.com/ index.html #fragment .. _target: http://a.very. long.host.name.com/ index.html #fragment .. _target: http://a.very.long.host.name.com/index.html#fragment The namespace/linkbase/baseref/etc. directive can do the same. [Tony] > Of course, this was also all gist to my argument that role > *use* should be done as:: > > role:`thing` > > rather than:: > > `role: thing` I'm coming to prefer the former (role outside of the quotes). Of course, with a properly implemented interpreted text resolver, we won't *need* to explicitly specify roles much anyhow. In Python docstring mode, identifiers won't need roles; they can reliably be inferred from context. I see the need for explicit roles with such concepts as index entries and inline graphics. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:14 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:14 -0400 Subject: [Doc-SIG] text in hyperlink targets In-Reply-To: Message-ID: Garth T Kidd wrote on 2001-08-08 6:59 PM: > .. _OOB: Out of the box, ie without any directives loaded. Now, how > on Earth do we render this link target, or any other non-URI link > target that hasn't been rescued by some directive? I'm using it > as a footnote. Hmmm. Perhaps I'll put in a check for spaces inside text in hyperlink targets. URIs may not contain spaces. The parser can generate a warning, including the entire "target" as a literal block. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:13 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:13 -0400 Subject: [Doc-SIG] Colons and footnotes (was RE: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes") In-Reply-To: <001701c120ac$531da500$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: [Garth] > ... remind me: I think we should make footnote identifiers > (excepting the square brackets) implicit hyperlink targets in their > own right. On rereading, this does seem like a good idea. Then ``.. _[1] footnote`` becomes the equivalent of:: .. _1: [1] footnote (The above lacks the semantics, of course.) The "namespace" for footnotes and hyperlinks is already one and the same, but footnotes keep their brackets now; this change would simply drop the brackets. The footnote reference, ``[1]_``, and hyperlink, ``1_``, would both refer to the same thing, but their representation may be different. I don't think there will be many conflicts, since footnotes are often numbered and must be short. [Tony, on using colons with footnotes] > *My* reason for suggesting using them was, however, entirely > orthogonal, and was simply that it is one less thing to remember, if > *all* hyperlink targets start with ``.. _`` and end with ``:``. I don't want to insert ':' after the footnote label. Footnotes are visible after processing, therefore I'd like the input and output to correspond as much as possible. Hyperlink targets are not (typically) visible after processing, so their syntax doesn't matter. The notion of ':' as "mapping" is important here. Remember that and you won't (a) mistakenly put the ':' on a footnote, (b) forget to put ':' on a hyperlink target, or (c) mistakenly put note text on a hyperlink target. ``.. _external: URI`` means, "when you see ``external_``, link to URI". ``.. _internal:`` (followed by a blank line) means, "when you see ``internal_``, link to *here*". Maybe we should change the ':' to '=', in order to emphasize the nature of the mapping going on:: .. _target=URI Perhaps, to make footnotes even more distinct from hyperlink targets, we can drop the leading '_' too. Then a footnote would look like this:: .. [1] footnote We'd lose a little bit of consistency (the reference, ``[1]_``, would have to keep its trailing underscore), but the visual correspondence (before and after processing) would be better, and the hyperlink target would no longer be explicit. > Now,this is convenience for the author, so not necessarily our > preeminent goal, but two of us at least keep typing the things and > then having to remenber to remove them (so, two out of a > scientifically selected sample of, erm, how many...). Just because you can't remember colons are *not* necessary doesn't mean they *are*! ;-) [Tony] > So the issue is: > > Do we want different sorts of hyperlink to occupy > different namespaces, or the same namespace. Good summary of the issues. The footnote references and hyperlinks were already sharing a namespace in the parser, but the footnote refs kept their brackets, making hyperlink references messy. I'm leaning toward merging them completely. Let me sleep on it, think about it over the weekend. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:14 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:14 -0400 Subject: [Doc-SIG] Suggestions for reST "modes" In-Reply-To: <001a01c120b1$aebd8240$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: [Tony, Garth, Tony, Garth] > > > > will be needed. I suspect that a means of marking > > > > Chapter, Appendix, etc., explicitly may be needed [...] > > > > > > ``.. section::``, anyone? > > > > I suspect facetiousness (!) but it may come to that. > > I'm not being facetious_. "Section" is the generic term most > Microsoft Word users would use to describe a chapter or appendix. An > application handling a "section" directive doesn't need to worry > about having an insufficiently large list of words used in headings > to describe a new section. Chapter and Appendix are obvious. `Fit > the First` isn't. You realize that section headers produce sections, which can be nested indefinitely. I'm thinking of an option to the output formatter, telling it what level of its native "tag" should correspond to the document element (which is simply the outermost enclosing section). So you could tell your book formatter to start at Chapter, or Section, or Appendix, or Preface. I'm pretty certain the parser doesn't need to know about any of this. > .. _Fit the First: `The Hunting of the Snark: an Agony in Eight > Fits`_, by Lewis Carroll. Note that this should be a footnote, not a hyperlink target. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:07:15 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:07:15 -0400 Subject: [Doc-SIG] Field lists and label blocks In-Reply-To: <001b01c120b6$213913d0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-09 5:31 AM: > Markup versus meaning > ===================== > Almost all of reST is dealing with markup - presentation. I would disagree. It deals with extracting structure from presentation. Admittedly, the amount of structure gleanable from plaintext is meager, and its level is quite low for the most part. Field lists are potentially higher-level structure. (I thought of another name for field lists: "label lists"; whaddya think? Oh, I see that Tony already had "label blocks"; similar.) > But field lists are a different kettle of fish. They're for a > different purpose, and require a separate justification. I don't see why they should be excluded. > All of the examples show the as being confined to the rest of > the line - that is, no line breaks allowed. That's an accident. I actually intend:: : The consists of one or more body elements> Including nested field lists! One-liners are merely a degenerate form. Even in email RFC822 headers, you often end up with multi-line (but single "paragraph") bodies. Indentation is all that's needed to determine if a field list item is a one-liner or multi-liner. In some modes' contexts, such as email headers, even indentation isn't necessary. > Label blocks > ============ ... > Label blocks have some implementation details, though: > > 1. A paragraph is only a label block if is found > in a dictionary of valid names, otherwise it's just > a normal paragraph (maybe with a Warning being issued). When working on the concept for field lists in reStructuredText, I thought about this as well. I rejected it as too limiting (somebody is always going to want a new field name). It's feasible in limited contexts, such as bibliographic fields, PEP headers, or email headers. And even in those contexts, unknown fields will not trigger an error, but will be shown as a simple field list instead. > 2. The "definition" associated with a name indicates > whether is restricted to the rest-of-line, > or whether it may be longer (technically, whether > its DOM tree node may have children). Specific > examples would be:: > > Author: Guido van Rossum > > Authors: > * Guido van Rossum > * Tim Peters > > 3. The "definition" also indicates which forms of DOM > node the children may be - for instance, bullet list, > paragraph, etc. We may put this kind of checking ability into the DPS, or perhaps the output formatter, but the parser needn't know about it. > In an reST context, I would replace the single colon by two, Added as syntax alternative 6. It's got potential. > and I would add a rule that if children are allowed and present, > then a blank line is not allowed after the - i.e., as in > cells within a table, the line prepares one for a new block. I don't follow. If this still applies after reading my explanation of body elements in field list item bodies, above, please explain. > When do we want these ideas? > ============================ > Field lists and label blocks are both about being able to extract > *meaning* from a document stream, rather than just presentation. > > I would contend that they do not, thus, belong in the base document > format at all, but in the particular modes where they are useful. > Note that making this decision means we can get reST *itself* out > the door faster, that we get a simpler reST document (a Good Thing), > and that the decisions about how to do such things can be > application dependent, and thus easier to design and reach agreement > on. Implementing the *interpretation* of field lists may be tricky, but their *parsing* is not a big deal (once the syntax is decided on; I like either #5 [":field: body"] or the new #6 ["field:: body"]). The interpretation of field lists will not be done by the parser anyhow. It's the DPS itself, or an output formatter, or an intermediate transformation component, that will do the interpretation. (BTW, the introduction of the concept of "modes" has helped me to gel some ideas I had about the DPS framework. We need mode-specific modules as middleware between the input parser and output formatters.) > Why field lists aren't enough > ============================= I think this is addressed by my explanation above of multiple body elements in each field list item? -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:29:31 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:29:31 -0400 Subject: [Doc-SIG] directives and reversability In-Reply-To: Message-ID: Garth T Kidd wrote on 2001-08-09 9:58 PM: > To minimise the impact on reversability, my current take is that pragma > directives (at minimum) have to be represented in the output as > directive tags, and -- if they hook the parser to extend what it can > output -- should contain elements describing what extended elements can > now be produced. ... > No, but we should make sure that at least the parser can figure out > which extension was responsible for the unknown element, and complain > appropriately when trying to re-generate the input. Something like that sounds right. Care to come up with example markup? -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Fri Aug 10 04:30:44 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 09 Aug 2001 23:30:44 -0400 Subject: [Doc-SIG] auto-numbered footnotes In-Reply-To: Message-ID: Garth T Kidd wrote on 2001-08-09 9:58 PM: > * Let's say we want to use non-URI link targets as automatically > numbered footnotes, which I think is pretty nifty. Explicitly > named footnotes are still perfect_ for citing references, but > authors are freed from the tyranny of having to avoid footnote > number collisions. > > .. perfect: Perfection is great! And, since this link target > doesn't have anything resembling a URI in it, it's an auto > numbered footnote, right? Wrong! Too ambiguous. For auto-numbered footnotes, how about something like:: Auto-numbered footnote ref: []_. .. _[] Here's the footnote. Of course, the order is all-important here. However, it's impossible to refer to this footnote a second time. Or we could define a new syntax variant:: Auto-numbered footnote ref: [#name]_. .. _[#name] Here's the footnote. The order is no longer important. And, we can refer to this footnote as ``name_``. The second idea seems to work well. > * Therefore, we need a way for applications to specify a resolver > function to the parser. I *don't* think so. [on indirect links] > That would > let me refer to a section called ``Extremely Long Heading`` > as ``ELH_`` as follows:: > > See ELH_ for more details. > > .. _ELH: `Extremely Long Heading`_ I've thought these over, and I don't see them happening. If you need another way to refer to a part of the current document, just put in another target:: .. _ELH: Extremely Long Heading ====================== ... If it's to an external link, just duplicate the target:: .. _link name number 1: http://somehost.somecompany.com .. _link1: http://somehost.somecompany.com > + I'm still going on about indirect links, even though I suspect > that they're already in the spec. I lack the time right now to > wade through and check. Bueller? Suspicions incorrect. Don't be like Ferris; do your homework! -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From garth@deadlybloodyserious.com Fri Aug 10 05:11:55 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 14:11:55 +1000 Subject: [Doc-SIG] auto-numbered footnotes In-Reply-To: Message-ID: > Auto-numbered footnote ref: []_. > > .. _[] Here's the footnote. Of course, the order is all-important > here. However, it's impossible to refer to this footnote a > second time. You're an evil genius. I love it. > Or we could define a new syntax variant:: > > Auto-numbered footnote ref: [#name]_. > > .. _[#name] Here's the footnote. The order is no longer > important. And, we can refer to this footnote as > ``name_``. > > The second idea seems to work well. I like that one, too. Can we have both? ``[]_`` matching the very next ``_[]`` footnote is just too lovely to pass up. I suspect the internal identifiers for anonymous footnotes should be something like [#auto.NNN] and should be spit out by reST when recreating its input. Reasoning: the reST version of the document *as originally written* is going to be very difficult to read if the author uses lots of anonymous footnotes. If the recreated version of the input contains identifiers, however, a subsequent editor can move the footnotes to somewhere more sensible, like just before the next heading. Indeed, the application might automatically move them there. >> * Therefore, we need a way for applications to specify a resolver >> function to the parser. > > I *don't* think so. Now that you've demonstrated a much better way of handling anonymous footnotes, I completely agree -- we can go back to the parser completely leaving link resolution up to the application. I feel a lot better now. :) > [on indirect links] > > I've thought these over, and I don't see them happening. If > you need another way to refer to a part of the current document, > just put in another target. Fair enough. Hey, it's not like the parser has to do the heavy lifting, in any case. If some madman writes it into their application, they do. I probably won't be that madman, though, because it strikes me as *much* less effort to put in another target than to write the code to walk the entire result tree and collapse indirect links. :) > Don't be like Ferris; do your homework! Naaah. Shoot first, ask questions later. :) Regards, Garth. From garth@deadlybloodyserious.com Fri Aug 10 05:24:52 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 14:24:52 +1000 Subject: [Doc-SIG] Hyperlink targets and roles In-Reply-To: Message-ID: > Name: maybe "baselink" or "basedoc" or "baseref"? ``baseref`` is good, yeah. > I like the idea of putting the base document reference in the target > rather than in the text as a prefix to the hyperlink itself. ... > However, there is a problem with the above approach: > 'dictionary:' looks just like a URI scheme ('http:', 'mailto:', > etc.). True. I don't think the WikiTeemingHordes will be much worried about the camelcased WikiName of an InterWiki target potentially clashing with the name of a new URI scheme, so I suspect they'll not be too concerned about using InterWiki targets as "phantom" URI schemes. That's their application, though, and their problem []_. .. _[] If we insist upon lowercase scheme names, that might actually help them. Any InterWiki link will fail the "is this a URI?" test and sit there unresolved waiting for the Wiki to save it. More generic document handlers won't support such behaviour. Moreover, I can't see WikiUsers employing baseref -- they have their own mechanism for that kind of thing -- so I'm comfortable with your second alternate syntax for baseref:: > .. _fnords: dictionary fnord > > fnord > > > .. Hmmm. If we adopt backslashed line extension, we should trim > > whitespace up to the indentation level of the block. > > We don't need backslashed line extension. ... for link targets (I now find out :), or for any directive which takes a single URI as its only argument, but what about directives supporting spaces in their arguments? :: .. indexterms:: extension, line extension, extension of lines, and it just occurred to me that you're about to say that it's up to any directive to parse its own block and if that directive wants line extension it can bloody well do it itself. :) > I've implemented hyperlink targets to collect all text, strip them > of whitespace left & right, and concatenate. That's very nifty, by the way. > > role:`thing` > > I'm coming to prefer the former (role outside of the quotes). Good. :) > I see the need for explicit roles with such concepts as index > entries and inline graphics. How do you see inline graphics handled? inlinepicture:`externalsite.gif`? Regards, Garth. From dgoodger@bigfoot.com Fri Aug 10 05:28:37 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Fri, 10 Aug 2001 00:28:37 -0400 Subject: [Doc-SIG] auto-numbered footnotes In-Reply-To: Message-ID: I wrote: > For auto-numbered footnotes, how about something like:: > > Auto-numbered footnote ref: []_. > > .. _[] Here's the footnote. Of course, the order is all-important > here. However, it's impossible to refer to this footnote a > second time. For consistency's sake, I think that anonymous auto-numbered footnotes should be defined with ``.. _[#]`` and referred to as ``[#]_``. No matter how pretty the empty version is, the number sign mnemonic is too useful. /David g'night! From dgoodger@bigfoot.com Fri Aug 10 05:34:50 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Fri, 10 Aug 2001 00:34:50 -0400 Subject: [Doc-SIG] Hyperlink targets and roles In-Reply-To: Message-ID: Garth T Kidd wrote on 2001-08-10 12:24 AM: > How do you see inline graphics handled? > inlinepicture:`externalsite.gif`? graphic:`logo.png` /David zzz... From garth@deadlybloodyserious.com Fri Aug 10 05:52:36 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 14:52:36 +1000 Subject: [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: > > > > ``.. section::``, anyone? > You realize that section headers produce sections, which can be nested > indefinitely. D'oh! You're absolutely right. I forgot. > I'm pretty certain the parser doesn't need to know about any of this. True. Regards, Garth. From garth@deadlybloodyserious.com Fri Aug 10 05:52:38 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 14:52:38 +1000 Subject: [Doc-SIG] RE: text in hyperlink targets In-Reply-To: Message-ID: > > .. _OOB: Out of the box, ie without any directives loaded. Now, how > > on Earth do we render this link target, or any other non-URI link > > target that hasn't been rescued by some directive? I'm using it > > as a footnote. Hmmm. > > Perhaps I'll put in a check for spaces inside text in hyperlink > targets. URIs may not contain spaces. The parser can generate a > warning, including the entire "target" as a literal block. Excellent idea, and very polite of the parser. "You were probably trying to specify a footnote, but forgot your square brackets and mistakenly included a colon..." Regards, Garth. From garth@deadlybloodyserious.com Fri Aug 10 06:13:08 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 15:13:08 +1000 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: >> For pragma directives, if the directive is not recognised, I think >> that the directive *itself* should be emitted as a node, >> and that it should be flagged as an Error. That gives the user some >> hint of why their document looks odd (!). > > Yes, this is the plan. How do we dodge the reversability problem for that one? Here's a literal block: $ ./quicktest.py :: This is a literal block. => This is a literal block. So, to *reverse* that, we spit out the literal block delimiter at the current indentation level (0), indent, and then spit out the contents of the literal block. Cool. Now let's try an unrecognised directive: $ ./quicktest.py .. disguised:: => If we spit the directive itself out in a literal block if it's not recognised, we'd get something like: .. disguised:: ... which would reverse to ``::``, a blank line, and the directive as some text in a literal block. Oops. I think we're better off spitting out the directive tag with some kind of "unrecognised" attribute, its argument as the argument attribute, and its *contents* as a literal block. Regards, Garth. From garth@deadlybloodyserious.com Fri Aug 10 06:22:07 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 15:22:07 +1000 Subject: [Doc-SIG] Comments on the reST notes In-Reply-To: Message-ID: > I don't know how Wikis work. When somebody posts a new message I would > expect it to say "Error in message: please correct" until there are no > errors, then show the processed version to the user and allow them to > post or edit their message. Currently, most Wikis just show you your broken output and let you go back and edit it if you feel like it and have the time. If not, someone else will probably fix it for you. More friendly is to point out the errors, not just show you your broken output. Many people won't look for a problem unless there's red on the page. One step tighter would be to commit the broken input, but also take you straight back to a page with the warnings and the editor pane so you can fix it. If you (say) shut down your browser, no problems, your changes are there and someone can come back and fix it. The key difference is that you don't have to expend any extra effort to get back to the editor, thus making it more likely that you'll fix the problem. One more step tighter is to take the user back to the editor *without* committing the changes, but supply a button marked "commit anyway and let someone else clean it up later" just in case they're in a hurry. If you have to press a button for people to see your changes, you may as well spend the time to fix the typo, right? :) Finally; detail oriented sites would change the "commit anyway" button to something like "leave in edit queue" -- the user can come back and fix the problems later, or anyone else with queue permissions can, but users won't see any changes until the syntax is valid. My personal favourite is the lattermost, but it only makes sense for an environment with concepts of "user", "queue", and "permissions". None of the three are considered particularly Wiki, but that's a different argument. Regards, Garth. From garth@deadlybloodyserious.com Fri Aug 10 06:22:13 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Fri, 10 Aug 2001 15:22:13 +1000 Subject: [Doc-SIG] auto-numbered footnotes In-Reply-To: Message-ID: > For consistency's sake, I think that anonymous auto-numbered > footnotes should be defined with ``.. _[#]`` and referred to > as ``[#]_``. > > No matter how pretty the empty version is, the number sign mnemonic > is too useful. +1 From dgoodger@bigfoot.com Fri Aug 10 22:52:07 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Fri, 10 Aug 2001 17:52:07 -0400 Subject: [Doc-SIG] directives and reversiblity In-Reply-To: Message-ID: [Tony] >>> For pragma directives, if the directive is not recognised, I think >>> that the directive *itself* should be emitted as a node, >>> and that it should be flagged as an Error. That gives the user some >>> hint of why their document looks odd (!). [David] >> Yes, this is the plan. [Garth] > I think we're better off spitting out the directive tag with some kind > of "unrecognised" attribute, its argument as the argument attribute, and > its *contents* as a literal block. When I said, "this is the plan", this was what I meant. It's the default case, what the parser does now. To clarify:: .. a_directive:: arguments block By default, after parsing the above reStructuredText becomes:: block An actually *implemented* directive may do something else, but it should still be reversible. When we devise a directive that isn't inherently reversible, we'll revisit this issue. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Sun Aug 12 00:23:03 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Sat, 11 Aug 2001 19:23:03 -0400 Subject: [Doc-SIG] reStructuredText Field Lists: Deciding on Syntax In-Reply-To: Message-ID: I've added Tibs' suggestion of double-colon syntax for field lists, as alternative #6 in reStructuredText.txt: 6. Use double colons:: Author:: Me Version:: 1 Advantages: unambiguous, obvious? (*almost* RFC822-compliant), flexible, similar to syntax already used for literal blocks and directives. Disadvantage: no precedent, not quite RFC822-compliant, similar to syntax already used for literal blocks and directives. Choosing this as the best of the alternatives, I started working on the implementation, and realized that the similarity to literal block syntax may be more significant that I'd thought. In the simple case, it's no problem:: field name:: field body But for long field names or field bodies containing multiple body elements, I'd like to be able to start the field body on another line:: field name:: field body There is a problem if people try to put a blank line between the field name and body:: field name:: field body The "field body" above *is* a literal block. The choices are: 1. Use syntax alternative 6, but accept the limitation that there may not be a blank line between a field name and field body. 2. Use a different syntax for field lists, one that avoids the similarities with literal blocks. Syntax alternative #5 (``:field name: body``) would be my next choice. It has the advantage of being visually distinctive up-front, bracketing the field name. By beginning with a colon, the field name also looks more like a list item marker, making a field list look like a list. Hmm. I'm starting to reconsider my choice of alternative #6 in favour of alternative #5. Opinions? -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Sun Aug 12 00:23:16 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Sat, 11 Aug 2001 19:23:16 -0400 Subject: [Doc-SIG] David's Idea for Lazy Indentation Message-ID: [I've added this to the restructuredtext/spec/rst-notes.txt file, in the "Or Not To Do?" section. Thoughts?] Consider a paragraph in a word processor. It is a single logical line of text which ends with a newline, soft-wrapped arbitrarily at the right edge of the page or screen. We can think of a plaintext paragraph in the same way, as a single logical line of text, ending with two newlines (a blank line) instead of one, and which may contain arbitrary line breaks (newlines) where it was accidentally hard-wrapped by an application. We can compensate for the accidental hard-wrapping by "unwrapping" every unindented second and subsequent line. The indentation of the first line of a paragraph or list item would determine the indentation for the entire element. Blank lines would be required between list items when using lazy indentation. The following example shows the lazy indentation of multiple body elements:: - This is the first paragraph of the first list item. Here is the second paragraph of the first list item. - This is the first paragraph of the second list item. Here is the second paragraph of the second list item. A more complex example shows the limitations of lazy indentation:: - This is the first paragraph of the first list item. Next is a definition list item: Term Definition. The indentation of the term is required, as is the indentation of the definition's first line. When the definition extends to more than one line, lazy indentation may occur. (This is the second paragraph of the definition.) - This is the first paragraph of the second list item. - Here is the first paragraph of the first item of a nested list. So this paragraph would be outside of the nested list, but inside the second list item of the outer list. But this paragraph is not part of the list at all. And the ambiguity remains:: - Look at the hyphen at the beginning of the next line - is it a second list item marker, or a dash in the text? Similarly, we may want to refer to numbers inside enumerated lists: 1. How many socks in a pair? There are 2. How many pants in a pair? Exactly 1. Go figure. Literal blocks and block quotes would still require consistent indentation for all their lines. For block quotes, we might be able to get away with only requiring that the first line of each contained element be indented. For example:: Here's a paragraph. This is a paragraph inside a block quote. Second and subsequent lines need not be indented at all. - A bullet list inside the block quote. Second paragraph of the bullet list inside the block quote. Although feasible, this form of lazy indentation has problems. The document structure and hierarchy is not obvious from the indentation, making the source plaintext difficult to read. This will also make keeping track of the indentation while writing difficult and error-prone. However, these problems may be acceptable for Wikis and email mode, where we may be able to rely on less complex structure (few nested lists, for example). -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From garth@deadlybloodyserious.com Mon Aug 13 01:32:10 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Mon, 13 Aug 2001 10:32:10 +1000 Subject: [Doc-SIG] David's Idea for Lazy Indentation In-Reply-To: Message-ID: > Although feasible, this form of lazy indentation has problems. The > document structure and hierarchy is not obvious from the indentation, > making the source plaintext difficult to read. I *suspect* this will be less of a problem once the parser is reversable. It's not too hard a stretch to imagine an "edit parsed text, not original" button on a Wiki, for example. The moment maintaining appropriate indentation becomes harder than using an alternative editor and pasting back into the edit box, I suspect people will do so. I do that often enough with email. Regards, Garth. From garth@deadlybloodyserious.com Mon Aug 13 01:32:13 2001 From: garth@deadlybloodyserious.com (Garth T Kidd) Date: Mon, 13 Aug 2001 10:32:13 +1000 Subject: [Doc-SIG] reStructuredText Field Lists: Deciding on Syntax In-Reply-To: Message-ID: > Hmm. I'm starting to reconsider my choice of alternative #6 > in favour of alternative #5. > > Opinions? :Lists: From tony@lsl.co.uk Mon Aug 13 09:25:51 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 09:25:51 +0100 Subject: [Doc-SIG] Comments on the reST specification - comments In-Reply-To: Message-ID: <003401c123d1$8feb3ce0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > Tony J Ibbs (Tibs) wrote on 2001-08-08 5:59 AM: > > Just one note - *do* we need ``.. comment::`` if we are going to > > retain ``.. `` as *meaning* comments? > > Nope. You forget about ``.. comment::`` and I'll forget all about > ``.. hyperlink::`` and ``.. footnote::``. Deal? OK, it's a deal. (so, in retrospect, apologies for the (now closed and pinched off) loop in the conversation about ``.. comment`` - but I feel *I've* learnt something from it, so it wasn't wasted for me). > I've redefined explicit markup starts to be two periods followed by > whitespace, which includes a newline (end of line). Ditto for the > space after bullets & enumerators. Yes - I actually saw that in a later email message you'd sent to Garth, but figured I'd already mail-bombed the list too much to bother saying so. (by the way - do we prefer to reply *just* to the list, or is replying to all recipients explicitly considered desirable?) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 13 09:36:16 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 09:36:16 +0100 Subject: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes" In-Reply-To: Message-ID: <003501c123d3$04959cb0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > I don't see much difference between "command directives" and "pragma > directives"; command directives simply don't act on any data. > > The big difference I see is one of scope. A true pragma (global > directive?) will affect the entire parser session, whereas a local > directive only affects its text block. Ah - that's exactly the difference I was seeing. Although, of course, a pragma directive affects the input stream *from that point on* (it would be a big restriction to say all pragma directives must be globally effective. Perhaps we differ over whether such a different desrves a difference in terminology - it's not a very important thing to worry about. I just thought I was seeing some discinctions that having a "name" would help describe. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 13 09:42:51 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 09:42:51 +0100 Subject: [Doc-SIG] auto-numbered footnotes In-Reply-To: Message-ID: <003601c123d3$f048a990$f05aa8c0@lslp7o.int.lsl.co.uk> Garth T Kidd wrote, replying to David: > > For consistency's sake, I think that anonymous auto-numbered > > footnotes should be defined with ``.. _[#]`` and referred to > > as ``[#]_``. > > > > No matter how pretty the empty version is, the number sign mnemonic > > is too useful. > > +1 Gosh - things that happen over the weekend. I think this whole issue is gilding on the lilly, but it's pretty gilding, so +1 too. Did I emphasise again recently enough that I think that reST is a Good Thing? Won't stop me picking nits, or trying to understand things I don't understand, of course. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 13 09:44:37 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 09:44:37 +0100 Subject: [Doc-SIG] Comments on the "problems with structured text" In-Reply-To: Message-ID: <003701c123d4$2eedcd60$f05aa8c0@lslp7o.int.lsl.co.uk> > [on the Grand Unification Theory] > > Hmm - you haven't watched the Doc-SIG for as long as I have. > > I have read through much of the archives, though. This debate dates > back to 1996 on Doc-SIG. It may go back further, elsewhere. Sorry - my misphrasing - it's actually fairly obvious that you must have read the archives. The meaning I was (rather poorly) striving for was the (I suppose trivial) one that you hadn't had to suffer the emotional wear-and-tear over the years - this may, of course, be a Good Thing (cooler minds and all that). Tibs From tony@lsl.co.uk Mon Aug 13 09:55:46 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 09:55:46 +0100 Subject: [Doc-SIG] reStructuredText Field Lists: Deciding on Syntax In-Reply-To: Message-ID: <003801c123d5$bdfbda50$f05aa8c0@lslp7o.int.lsl.co.uk> Hmm - I had actually realised that the "missing blank line" problem existed (I think I mentioned it) - to me it wasn't a problem (well, maybe I'm in denial). But... David Goodger wrote: > The choices are: > > 1. Use syntax alternative 6, but accept the limitation that > there may not be a blank line between a field name and > field body. I could happily live with this myself, on tacky pragmatic grounds, since I like the look of this alternative more than that of the other. BUT my "standards head" says that it is rather confusing to allow the "::" to be overloaded like that, especially since one already has to remember varieties of "::" use (e.g., preceded by space, etc.). Of course, in this instance I don't want to *listen* to that head... > 2. Use a different syntax for field lists, one that avoids the > similarities with literal blocks. Syntax alternative #5 > (``:field name: body``) would be my next choice. It has the > advantage of being visually distinctive up-front, bracketing > the field name. By beginning with a colon, the field name > also looks more like a list item marker, making a field list > look like a list. My initial response to this is, as ever, yuck. On the other hand, I find it difficult to "look at it for the first time" - I'm too entrenched in what I want to type from older arguments. If this will allow us to have field lists that contain content - for instance:: :Some-name: And more than one... ...paragraph. then I'd be willing to vote +0 on it. I think I'd have to vote -0 (argh - don't like doing that) on option 6. I would, however, then vote that email and PEP modes have a specialisation for the first block, which allows one to do "traditional" email headers, without requiring the leading colons. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 13 10:16:37 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 10:16:37 +0100 Subject: [Doc-SIG] Slightly newer version of quickref In-Reply-To: Message-ID: <003901c123d8$a7552dd0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote on 2001-08-08 4:05 AM: > > I *did* have time to make the next iteration of the quick > > reference... > > > > http://www.tibsnjoan.co.uk/reST/quick_reST.html > > Although it's a great resource, I think it has grown too > large to be usable as a quick reference. Actually, I agree. I'm sort of iterating towards my final goal, which probably is more like: > a quickref page (like the first version, just > the yellow bits) with links to a separate details page > (full explanations)? but of course it's easier to produce the second first (so to speak). One problem, though, is that tables are hard to show in the yellow/parallel format. On the other hand, since one can do just about anything one wants with tables, maybe a simple example would suffice... > How about adding links to the project home page? Easily done at the end. > Better yet, how about adding the quickref *to* the project? Hmm - unless that's as easily done as my current FTPing of a new version to my website, it's not an obvious thing for me to do... It's probably easier for you to tell me if that's how it works than for me to try to find out! > Once the parser is done, we can *do* the quickref with > reStructuredText. Probably not, as one would want closer control over the layout than reST gives (although a version in reST is not a bad idea in itself). And no, I *don't* want to add that much cruft to reST just so I can produce a "pretty" HTML page! > Bugs: Thanks for these - I'll get on them. > - "Inline Markup", end of blue section:: > > For instance, consider ``this example, which > has lots of spaces``. > > That won't work. The second line is indented relative to the first, > and will currently be recognized as a definition list. The unclosed > backquotes will generate a warning (level 1). > > The sentence ending the preceding paragraph doesn't make sense in > this context: "Spaces at the *start* of a line are counted relative > to the left margin of the current paragraph." Perhaps the same bug. Hmm - yes, I see what you mean. Humph. > - "Links". This is still wrong:: > > Internal crossreferences, like example_. > > .. _example: This is an example > crossreference target. > > The target should be:: > > .. _example: > > This is an example cross reference target. Ah - fundamental misunderstanding on my part. I think I get it now. I was seeing there as being two sorts of hyperlink target:: .. _fred: A "footnote" like one .. _bill: And a specialisation of that which marked a piece of text. - don't know why. I'm glad to have gotten that one sorted out. > - "Definition lists". Still waiting for an answer on: > > The spec (and the parser) require blank lines between definition > list items. This requirement could be relaxed, as it has been > for other lists. What do you think? > > Your example has no blank line between definition list items. Ah - that's either a mistake, or because I was trying to see what it looked like (and maybe argue for it). At this moment, I can't remember which... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 13 10:19:13 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 10:19:13 +0100 Subject: [Doc-SIG] Re: reST: standalone hyperlinks In-Reply-To: Message-ID: <003a01c123d9$048eb020$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > I've expanded the overview a bit in reStructuredText.txt: [..elided..] > I don't think the spec needs to be any more detailed than > this. Agreed. But I'm quite impressed if you're going to recognise any legitimate (by those specs) URI - glad you're doing the code and not me. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 13 10:28:35 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 10:28:35 +0100 Subject: [Doc-SIG] Field lists and label blocks In-Reply-To: Message-ID: <003b01c123da$5385b9c0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > > All of the examples show the as being confined to the rest of > > the line - that is, no line breaks allowed. > > That's an accident. I actually intend:: > > : > > The consists of > one or more body elements> > > Including nested field lists! > > One-liners are merely a degenerate form. Even in email RFC822 headers, > you often end up with multi-line (but single "paragraph") bodies. Aargh - I think I must have continually kept reading past the text "The field body ay contain multiple body elements." My apologies. > The interpretation of field lists will not be done by the parser > anyhow. It's the DPS itself, or an output formatter, or an > intermediate transformation component, that will do the > interpretation. Again, sorry - I keep forgetting this separation now exists. Old dogs and new tricks, to some extent. > (BTW, the introduction of the concept of "modes" has helped me to gel > some ideas I had about the DPS framework. We need mode-specific > modules as middleware between the input parser and output formatters.) Hmm. Sometimes a mode is going to change the parse a bit, though, surely? Anyway, I think my issues with field lists (or whatever you choose to call them) may now be called resolved. Thanks. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 13 10:45:10 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 10:45:10 +0100 Subject: [Doc-SIG] Re: reST: Option lists and descriptive lists In-Reply-To: Message-ID: <003c01c123dc$a479d670$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > Rather than trying to shoehorn option lists into > definition/descriptive lists, I'm trying to provide for them in a > natural way. Lists of command-line options, such as found in man pages > and '--help' usage output, are not the same as definition lists. Well, we obviously differ. But, on the other hand, *you* are the one with final decisions, and I'm the one who has to come up with a convincing argument. > > At which point we need to stand back and think again. And the way to > > do *that* is to take lots of examples and to look for commonality. > > That's what I have done. I've looked at a lot of man pages and > '--help' usage output, and I see option lists as described in the > spec. I'm still uncomfortable with the Unix specificity of that. So, trying to worry in a more specific manner, you currently propose:: -a Output all -b Output both (this description is quite long) Would you also allow:: /a Output all /b Output both (this description is quite long) which is more natural on Windows and VMS? (if I'm producing software that *will* only be used on Windows, it doesn't make sense to stick with Unix conventions for switches). On my worriting about descriptive lists: > So come up with a better, unambiguous alternative, and fame & fortune > will be yours. (Well, maybe not fortune. Not much fame either, I'm > afraid. A bit of egoboo is all we open-sourcers can expect.) Heh, don't denigrate egoboo - people run N-thousand people conventions just for the egoboo of it! > The option list construct is convenient and unambiguous, > and (AFAICT, not having implemented it yet) ought to > work well. Why all the resistance? I wish I could explain - if I could it would probably encapsulate the solution(!) - but it undoubtedly stems back to my discomfort with descriptive lists, and *that* ties back to the "naturalness" of Guido's example. Hmm - maybe *I'm* overgeneralising - would we accept a Python extension that allowed me to do, for instance:: :Arguments: `arg1` -- not a very informative example. `arg2` -- and it is *very* restricted in what goes at the front - it *must* be a Python thingy in quotes. since it is the arguments case that particularly bugs me? Is *that* worth it? (maybe not). On the other hand, given three choices: 1. Get a working reST/DPS with descriptive lists as they are now. 2. Get a working reST/DPS without descriptive lists at all. 3. Continue arguing about this forever. option 3 is the only one I *wouldn't* choose. Tibs (colour me happy except for some minor polka dots that I can ignore if I really have to) -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Mon Aug 13 14:11:42 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 13 Aug 2001 14:11:42 +0100 Subject: [Doc-SIG] Version 0.3 of quickref In-Reply-To: <003901c123d8$a7552dd0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: <003d01c123f9$7ee12e00$f05aa8c0@lslp7o.int.lsl.co.uk> I've just uploaded version 0.3 of the "quick" reference: http://www.tibsnjoan.co.uk/reST/quick_reST.html It's still not terribly "quick", but I think it is now more of a minimal reference. I've included my understanding of the additional hyperlink/footnote capabilities, as discussed recently. Two things - the reason the earlier version didn't just use the reST text for inline markup description was that I was working from an earlier version, which wasn't as good (it now does, albeit slightly reformatted). Also, David said: > The spec (and the parser) require blank lines between > definition list items. This requirement could be relaxed, > as it has been for other lists. What do you think? For the sake of "fewer cases to remember", I think that it should be allowed to leave out blank lines between definition list items. I've deliberately made the quick ref silent on this matter... Let's hope I'm getting the hang of this now, and thus have fewer bugs in the spec! Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From klm@zope.com Mon Aug 13 17:45:35 2001 From: klm@zope.com (Ken Manheimer) Date: Mon, 13 Aug 2001 12:45:35 -0400 (EDT) Subject: [Doc-SIG] Version 0.3 of quickref In-Reply-To: Message-ID: > I've just uploaded version 0.3 of the "quick" reference: > > http://www.tibsnjoan.co.uk/reST/quick_reST.html > > It's still not terribly "quick", but I think it is now more of a minimal > reference. I've included my understanding of the additional > hyperlink/footnote capabilities, as discussed recently. As a lurker, i was yearning for an overview with substance. This is *just* what i was seeking - thanks tony! Excellent! Some questions, requests, etc... - In the _Indirect hyperlinks_ section - what is meant by "fold-in" and "call-out" forms? Maybe that warrants a note below that box. - _Titles_ section - it may be worth indicating how the hierarchical order of the titles is inferred - not sure how to say it succinctly, though, maybe someone has done so in the discussions... - I hope this isn't out of bounds, but i find that yellow painful - would you consider a more understated yellow-ish, eg "#ffffcc"? - I think it would be awfully nice to have some kind of link from each of the items in the cheat-sheet to more thorough documentation for that topic. Just a thought, for future documentation... Thanks! Ken From dgoodger@bigfoot.com Tue Aug 14 04:32:19 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 13 Aug 2001 23:32:19 -0400 Subject: [Doc-SIG] reStructuredText Field Lists: Deciding on Syntax In-Reply-To: <003801c123d5$bdfbda50$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-13 04:55: > David Goodger wrote: > > The choices are: > > > > 1. Use syntax alternative 6, but accept the limitation that > > there may not be a blank line between a field name and > > field body. > > > > 2. Use a different syntax for field lists, one that avoids the > > similarities with literal blocks. Syntax alternative #5 > > (``:field name: body``) would be my next choice. It has the > > advantage of being visually distinctive up-front, bracketing > > the field name. By beginning with a colon, the field name > > also looks more like a list item marker, making a field list > > look like a list. > > My initial response to this is, as ever, yuck. On the other hand, I > find it difficult to "look at it for the first time" - I'm too > entrenched in what I want to type from older arguments. I see from quick_reST.html 0.3 that you assumed the ':field-name:' syntax would win out. You assumed correctly. Over the weekend, I implemented field lists, option lists, and tables (temporarily, as literal blocks; a full implementation will be a Significant Effort). (Implementing option lists was a bit of a pain, because of a time-consuming red herring: I'd made a simple logic error but failed to track it down, thinking it was a regex problem instead. However, implementing field lists was a pleasure. I made some test cases, worked out the regex, put in the transition code for the first field [copied & modified from bullet lists], and made a new state for fields 2 and up. This all took about a half hour. Ran it. Worked, first time, no errors. "Cool!" I said, with a big grin on my face. Thank Guido for Python!) > I would, however, then vote that email and PEP modes have a > specialisation for the first block, which allows one to do > "traditional" email headers, without requiring the leading colons. Agreed. For this purpose, I'll include an 'rfc822' syntax in the parser, which is normally disabled but can be enabled by email & PEP modes. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 14 04:32:55 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 13 Aug 2001 23:32:55 -0400 Subject: [Doc-SIG] Slightly newer version of quickref In-Reply-To: <003901c123d8$a7552dd0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-13 05:16: > One problem, though, is that tables are hard to show in the > yellow/parallel format. On the other hand, since one can do just about > anything one wants with tables, maybe a simple example would > suffice... Your table example looks good. I agree with Ken, though: please tone down the yellow! > > Better yet, how about adding the quickref *to* the project? > > Hmm - unless that's as easily done as my current FTPing of a new > version to my website, it's not an obvious thing for me to do... > > It's probably easier for you to tell me if that's how it works than > for me to try to find out! Get yourself a SourceForge login (free), let me know what it is and I'll add you as a developer to the two projects. You can use CVS, SCP, or SFTP (*not* FTP, which isn't secure) to upload files. Or you can submit a patch, or email me the new file, or just let me know there's a new version and *I'll* add it to the project. That last one may be the easiest. Let me know if it's OK to add the quickref to the project. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 14 04:34:36 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 13 Aug 2001 23:34:36 -0400 Subject: [Doc-SIG] modes In-Reply-To: <003b01c123da$5385b9c0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-13 05:28: > > (BTW, the introduction of the concept of "modes" has helped me to > > gel some ideas I had about the DPS framework. We need > > mode-specific modules as middleware between the input parser and > > output formatters.) > > Hmm. Sometimes a mode is going to change the parse a bit, though, > surely? I'm thinking of "transformation mode" (xmode?) modules which reside as a new layer between the DPS and the parser & formatter. The mode knows how to interpret the parsed input, how to move stuff around in its own special way. It's the "business logic" part of the system. That way, the formatter can be a pure translation module, internal structure to TeX/*ML/whatever. The parser *will* need to be told something about what mode it's in: whether or not to use rfc822, lazy indentation. Have to think this through. Gotta update the diagram too. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 14 04:35:21 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 13 Aug 2001 23:35:21 -0400 Subject: [Doc-SIG] Re: reST: Option lists and descriptive lists In-Reply-To: <003c01c123dc$a479d670$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-13 05:45: > I'm still uncomfortable with the Unix specificity of that. ... > Would you also allow:: > > /a Output all > /b Output both (this description is > quite long) > > which is more natural on Windows and VMS? Hadn't thought of it, not being Windows-centric, but I don't see why not. I was aiming to support the syntax that getopt.py supports. Not that it matters, but is there a Python module supporting Windows-style "/" options? -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 14 04:33:06 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 13 Aug 2001 23:33:06 -0400 Subject: [Doc-SIG] Re: reST: standalone hyperlinks In-Reply-To: <003a01c123d9$048eb020$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-13 05:19: > But I'm quite impressed if you're going to recognise any legitimate > (by those specs) URI - glad you're doing the code and not me. Already implemented. Please test your bookmarks & let me know if any aren't recognized. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 14 04:36:08 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 13 Aug 2001 23:36:08 -0400 Subject: [Doc-SIG] Version 0.3 of quickref In-Reply-To: <003d01c123f9$7ee12e00$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-13 09:11: > I've just uploaded version 0.3 of the "quick" reference: > > http://www.tibsnjoan.co.uk/reST/quick_reST.html ... > Let's hope I'm getting the hang of this now, and thus have fewer > bugs in the spec! The spec is bigger so it's easier for bugs to crawl in. Let's squash 'em: - "Inline markup", last row of the table. I'd change ``\* and \` but \\`` to something like ``\*escape* \`with` "\\"``, whose typical result would be ``*escape* `with` "\"`` (note: just one backslash after parsing). A lone "*" or "`" won't count as markup, so escaping isn't necessary. I'll add "escaped space may mean non-breaking space in the future" to the spec. - "Implicit crossreferences": Perhaps "Implicit (crossreference|hyperlink) targets"? I'd add footnotes as well; footnote labels become implicit targets. Oh, this is what you have in "proposed footnote tricks", the first one. I'd either move it or mention it here. - "Proposed footnote tricks": - First row. Footnote labels can't have any whitespace, so this won't work:: Given a footnote [like this]_, one can also refer to it `like this`_. Should change to ``[like_this]_`` or something. - Second row. The formatting is funny on the plaintext side:: They may be assigned 'counters', for instance, [#a], [#b] - Rather than 'counters', I'd call these 'reference labels' or something. The autonumbered footnotes would *not* contain the label (you should have [1] [2] [3] ... [6], not [a1] [b1] etc.). I'll write this into the spec. - You have the plaintext sentences broken in two, with footnotes in-between, but somehow the paragraphs get joined up under "Typical result". Magic? Note that auto-numbered footnotes & references won't have to be in lock-step, just in the same relative order:: [#]_ is first, [#]_ is second. .. _[#] first .. _[#] second - "Directives": There's not going to be a "comment" directive. Perhaps a section on comments? Include that an empty comment does *not* gobble up subsequent indented blocks. (I'll write this into the spec, so you may want to wait until that's done to see the model text.) - "Field lists": The two authors would become a single paragraph:: :Authors: Guido van Rossum Tim Peters Either add a comma after GvR, make them into a two-item bullet list, or put a blank line between for two paragraphs. - There's a hyphen missing from the top border of the table. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 14 04:36:21 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Mon, 13 Aug 2001 23:36:21 -0400 Subject: [Doc-SIG] definition lists & blank lines In-Reply-To: <003d01c123f9$7ee12e00$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: > Also, David said: > > The spec (and the parser) require blank lines between definition > > list items. This requirement could be relaxed, as it has been for > > other lists. What do you think? [Tony] > For the sake of "fewer cases to remember", I think that it should be > allowed to leave out blank lines between definition list items. Agreed. Will make the changes to spec & parser. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Tue Aug 14 05:15:53 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 14 Aug 2001 00:15:53 -0400 Subject: [Doc-SIG] definition lists & blank lines In-Reply-To: <003d01c123f9$7ee12e00$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: > Also, David said: > > The spec (and the parser) require blank lines between definition > > list items. This requirement could be relaxed, as it has been for > > other lists. What do you think? [Tony] > For the sake of "fewer cases to remember", I think that it should be > allowed to leave out blank lines between definition list items. Agreed. Will make the changes to spec & parser. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From tony@lsl.co.uk Tue Aug 14 09:02:16 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 14 Aug 2001 09:02:16 +0100 Subject: [Doc-SIG] reStructuredText Field Lists: Deciding on Syntax In-Reply-To: Message-ID: <004501c12497$6ed2e0a0$f05aa8c0@lslp7o.int.lsl.co.uk> > I see from quick_reST.html 0.3 that you assumed the ':field-name:' > syntax would win out. You assumed correctly. Yes, well, it's not only from the Python arena that I've learnt about the benefits of BDFL-nature and the benefits of compromise (and yes, I do believe those go together). > Over the weekend, I > implemented field lists, option lists, and tables (temporarily, as > literal blocks; a full implementation will be a Significant Effort). Gosh - things move one apace. > (Implementing option lists was a bit of a pain, because of a > time-consuming red herring: I'd made a simple logic error but failed > to track it down, thinking it was a regex problem instead. Aagh - been there, done that. Sometimes it would be useful to have the canonical person to look over one's shoulder when doing work like this as well... > "Cool!" I said, with a big grin on my face. Thank Guido for > Python!) And I know *that* feeling as well! Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Tue Aug 14 09:14:43 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 14 Aug 2001 09:14:43 +0100 Subject: [Doc-SIG] Slightly newer version of quickref In-Reply-To: Message-ID: <004601c12499$2c6b4bb0$f05aa8c0@lslp7o.int.lsl.co.uk> Ken Manheimer wrote: > As a lurker, i was yearning for an overview with substance. All egoboo greatfully accepted - but David is still finding bugs in it, so it's not there yet! (for me, the main benefit has actually been that at least one gaping (and stupid) misconception I had has been fixed). > - In the _Indirect hyperlinks_ section - what is meant by > "fold-in" and "call-out" forms? Maybe that warrants > a note below that box. OK - I'll add a note. They're terms David and I came up with (one each). Fold-in style is how one would expect HTML to work - one presses on the link and goes directly to the location, and the "footnote" is not visible. Call-out is how a paper document would work - the links need to be cast as *actual* footnotes. The examples I give of this in action are fold-in: http://homepage.ntlworld.com/tibsnjoan/further2.html call-out: http://homepage.ntlworld.com/tibsnjoan/further3.html These two documents could (essentially) have been written in reST and produced by two different runs of the processor. > - _Titles_ section - it may be worth indicating how the > hierarchical order of the titles is inferred - not > sure how to say it succinctly, though I *think* this is best left to the main document - partly because for *many* purposes of reST use one won't need titles (heh, I'm a docstring person), and partly because it *is* difficult to explain quickly. I see this as a memory jogger once one has already learnt (the basics of) reST, so fundamental things like titles can be left out. > - I hope this isn't out of bounds, but i find that > yellow painful - would you consider a more understated > yellow-ish, eg "#ffffcc"? And David agrees! (actually, so do I) - but it isn't intended as a permanent colour choice (although I shall try yours). The blue started out something else as well, until I "stole" Python blue again. > - I think it would be awfully nice to have some kind of > link from each of the items in the cheat-sheet to more > thorough documentation for that topic. David had already asked for a general link to the main document(s). I like the idea of "internal" links to the main document - but I guess it will have to wait until we have an HTML version to link to... David Goodger wrote: > Get yourself a SourceForge login (free), Aha - done. > let me know what it is heh - I was lucky enough to get "tibs" - that's really neat. Just waiting for the confirmation email... > I'll add you as a developer to the two projects. Ok - serious egoboo (well, a little bit). > You can use CVS, SCP, or SFTP (*not* FTP, which isn't secure) > to upload files. Right. Well, I've got scp here at work, and since I run Debian at home I can't imagine there's a problem there. > Let me know if it's OK to add the quickref to the project. Yes, please do. I'll *try* to update it a bit later in the day (if only to tone down the yellow!) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Tue Aug 14 09:18:47 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 14 Aug 2001 09:18:47 +0100 Subject: [Doc-SIG] Re: reST: Option lists and descriptive lists In-Reply-To: Message-ID: <004701c12499$bddae4c0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > Hadn't thought of it, not being Windows-centric, but I don't see why > not. I was aiming to support the syntax that getopt.py supports. Not > that it matters, but is there a Python module supporting Windows-style > "/" options? I don't know - personally I don't care much, since I rarely use complex enough command lines to bother with an "official" mode, and I've never particularly like any of the presupplied ones anyway (but then, that's my VMS background showing again). Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From Juergen Hermann" Hi! >From quickrest: \* and \` but \\ * and ` but \\ Escaped space (\ ) may, in future, mean non-breaking space. OK, so how do I get a single backslash followed by an asterisk, in the output?! Ciao, J=FCrgen -- J=FCrgen Hermann, Developer (jhe@webde-ag.de) WEB.DE AG, http://webde-ag.de/ From tony@lsl.co.uk Tue Aug 14 11:10:46 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 14 Aug 2001 11:10:46 +0100 Subject: [Doc-SIG] Not escaping the escape leaves no escape ;) In-Reply-To: Message-ID: <004901c124a9$62b55b10$f05aa8c0@lslp7o.int.lsl.co.uk> Juergen Hermann wrote: > OK, so how do I get a single backslash followed by an > asterisk, in the output?! Well, my first guess would be ``\\*`` - but let's see what David says it *actually* is, to see how good my guessing is... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Tue Aug 14 11:12:18 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 14 Aug 2001 11:12:18 +0100 Subject: [Doc-SIG] Version 0.4 of reST quick guide Message-ID: <004a01c124a9$99657280$f05aa8c0@lslp7o.int.lsl.co.uk> As it says, version 0.4 of the quick ref is now at http://www.tibsnjoan.co.uk/reST/quick_reST.html This should be a lot closer to being correct. David, feel free to put this into the CVS tree if you wish. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Tue Aug 14 11:20:07 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 14 Aug 2001 11:20:07 +0100 Subject: [Doc-SIG] Not escaping the escape leaves no escape ;) In-Reply-To: <004901c124a9$62b55b10$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: <004c01c124aa$b0db0af0$f05aa8c0@lslp7o.int.lsl.co.uk> > Well, my first guess would be ``\\*`` Aaargh - no, I *meant* ``\\\*`` - as in:: This text contains \\\*, which should be a backslash followed by an asterisk. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From jhe@webde-ag.de Tue Aug 14 11:31:19 2001 From: jhe@webde-ag.de (=?iso-8859-1?Q?J=FCrgen_Hermann?=) Date: Tue, 14 Aug 2001 12:31:19 +0200 Subject: [Doc-SIG] Not escaping the escape leaves no escape ;) Message-ID: <82C891B6DD60D411A6F200508BC5D6030340D274@exchange1.cinetic.de> > > Well, my first guess would be ``\\*`` >=20 > Aaargh - no, I *meant* ``\\\*`` - as in:: >=20 > This text contains \\\*, which should be > a backslash followed by an asterisk. No, your first guess was right. Since '\\' is not an escape sequence, = the lexer would return '\', with '\*' remaining. And '\*' is a single = asterisk. So the only problem remaining is that NOONE used to "normal" escaping = will be able to grok this intuitively, which both of us just proved very = nicely. ;) Ciao, J=FCrgen -- J=FCrgen Hermann, Developer (jhe@webde-ag.de) WEB.DE AG, http://webde-ag.de/ From Paul.Moore@atosorigin.com Tue Aug 14 11:44:19 2001 From: Paul.Moore@atosorigin.com (Moore, Paul) Date: Tue, 14 Aug 2001 11:44:19 +0100 Subject: [Doc-SIG] Re: David's Idea for Lazy Indentation Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5AF6E@UKRUX002.rundc.uk.origin-it.com> > And the ambiguity remains:: > - Look at the hyphen at the beginning of the next line > - is it a second list item marker, or a dash in the text? > > Similarly, we may want to refer to numbers inside enumerated > lists: > > 1. How many socks in a pair? There are > 2. How many pants in a pair? Exactly > 1. Go figure. Excuse my butting in - I'm not a member of the doc-sig, but I noticed this while browsing the web archives. Surely this is a simple case of "don't do this"? My understanding is that "structured text" (whatever form) should be something that can be automatically translated into other forms (TeX, HTML, PDF, whatever) but which is (as well as possible) readable in plain form. In which case, your two examples are *only* "readable" as lists. So define the rules to state that: 1. A line starting with the list marker (hyphen, or whatever) is *always* a new item. If you don't want that, change the line break, as it wouldn't be readable as plain text anyway. 2. A line in an enumerated list which starts with a number is *always* a new item. If you don't want that, change the line break, as it wouldn't be readable as plain text anyway. Paul. PS As a check, did my enumerated list above work as (re-)structured text? I haven't looked at the rules (other than a brief "skim" which confirmed that I like the general feel, but this is how I'd write enumerated lists by default, so it would be nice if it was recognised as such by the parser... From dgoodger@bigfoot.com Tue Aug 14 13:23:36 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 14 Aug 2001 08:23:36 -0400 Subject: [Doc-SIG] Not escaping the escape leaves no escape ;) In-Reply-To: <82C891B6DD60D411A6F200508BC5D6030340D274@exchange1.cinetic.de> Message-ID: [Tony] >>> Well, my first guess would be ``\\*`` [Tony] >> Aaargh - no, I *meant* ``\\\*`` - as in:: >>=20 >> This text contains \\\*, which should be >> a backslash followed by an asterisk. [J=FCrgen] > No, your first guess was right. Since '\\' is not an escape sequence, the > lexer would return '\', with '\*' remaining. And '\*' is a single asteris= k. > So the only problem remaining is that NOONE used to "normal" escaping wil= l > be able to grok this intuitively, which both of us just proved very nicel= y. > ;) I don't know about proof, but there's some misconception going on here. A single backslash always escapes the next character [1]_. When you use backslash-escapes, the first backslash *always* disappears. If there are multiple backslashes in a row, the first escapes the second, then we start over. So:: "\\" -> "\" "\\\*" -> "\*" "\\\ " -> "\ " (in future, this may become "\ ") .. _[1] The only exception to the escaping rules is inside literal blocks and inline literals, where the backslashes have no effect. Now, the following is a bit tricky, not because of the escaping rules, but because of the inline markup rules:: " * " -> " * " " (*) " -> " (*) " " 2*3 " -> " 2*3 " " *, ...* " -> " , ... " " \*, ...* " -> " *, ...* " " *, ... " -> " *, ... ", followed by a no end-string for emphasis In other words, to get an asterisk, either escape it, or make sure there's whitespace after it. The inline markup rules are intentionally tricky, to allow 90% of legitimat= e uses of '*' and '`' *without* resorting to backslashes. For 9 of the remaining 10%, use inline literals or literal blocks:: "``\*``" -> "\*" (possibly in another font or quoted) Only those who understand the escaping and inline markup rules may do the remaining 1% of cases. ;-) --=20 David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From jhe@webde-ag.de Tue Aug 14 13:31:22 2001 From: jhe@webde-ag.de (=?iso-8859-1?Q?J=FCrgen_Hermann?=) Date: Tue, 14 Aug 2001 14:31:22 +0200 Subject: [Doc-SIG] Not escaping the escape leaves no escape ;) Message-ID: <82C891B6DD60D411A6F200508BC5D6030340D275@exchange1.cinetic.de> > If there are > multiple backslashes in a row, the first escapes the second,=20 > then we start > over. So:: >=20 > "\\" -> "\" > "\\\*" -> "\*" > "\\\ " -> "\ " (in future, this may become "\ ") Then it's a documentation problem, because the quickref tells us = otherwise. Ciao, J=FCrgen -- J=FCrgen Hermann, Developer (jhe@webde-ag.de) WEB.DE AG, http://webde-ag.de/ From tony@lsl.co.uk Tue Aug 14 13:41:16 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 14 Aug 2001 13:41:16 +0100 Subject: [Doc-SIG] Not escaping the escape leaves no escape ;) In-Reply-To: Message-ID: <004e01c124be$68ddff50$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > Only those who understand the escaping and inline markup > rules may do the remaining 1% of cases. ;-) Ooh, I like it, I like it! (obOnTopic: I may actually have an in-house use waiting for DPS/reST, as a simple way of allowing people to produce HTML without having to learn anything much beyond a normal text editor. So I now have another reason for caring about all of this!) Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Tue Aug 14 13:52:49 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 14 Aug 2001 13:52:49 +0100 Subject: [Doc-SIG] Not escaping the escape leaves no escape ;) In-Reply-To: <82C891B6DD60D411A6F200508BC5D6030340D275@exchange1.cinetic.de> Message-ID: <004f01c124c0$05f46cb0$f05aa8c0@lslp7o.int.lsl.co.uk> > Then it's a documentation problem, because the quickref tells > us otherwise. Oh, quite likely - the quickref is being written by me, and in its writing I have discovered at least one fundamental misconception of a LARGE kind that I had about reST (and a stupid one at that) - I wouldn't be at all surprised if there were small things around the edge. David's document is the final reference, for all of that. Anyhoo, I personally won't entirely trust the quick ref until I can run the left hand side of each table through DPS/reST and generate (something sufficiently close to) the right hand side... <> Hmm. Where is the (current version of) the quick reference broken on this? Version 0.4 now says that:: \*escape* \'with' "\\" will produce something like:: *escape* 'with' "\" which matches what David said (indeed, it's his suggestion). This is a better example than before because it suggests *so* much more lurking behind the scenery to be understood... (i.e., if one doesn't understand it, one has to think about it). It's only rule 7 I worry about - in the context of the quickref it needs rewriting, because it doesn't say enough - for instance, one can do:: ``This is a \ and it doesn't need escaping`` which isn't clear therein. What rule 7 is addressing, I think, is:: ``We have a backslash at the end\`` and that's confusing to me (David - rule 7 could do with a *little* more exposition in the spec, to make clear what is going on for us people with a head cold). But then I find r"" strings confusing too, when they (don't) have a backslash at the end. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From Juergen Hermann" Message-ID: On Tue, 14 Aug 2001 13:52:49 +0100, Tony J Ibbs (Tibs) wrote: >Hmm. Where is the (current version of) the quick reference broken on >this? Version 0.4 now says that:: This morning, 0.3 was currrent. ;) Ciao, J=FCrgen From fdrake@acm.org Tue Aug 14 22:52:28 2001 From: fdrake@acm.org (Fred L. Drake) Date: Tue, 14 Aug 2001 17:52:28 -0400 (EDT) Subject: [Doc-SIG] [development doc updates] Message-ID: <20010814215228.696DA28845@cj42289-a.reston1.va.home.com> The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ A wide range of mostly small fixes and updates. Some new C API functions are documented. Examples are given for how to mark up tables in the "Documenting Python" guide. The language reference contains more information about support // and true division. From dgoodger@bigfoot.com Wed Aug 15 03:53:57 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 14 Aug 2001 22:53:57 -0400 Subject: [Doc-SIG] Not escaping the escape leaves no escape ;) In-Reply-To: <004f01c124c0$05f46cb0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-14 08:52: > (David - rule 7 could do with a *little* more exposition in the > spec, to make clear what is going on for us people with a head cold) Noted. /David (whose summer cold is thankfully limited to his throat at present) From dgoodger@bigfoot.com Wed Aug 15 03:54:17 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 14 Aug 2001 22:54:17 -0400 Subject: [Doc-SIG] Re: David's Idea for Lazy Indentation In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5AF6E@UKRUX002.rundc.uk.origin-it.com> Message-ID: Moore, Paul wrote on 2001-08-14 06:44: > Excuse my butting in - I'm not a member of the doc-sig, but I > noticed this while browsing the web archives. Not at all; glad to have you, the more the merrier. Please join up! (It's free you know. :-) > Surely this is a simple case of "don't do this"? My understanding is > that "structured text" (whatever form) should be something that can > be automatically translated into other forms (TeX, HTML, PDF, > whatever) but which is (as well as possible) readable in plain form. > In which case, your two examples are *only* "readable" as lists. One very important thing was missing from the original post: mention of the context. In this case, the context is for applications like Wikis and email, where decent editors are not available, and a "shortcut" lazy indentation mode may be desirable. Rest assured, it will not infect the rest of reStructuredtext. > PS As a check, did my enumerated list above work as > (re-)structured text? Yes, it looks fine, except that something (probably your email client) hard-wrapped a few words that stuck out a bit too far to the right, which would throw the parser for a loop. This is *exactly* the reason lazy indentation may be necessary in applications like email; thanks for providing an (unwitting) example! To see the problem, take a look at your message in the archive: http://mail.python.org/pipermail/doc-sig/2001-August/002138.html -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Wed Aug 15 04:20:05 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 14 Aug 2001 23:20:05 -0400 Subject: [Doc-SIG] Version 0.4 of reST quick guide In-Reply-To: <004a01c124a9$99657280$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-14 06:12: > As it says, version 0.4 of the quick ref is now at > > http://www.tibsnjoan.co.uk/reST/quick_reST.html I fixed two problem areas: 1. "Inline markup", last row. A backslash was escaping a single-quote, which isn't markup. Changed to backquotes. 2. "Autonumbered footnotes". Changed the autonumber labels, added an explanatory note. Also expanded "reST" abbreviations (I'm still not comfortable with them, especially not the Aretha Franklin association -- silly Tibs). Added to CVS as version 0.4.1: restructuredtext/docs/quickref.html. Please feel free to undo my butchery. I await version 0.5. Soon to be available at: http://structuredtext.sourceforge.net/docs/quickref.html -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From Paul.Moore@atosorigin.com Wed Aug 15 09:20:51 2001 From: Paul.Moore@atosorigin.com (Moore, Paul) Date: Wed, 15 Aug 2001 09:20:51 +0100 Subject: [Doc-SIG] RE: David's Idea for Lazy Indentation Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5AF71@UKRUX002.rundc.uk.origin-it.com> From: David Goodger [mailto:dgoodger@bigfoot.com] >Moore, Paul wrote on 2001-08-14 >06:44: > >> Excuse my butting in - I'm not a member of the doc-sig, >> but I noticed this while browsing the web archives. > >Not at all; glad to have you, the more the merrier. Please >join up! (It's free you know. :-) No, it's not - the cost is yet *more* E-Mail in my inbox :-) But I probably should. I care about having a documentation system. I worked with Perl for a long time, and there are major benefits to POD. Not, I hasten to add, because it is a *good* system (it sucks in many ways), but because it *exists*. I have a strong interest in seeing Python have a standard documentation system. Even if it's not perfect - it needs to exist SOON. More and more people are learning Python, and there needs to be a culture of seeing documentation (and testing - I was glad to see unittest get into the core - and standard distribution methods - distutils ditto) as "just something that you do". Perl module documentation may not always be good, but it's always there, and always accessible by the same means (perldoc). That makes a lot of difference. >One very important thing was missing from the original >post: mention of the context. In this case, the context is >for applications like Wikis and email, where decent editors >are not available, and a "shortcut" lazy indentation mode >may be desirable. Rest assured, it will not infect the rest >of reStructuredtext. Hmm. So this is a context where the original plain text is never going to be read "raw"? In that case, I can see the point (a bit). But that sounds like a significantly different application area (markup-less markup, as it were, rather than structured plaintext -- but maybe I'm taking the point too far). >> PS As a check, did my enumerated list above work as >> (re-)structured text? > >Yes, it looks fine, except that something (probably your >email client) hard-wrapped a few words that stuck out a bit >too far to the right, which would throw the parser for a >loop. This is *exactly* the reason lazy indentation may be >necessary in applications like email; thanks for providing >an (unwitting) example! To see the problem, take a look at >your message in the archive: Yes, I saw that after I'd posted :-) But I have some thoughts there. First, I can't imagine that sort of problem *ever* being automatically fixable. I've seen enough quoted text mangled by E-Mail systems to give up hope. It simply isn't *readable* -- let alone automatically fixable. (I know quoting differs from structured constructs, but if you think of a quote as a bulleted list with > as the bullet, you get my point...) Second, I was annoyed when I saw that post. I see it as a failure on my part to not take into account the annoying tendencies of my E-Mail client to re-wrap text, when posting. It's *my* job to communicate clearly. It's not the recipient's job to struggle through mangled text in order to to perceive the pearls of wisdom I impart :-) [Nor is it the job of some almost-magical piece of software to allow both of us to be lazy - after all, the recipient may not be able to *run* the software against the text - for example, while reading the web archive!] Finally, if someone *writes* text in that sort of lazy format (I'm thinking here of dumb editors, rather than later mangling like E-Mail), I'd say that they aren't taking enough care over the form of what they are saying, which makes me wonder about the content. Maybe I'm over harsh, but I really do believe that taking a little extra time to format clearly pays vastly in terms of clarity of wording. And a system which bends over backwards to allow people to format sloppily, is favouring form over content a little too much. (Hmm, I hope that didn't come across as too dogmatic - it isn't meant to be...) Paul. From tony@lsl.co.uk Wed Aug 15 09:39:04 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 15 Aug 2001 09:39:04 +0100 Subject: [Doc-SIG] Version 0.4 of reST quick guide In-Reply-To: Message-ID: <006001c12565$bd8948a0$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger wrote: > I fixed two problem areas: > > 1. "Inline markup", last row. A backslash was escaping a single-quote, > which isn't markup. Changed to backquotes. Thanks. I *think* I'd just forgotten what I was doing in context there. > 2. "Autonumbered footnotes". Changed the autonumber labels, added an > explanatory note. OK. I was trying to work from Garth's notes, so was half sure I hadn't quite got it all (no problem with Garth's notes, just with my understanding!). I think, from your amendments, that I now do understand. > Also expanded "reST" abbreviations (I'm still not comfortable with > them, especially not the Aretha Franklin association -- silly Tibs). Heh, silly is good (although I've always wanted "weird"). I still like the abbreviation reST, and shall continue to use it (I seriously think it is better than RST, which is rather bland and quite likely to be used for all sorts of other things). The Aretha Franklin association is, well, not *really* something other people have to care about! But, regardless, I'm OK with using the full name in the quickref, and have left it so. > Added to CVS as version 0.4.1: restructuredtext/docs/quickref.html. > Please feel free to undo my butchery. Looks OK to me. > I await version 0.5. See below - I've also fixed some HTML errors (stupid ones, on my part - should have used HTML tidy) that Amos Latteier (hope he doesn't mind my mentioning him) has pointed out. > Soon to be available at: > > http://structuredtext.sourceforge.net/docs/quickref.html Heh - it's there already! Anyway, I've taken a copy, and applied my edits to that, to produce version 0.4.2 (I don't think it warrants a whole 0.9 change in version number). By the way, I note that you changed the title from quick_reST to quickref - I'm not *terribly* fussed, but I would have thought that some redundancy in the title would be a good thing (for instance, if someone is downloading it to local disk for use, they don't *really* want to have to think up a good name for it, and if *everyone* calls their quickref document "quickref"...). Of course, as a point either for my point or against it (hmm), I note that the Python quick reference is already called quick-ref2.0.html. Opinions? Regardless, since I still don't have any response from Sourceforge on my user name, I don't have to worry about trying to update it directly (!), and thus I have updated the (by now familiar) http://www.tibsnjoan.co.uk/reST/quick_reST.html Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From fdrake@acm.org Wed Aug 15 20:41:36 2001 From: fdrake@acm.org (Fred L. Drake) Date: Wed, 15 Aug 2001 15:41:36 -0400 (EDT) Subject: [Doc-SIG] [development doc updates] Message-ID: <20010815194136.8BEE328846@beowolf.digicool.com> The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ More material on defining new types in C in "Extending & Embedding the Python Interpreter": http://python.sourceforge.net/devel-docs/ext/defining-new-types.html From dgoodger@bigfoot.com Thu Aug 16 03:24:59 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Wed, 15 Aug 2001 22:24:59 -0400 Subject: [Doc-SIG] Re: David's Idea for Lazy Indentation In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5AF71@UKRUX002.rundc.uk.origin-it.com> Message-ID: Moore, Paul wrote on 2001-08-15 04:20: > From: David Goodger [mailto:dgoodger@bigfoot.com] > >In this case, the context is for applications like Wikis and email, > >where decent editors are not available... > > Hmm. So this is a context where the original plain text is never > going to be read "raw"? Yes, but it's the lack of decent editing support that's the real issue. The "lazy mode" was requested [1]_ especially for the use of Wikis, where there's typically only an edit box on a web page in which to insert one's post. Manually indenting under these conditions can be onerous. .. _[1] Requested most recently by Garth Kidd, who is connected to the MoinMoin_ Wiki clone: http://moin.sourceforge.net/cgi-bin/moin/moin/ > But I have some thoughts there. First, I can't imagine that sort of > problem *ever* being automatically fixable. Agreed. I wouldn't try to fix such problems. What the lazy mode allows is minimal indentation from the beginning, so that bad line wrapping doesn't matter, like this:: - This is a bullet list item. - Here's another. If this is wrapped 10 columns in, we get this:: - This is a bullet list item. - Here's another. The accidental wrapping doesn't adversely affect the markup recognition (or affects it less). We can't mix strict and lazy indentation though; doesn't work (as evidenced by your previous message). -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From dgoodger@bigfoot.com Thu Aug 16 03:26:52 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Wed, 15 Aug 2001 22:26:52 -0400 Subject: [Doc-SIG] Version 0.4 of reST quick guide In-Reply-To: <006001c12565$bd8948a0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-15 04:39: > By the way, I note that you changed the title from quick_reST to > quickref Yes, just because "quickref" is instantly recognizable as such. "reST" does have advantages, though. It can be pronounced (as "rest", not spelled to music please!), and extended ("reStructuredText Next Generation" could be "reST NG" pronounced "resting", a reStructuredText editor or emacs editing mode could be "reSTed", and I'm sure somebody could come up with a use for "arreST", "unreST", and perhaps even "reSTless" ;-). -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From fdrake@acm.org Thu Aug 16 23:09:36 2001 From: fdrake@acm.org (Fred L. Drake) Date: Thu, 16 Aug 2001 18:09:36 -0400 (EDT) Subject: [Doc-SIG] [development doc updates] Message-ID: <20010816220936.4E38428845@cj42289-a.reston1.va.home.com> The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Improved documentation for the os.spawn*() functions. Fix some HTML generation problems. From dgoodger@bigfoot.com Fri Aug 17 00:22:52 2001 From: dgoodger@bigfoot.com (David Goodger) Date: Thu, 16 Aug 2001 19:22:52 -0400 Subject: [Doc-SIG] Re: [Docstring-develop] Attribute docstrings In-Reply-To: <000301c12659$3a9a7370$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-16 09:42: > DPS (pep 258) is proposing to support attribute docstrings. > > Yet PEP 224 was rejected by the BDFL because he dislikes the look of:: > > a = 1 > """Documentation.""" > b = 1 > > a. because he doesn't like it > b. because he can't tell if the docstring belongs > to `a` or `b` > > This rejection did *not* worry about issues of what value was used to > store the docstring (obviously not an issue for us). > > Is DPS on dodgy ground in supporting a PEP that has been fundamentally > rejected? The fundamental differences between PEP 224 and the relevant part of PEP 258 are the impact and the context. PEP 224 required changes to the core Python language for a feature of marginal usefulness *to* the core language. The DPS (PEP 258) provides a useful, application context for the concept of attribute docstrings, without requiring any changes to the core Python language. Attribute docstrings become a simple documentation convention with no impact or incompatibilities. Although I think attribute docstrings are very useful (see dps/statemachine.py for a complete example), the success of the DPS does not hinge on them being accepted. If push comes to shove, they're easy to drop. But I hope it doesn't come to that, since it's really an application issue. > As a potential *slight* cure for the BDFL objections (I'm doubtful), I > can only propose that we mark up the docstring itself:: > > a = 1 > """.. doc::a Some documentation""" > > would be documentation for `a`. That's a bit verbose, so maybe it should > be:: > > """:doc:a Some documentation""" > > Or even:: > > """:a: Some documentation""" > > (is that last stretching too far?) > > [I'm not sure I like any of the above, in fact Nor do I; I don't think any of these would fly. If forced to use such markup, I think I'd rather just leave these docstrings in the parent module/class/method/function docstring. > Or maybe we should enforce no blank line before the docstring, and at > least one blank line after it (I've yet to see if we can tell that from > the AST, but I suspect we can). If we can glean this info from the AST, then that's certainly a possibility. > do we have a BDFL comment on this part of the DPS spec? Let's ask. What do you think, Guido? -- David Goodger dgoodger@users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From goodger@users.sourceforge.net Fri Aug 17 03:56:26 2001 From: goodger@users.sourceforge.net (David Goodger) Date: Thu, 16 Aug 2001 22:56:26 -0400 Subject: [Doc-SIG] Changes to reStructuredText spec Message-ID: I've updated the specification documents quite a bit, along the lines of the recent discussions. Highlights: - Removed leading underscore from footnote definition [1]_ and added implicit hyperlink target generation (like section headers). - Added automatic numbering of footnotes. - Moved interpreted text's role outside of backquotes. - Settled on field list syntax (":field-name: field body"), updated definition. I'm in the process of updating the *uses* of field lists in the various documents and modules as well. - Added 'abstract' to list of bibliographic elements. - Loosened enumerated list requirements (2-in-a-row). - Removed requirement for blank lines between definition list items. - Added option lists & doctest blocks from pyextensions.txt (which will be removed soon, and the non-syntax parts reincarnated as a DPS Python "mode"). .. [1] This is one of the most interesting changes, I expect. By leveraging the implicit hyperlink target generation of section headers, footnotes now look much more natural. And confusion with hyperlink targets should decrease too. The implementation changes will follow shortly. (Wait a sec -- isn't that backwards? Usually the docs lag behind the code. Not for a documentation project, I guess. ;-) I haven't made a new release yet, but there are now daily snapshots updated at midnight EDT (04:00 UTC): - reStructuredText code & spec: http://structuredtext.sourceforge.net/rst-snapshot.tgz - DPS code & spec: http://docstring.sourceforge.net/dps-snapshot.tgz -- David Goodger dgoodger@users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From fdrake@acm.org Mon Aug 20 23:41:02 2001 From: fdrake@acm.org (Fred L. Drake) Date: Mon, 20 Aug 2001 18:41:02 -0400 (EDT) Subject: [Doc-SIG] [development doc updates] Message-ID: <20010820224102.B942E28846@beowolf.digicool.com> The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Final documentation for Python 2.2 alpha 2. From tony@lsl.co.uk Tue Aug 21 09:23:36 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 21 Aug 2001 09:23:36 +0100 Subject: [Doc-SIG] Oscar - pre-announcement over on Types-SIG Message-ID: <002701c12a1a$930ddc80$f05aa8c0@lslp7o.int.lsl.co.uk> I don't know if people here watch the Types-SIG, and I suspect that Greg doesn't watch the Doc-SIG, so... Greg Ward has just made a pre-announcement of Oscar [1]_. To quote: several months ago, I cooked up a tool, Oscar for rigorously type-checking a Python object graph: you define an object schema (currently through specially- formatted class docstrings), and Oscar crawls a persistent object graph to ensure that every scrap of data in it conforms to your schema. We use this regularly in the MEMS Exchange for integrity-checking our ZODB database; it's not the be-all-end-all to checking that all is well with an object database, but it's a hell of a lot better than nothing. The interesting bit for us is "through specially-formatted class docstrings". These look like, for instance:: class Animal (Thing): """An animal, ie. a thing with multiple legs and possibly fur. Instance attributes: num_legs : int the number of legs this animal has furry : boolean whether this animal is furry or not Outsiders should use 'get_num_legs()' and 'is_furry()' to access these attributes. """ His parser looks for the ``Instance attributes:``, and eats anything indented after it (and the formatting of that is fairly strict). Thought for us - this is something we need to bear in mind, since it would be nice if we didn't muck up its appearance when processing a docstring for presentation. Thoughts for Greg - currently the ``Instance attributes`` clause, as presented, would not be acceptable to the DPS/reStructuredText system. However, it's very near. There are two ways to change it to *make* it acceptable: 1. Simply add a blank line after ``Instance attributes:`` (that would make the stuff thereafter a descriptive list, which sort-of makes sense) 2. Prepend an additional colon before ``Instance attributes:``, and make the "title" into a single "word" - for instance:: :Instance-attributes: or:: :InstanceAttributes: This looks a bit uglier, but means that the text following could be handed to a specialised plugin which knows to do special things with it. The "schema spec ends when indentation returns to that of the title" rule will work OK in DPS/reST. .. [1] http://aspn.activestate.com/ASPN/Mail/Message/types-sig/751935 Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From gward@mems-exchange.org Tue Aug 21 16:40:04 2001 From: gward@mems-exchange.org (Greg Ward) Date: Tue, 21 Aug 2001 11:40:04 -0400 Subject: [Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG In-Reply-To: <002701c12a1a$930ddc80$f05aa8c0@lslp7o.int.lsl.co.uk>; from tony@lsl.co.uk on Tue, Aug 21, 2001 at 09:23:36AM +0100 References: <002701c12a1a$930ddc80$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: <20010821114004.A9888@mems-exchange.org> On 21 August 2001, Tony J Ibbs (Tibs) said: > I don't know if people here watch the Types-SIG, and I suspect that Greg > doesn't watch the Doc-SIG, so... I used to watch the doc-sig, but got overwhelmed. Sorry... > Thought for us - this is something we need to bear in mind, since it > would be nice if we didn't muck up its appearance when processing a > docstring for presentation. > > Thoughts for Greg - currently the ``Instance attributes`` clause, as > presented, would not be acceptable to the DPS/reStructuredText system. > However, it's very near. There are two ways to change it to *make* it > acceptable: > > 1. Simply add a blank line after ``Instance attributes:`` > (that would make the stuff thereafter a descriptive > list, which sort-of makes sense) I'm pretty sure you can already do that with my current docstring parser. > 2. Prepend an additional colon before ``Instance > attributes:``, and make the "title" into a single > "word" - for instance:: > > :Instance-attributes: > > or:: > > :InstanceAttributes: > > This looks a bit uglier, but means that the text > following could be handed to a specialised plugin > which knows to do special things with it. I'm not opposed to generalizing the parser a bit to handle these forms. Right now it just does this: if line.startswith("Instance attributes:"): Looks like I could accomodate you by changing this to: if re.match(r':?instance[\ \-]?attributes:', line): which doesn't bother me. Question for the doc-sig: * is DPS/reST the One True Docstring syntax? do we have it at last? an end to the docstring wars? or is this just one more proposed syntax? * do you have a standard for documenting instance attributes and their types yet? I had to invent my own for Oscar, and I'm quite happy with it. If there's an existing standard, I'm willing to entertain the notion of modifying my parser to accomodate it. If not, may I propose my syntax as part of the standard? Greg -- Greg Ward - software developer gward@mems-exchange.org MEMS Exchange http://www.mems-exchange.org From goodger@users.sourceforge.net Wed Aug 22 04:06:09 2001 From: goodger@users.sourceforge.net (David Goodger) Date: Tue, 21 Aug 2001 23:06:09 -0400 Subject: [Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG In-Reply-To: <20010821114004.A9888@mems-exchange.org> Message-ID: Greg Ward wrote on 2001-08-21 11:40: > On 21 August 2001, Tony J Ibbs (Tibs) said: > > I don't know if people here watch the Types-SIG, and I suspect > > that Greg doesn't watch the Doc-SIG, so... > > I used to watch the doc-sig, but got overwhelmed. Sorry... There are only so many hours in the day! :-) > > Thought for us - this is something we need to bear in mind, since > > it would be nice if we didn't muck up its appearance when > > processing a docstring for presentation. It's a good idea to keep compatibility with other applications of docstrings, to a point. Past that point lies creeping featurism and overcomplexity. Some would say we've passed that point already ;-). > > Thoughts for Greg - currently the ``Instance attributes`` clause, > > as presented, would not be acceptable to the DPS/reStructuredText > > system. However, it's very near. There are two ways to change it > > to *make* it acceptable: > > > > 1. Simply add a blank line after ``Instance attributes:`` > > (that would make the stuff thereafter a descriptive > > list, which sort-of makes sense) > > I'm pretty sure you can already do that with my current > docstring parser. This will turn "Instance attributes:" into a simple paragraph, and the attributes themselves into a block quote containing a definition list. Although this is probably sufficient for Oscar's purposes, it doesn't do the data any descriptive justice. > > 2. Prepend an additional colon before ``Instance > > attributes:``, and make the "title" into a single > > "word" - for instance:: > > > > :Instance-attributes: > > > > or:: > > > > :InstanceAttributes: > > > > This looks a bit uglier, but means that the text > > following could be handed to a specialised plugin > > which knows to do special things with it. > > I'm not opposed to generalizing the parser a bit to handle > these forms. > Right now it just does this: > if line.startswith("Instance attributes:"): > > Looks like I could accomodate you by changing this to: > if re.match(r':?instance[\ \-]?attributes:', line): > which doesn't bother me. This creates a field in what we call a "field list", like an RFC822 header field, where "Instance-attributes" is the field name and the field body consists of a definition list. Descriptively better than option #1. But it still doesn't extract the semantic information embedded in the description of the types. I'm not sure about Tony's reference to a "specialized plugin" for fields. Although we have settled on a syntax for field lists, there has yet to be a discussion about what field lists actually *do*, if anything, other than describing a data structure. I'm wary of it, but one (remote) possibility is for field lists to acquire functionality similar to that of directives. This leads us to... Another option: use a directive:: class Animal (Thing): """An animal, ie. a thing with multiple legs and possibly fur. Instance attributes: .. oscar:: num_legs : int the number of legs this animal has furry : boolean whether this animal is furry or not Outsiders should use 'get_num_legs()' and 'is_furry()' to access these attributes. """ The "oscar" directive is free to define the syntax of its contents and do anything it likes with the results. > Question for the doc-sig: > * is DPS/reST the One True Docstring syntax? do we have it at last? > an end to the docstring wars? or is this just one more proposed > syntax? The DPS_ is the Python Docstring Processing System, subject of PEPs 256 and 258. reST [1] is reStructuredText, a markup syntax and parser component of the DPS, possibly one of many. In my biased opinion, it reStructuredText seems to have more support than any other proposal, and the best chance of success. Juergen Hermann of MoinMoin fame has shown definite interest, as have others (in private correspondence), and still more are guardedly interested (wait and see). .. _DPS: http://docstring.sourceforge.net .. [1] A complete reference to reStructuredText can be found at http://structuredtext.sourceforge.net/spec/reStructuredText.txt, and Tony's QuickRef is located at http://structuredtext.sourceforge.net/docs/quickref.html. The reStructuredText parser is almost complete, but the DPS itself is still in its infancy. The DPS is a framework, providing a clean separation of input markup, processing, and output format. If you get on the bandwagon with Oscar, it will help push reStructuredText toward becoming the exalted "One True Syntax", and help push the DPS toward completion and eventual inclusion in the standard library. So please do! And your input is welcome. > * do you have a standard for documenting instance attributes and > their types yet? I had to invent my own for Oscar, and I'm > quite happy with it. See Frederic Giacometti's post "documenting Python constraints on types" (specifically the "iPhrase" attachment: doc-conventions.html) for another approach: http://mail.python.org/pipermail/doc-sig/2001-May/001840.html > If there's an existing standard, I'm willing to entertain the > notion of modifying my parser to accomodate it. Glad to hear it. I don't know of an established "standard"; if any, I'd have thought it would have been developed by the Types SIG. > If not, may I propose my syntax as part of the standard? It would be easy enough to fit it in. As it is, the text after "Instance attributes:" is a reStructuredText definition list. The "type : NAME" (etc.) syntax listed in `Oscar's type system`_ is a bit inadequate, since a simple colon is so often used in plain text. .. _Oscar's type system: http://aspn.activestate.com/ASPN/Mail/Message/types-sig/751935/ unknown1 In combination with an "oscar" directive the syntax wouldn't be a problem, since the directive can parse its data using a special local syntax. It may even be feasible to add an optional classifier to definition list items:: term [ ' : ' classifier ] definition This would be enough to separate the Oscar 'type' from the classifier. The classifier could be formatted distinctively, in italics or otherwise. Opinions? -- David Goodger goodger@users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From tony@lsl.co.uk Wed Aug 22 09:47:39 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 22 Aug 2001 09:47:39 +0100 Subject: [Doc-SIG] RE: Not escaping the escape leaves no escape ;) In-Reply-To: <20010821125723C.eddy@chaos.org.uk> Message-ID: <004901c12ae7$1945c7a0$f05aa8c0@lslp7o.int.lsl.co.uk> Edward Welbourne (hi Eddy) wrote: > Hi Tibs [..deletia..] > but the backslash stuff has me a bit confused > ... partly because the illustrations didn't appear > to be using r'...' strings. > > In non-raw strings, a backslash followed by > something it doesn't find interesting is just > an ordinary character > > >>> 'hell\o there' > 'hell\\o > >>> 'h\appy birthday' > 'h\007ppy birthday' > >>> # (James Bond escapes as an alert character ;^) > > but a backslash is, itself, interesting to a backslash; > so (changing one of your ' pairs to a ` pair so I can > enclose in a ' pair) > > >>> '\*escape* \`with` "\\"' > '\\*escape* \\`with` "\\"' > >>> '\\*escape* \\`with` "\\"' > '\\*escape* \\`with` "\\"' > > your parser isn't going to be able to distinguish > whether the source contained doubled or single > backslashes, except when the following character > is one that backslash finds interesting ... but > your rules seem to depend on your parser knowing > this. > > I may be worrying needlessly, but just thought I'd > better throw a sanity-check `\007' ! He also said: > Feel free to forward to doc-sig if novel and interesting > enough ;^> so I am doing so... Ah - it may be necessary to beware that DPS/reST is not only aimed at docstrings, so almost all of the examples are going to assume "plain text" as the input - i.e., some form of non-Pythonic text file - and leave the "docstring-isation" up to the user ('cos that's easier to do - it also (personal opinion!) makes it easier to ignore how, erm, rather hard it is to use backslashes as escape characters within Python strings... Indeed, your choice of example shows that you've been reading the quickref, and it is also talking about "bare" text - so that sounds like I need to add a small section on embedding reST within *actual* docstrings. I'll try to get around to amending the quickref to mention something along those lines. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Aug 22 09:47:43 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 22 Aug 2001 09:47:43 +0100 Subject: [Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG In-Reply-To: Message-ID: <004a01c12ae7$1bac1940$f05aa8c0@lslp7o.int.lsl.co.uk> David Goodger replied to Greg Ward (who was replying to me): > > I used to watch the doc-sig, but got overwhelmed. Sorry... > > There are only so many hours in the day! :-) Indeed! > I'm not sure about Tony's reference to a "specialized plugin" for > fields. Although we have settled on a syntax for field lists, there > has yet to be a discussion about what field lists actually *do*, if > anything, other than describing a data structure. I'm wary of it, but > one (remote) possibility is for field lists to acquire functionality > similar to that of directives. Nah - I think it was a brainio on my part - I was trying to make a response in between building executables and debugging something else, and indeed what I *should* have said is what David suggests next: > Another option: use a directive: Greg then asks: > > Question for the doc-sig: > > * is DPS/reST the One True Docstring syntax? do we have > > it at last? an end to the docstring wars? or is this > > just one more proposed syntax? Technically, it is indeed "just one more proposed syntax". But David has done two important things - he has separated the infrastructure that *uses* the docstrings from the parser that understands their content (hence the DPS and reST split, respectively - and yes, I know HappyDoc, for instance, has done it as well, but it didn't do it so, well, prominently), and he has also managed to amalgamate the threads on the Doc-SIG to produce something that, whilst not *actually* and *formally* proposed as the One True Syntax, has a good chance at it. As a long term Doc-SIG participant (my name is Tibs and I'm involved with the Doc-SIG) *I* am willing to accept it as the OTS (erm...). More importantly, Guido has made modest supportive noises (warning: my success at remembering details of what Guido says is limited!). Also, it *won't* be a *required* syntax - documenting in plain text (for instance) will always be "allowed" (not that there's anyone to allow or disallow such things). Regardless, for the trivial changes to be made to Oscar that admit it to reST compliance, it seems worth it to me. > The reStructuredText parser is almost complete, but the DPS itself is > still in its infancy. The DPS is a framework, providing a clean > separation of input markup, processing, and output format. What he said. Progress *is* being made, though. > In combination with an "oscar" directive the syntax wouldn't be a > problem, since the directive can parse its data using a special local > syntax. It may even be feasible to add an optional classifier to > definition list items:: > > term [ ' : ' classifier ] > definition > > This would be enough to separate the Oscar 'type' from the classifier. > The classifier could be formatted distinctively, in italics or > otherwise. Hmm - do we care about the distinctness (or not) between:: term : classifier and:: word: some text I'd probably leave that for the moment. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From goodger@users.sourceforge.net Thu Aug 23 03:18:21 2001 From: goodger@users.sourceforge.net (David Goodger) Date: Wed, 22 Aug 2001 22:18:21 -0400 Subject: [Doc-SIG] RE: Not escaping the escape leaves no escape ;) In-Reply-To: <004901c12ae7$1945c7a0$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-22 04:47: > I need to add a small section on embedding reST within *actual* > docstrings. >From PEP 257: Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. I'll add a note to the spec about this as well. -- David Goodger goodger@users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From goodger@users.sourceforge.net Thu Aug 23 03:20:09 2001 From: goodger@users.sourceforge.net (David Goodger) Date: Wed, 22 Aug 2001 22:20:09 -0400 Subject: [Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG In-Reply-To: <004a01c12ae7$1bac1940$f05aa8c0@lslp7o.int.lsl.co.uk> Message-ID: Tony J Ibbs (Tibs) wrote on 2001-08-22 04:47: > Hmm - do we care about the distinctness (or not) between:: > > term : classifier > > and:: > > word: some text I would prefer to require spaces on both sides of the colon, to avoid accidents in cases like:: Mission: Impossible A cheesy 60's TV show and lame 90's movie. -- David Goodger goodger@users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net From tony@lsl.co.uk Thu Aug 23 09:04:54 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 23 Aug 2001 09:04:54 +0100 Subject: [Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG In-Reply-To: Message-ID: <001201c12baa$4b58f3c0$f05aa8c0@lslp7o.int.lsl.co.uk> > Tony J Ibbs (Tibs) wrote on 2001-08-22 04:47: > > Hmm - do we care about the distinctness (or not) between:: > > > > term : classifier > > > > and:: > > > > word: some text David Goodger wrote: > I would prefer to require spaces on both sides of the colon, to > avoid accidents in cases like:: > > Mission: Impossible > A cheesy 60's TV show and lame 90's movie. Sorry - I wasn't precise enough. What I was trying to say was: Do we care if we have two forms with different meanings which only differ in whether the colon is preceded by a space or not - i.e., that:: term : classifier has a radically different meaning than:: term: classifier (the former is a term and classifier, the second is just a word followed by a colon). Tibs (still not too fussed about it, though) -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From gward@mems-exchange.org Thu Aug 23 15:13:51 2001 From: gward@mems-exchange.org (Greg Ward) Date: Thu, 23 Aug 2001 10:13:51 -0400 Subject: [Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG In-Reply-To: ; from goodger@users.sourceforge.net on Tue, Aug 21, 2001 at 11:06:09PM -0400 References: <20010821114004.A9888@mems-exchange.org> Message-ID: <20010823101351.A442@mems-exchange.org> On 21 August 2001, David Goodger said: > Another option: use a directive:: > > class Animal (Thing): > """An animal, ie. a thing with multiple legs and possibly fur. > > Instance attributes: > > .. oscar:: > num_legs : int > the number of legs this animal has > furry : boolean > whether this animal is furry or not > > Outsiders should use 'get_num_legs()' and 'is_furry()' > to access these attributes. > """ > > The "oscar" directive is free to define the syntax of its contents and > do anything it likes with the results. FYI: s/oscar/grouch/; too many projects named "Oscar" already. Anyways. Seems to me that a much neater way to do this would be .. grouch-instance-attributes:: num_legs : int the number of legs this animal has furry : boolean whether this animal is furry or not ie. drop the "Instance attributes:" line entirely, and just use a single reST directive. It's just spelling; why say the same thing twice? > The DPS_ is the Python Docstring Processing System, subject of PEPs > 256 and 258. reST [1] is reStructuredText, a markup syntax and parser > component of the DPS, possibly one of many. OK, that was my rough understanding, based mainly on skimming the doc-sig for the last couple of months. Glad to hear things are going right at last -- I would be quite happy to make trivial changes to Grouch's syntax to play along nicely with reST. It's not gonna happen in the first release, though, which is imminent. In my biased opinion, it > reStructuredText seems to have more support than any other > proposal, and the best chance of success. Juergen Hermann of MoinMoin > fame has shown definite interest, as have others (in private > correspondence), and still more are guardedly interested (wait and > see). > > .. _DPS: http://docstring.sourceforge.net > > .. [1] A complete reference to reStructuredText can be found at > http://structuredtext.sourceforge.net/spec/reStructuredText.txt, > and Tony's QuickRef is located at > http://structuredtext.sourceforge.net/docs/quickref.html. > > The reStructuredText parser is almost complete, but the DPS itself is > still in its infancy. The DPS is a framework, providing a clean > separation of input markup, processing, and output format. All sounds pretty sensible to me. Just downloaded "rst.0.3.tar.gz". Argg. One of the reasons I wrote the Distutils was because I was (and still am) tired of downloading tarballs with non-standard names that unpack to directories whose names are not immediately obvious from the tarball. Such as, for instance "rst.0.3.tar.gz" which unpacks to "restructuredtext". If you had simply used the Distutils "sdist" command (and updated the version in your setup.py), this would be "rst-0.3.tar.gz" which unpacks to "rst-0.3", which is the time-honoured convention for source distributions on Unix, used by thousands of programmers for well over a decade. Grumble. The Distutils exist for a reason! > If you get on the bandwagon with Oscar, it will help push > reStructuredText toward becoming the exalted "One True Syntax", and > help push the DPS toward completion and eventual inclusion in the > standard library. So please do! And your input is welcome. Yeah, that would be a good thing. I'll look into it for some future version. > In combination with an "oscar" directive the syntax wouldn't be a > problem, since the directive can parse its data using a special local > syntax. It may even be feasible to add an optional classifier to > definition list items:: > > term [ ' : ' classifier ] > definition > > This would be enough to separate the Oscar 'type' from the classifier. > The classifier could be formatted distinctively, in italics or > otherwise. Interesting notion. Whether it's of general interest will have to be decided by the doc-sig, but I like it! ;-) For the record, I'd much rather require spaces around a single colon than any other contortion -- ie. " : " over "::". Greg -- Greg Ward - software developer gward@mems-exchange.org MEMS Exchange http://www.mems-exchange.org From tony@lsl.co.uk Thu Aug 23 16:45:54 2001 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 23 Aug 2001 16:45:54 +0100 Subject: [Doc-SIG] quick_reST 0.4.6 In-Reply-To: Message-ID: <001d01c12bea$b1d480c0$f05aa8c0@lslp7o.int.lsl.co.uk> I've uploaded a new version of the quick reference, at (as always): http://www.tibsnjoan.co.uk/reST/quick_reST.html It merges back in some changes David made, and has a start at some text (well, a table) about what to do in docstrings if you want to use backslashes to escape reST things. Main other changes: all uses of
 in the left hand side of tables
removed (this gives better formatting in many browsers); title hack
suggested by David adopted (to get the  part in a better size) -
this may be temporary.

(hmm - will we ever reach version 0.5?)

Tibs

(who's now having mad thoughts about::

    .. reSTexample::
       :title: Inline markup
       :link:  :rest:reStructuredText.html#inline_markup
       :plain: ``*emphasis*``
       :shown: *emphasis*

directives, despite having said to David that one couldn't use reST to
produce the quick reference...)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From fdrake@acm.org  Thu Aug 23 20:27:01 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Thu, 23 Aug 2001 15:27:01 -0400
Subject: [Doc-SIG] Re: [Python-Dev] Inline and SWIG
In-Reply-To: <05c601c12bfb$fcd46c50$e000a8c0@thomasnotebook>
References: <200108230601.SAA04304@s454.cosc.canterbury.ac.nz>
 <05c601c12bfb$fcd46c50$e000a8c0@thomasnotebook>
Message-ID: <15237.22789.951079.581327@grendel.digicool.com>

Thomas Heller writes:
 > Makes a pretty good pair with a calldll-like extension module.

  I guess calldll is very different from the dl module, which has
documentation.  Is anyone up to writing docs for calldll?
  I've CC'd to the Doc-SIG since there may be volunteers there ;-) --
please remove python-dev from doc-related followups.


  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Zope Corporation



From goodger@users.sourceforge.net  Thu Aug 23 23:51:29 2001
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 23 Aug 2001 18:51:29 -0400
Subject: [Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG
In-Reply-To: <001201c12baa$4b58f3c0$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: 

Tony J Ibbs (Tibs)  wrote on 2001-08-23 04:04:
> Sorry - I wasn't precise enough.

No, you were, *I* wasn't ;-)

> What I was trying to say was:
>=20
> Do we care if we have two forms with different meanings which only
> differ in whether the colon is preceded by a space or not - i.e., that::
>=20
> term : classifier
>=20
> has a radically different meaning than::
>=20
> term: classifier
>=20
> (the former is a term and classifier, the second is just a word followed
> by a colon).

I think the ' : ' syntax is natural, and unlikely to occur accidentally.
Escpecially not in the one context where it's to be recognized: definition
lists. So, to answer your question directly: we do care, but not too much,
and it will be documented.

I just took a look through the archives, and saw an earlier reference to
just this sort of thing, on 2000-02-08, by Edward Welbourne (Subject: Re:
[Doc-SIG] Cross-reference proposal). His proposal was to use ' ! ' as the
delimiter. It turns out that I replied to the ongoing discussions at the
time, in my first posting to the Doc-SIG (Subject: [Doc-SIG] Docstring: a
newbie's two bits), suggesting ' : ' instead. Interesting to read one's
opinions so far (18 months!) back and see how far we've come. And "plus =E7a
change, plus c'est la m=EAme chose".

--=20
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net



From goodger@users.sourceforge.net  Fri Aug 24 04:32:19 2001
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 23 Aug 2001 23:32:19 -0400
Subject: [Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG
In-Reply-To: <20010823101351.A442@mems-exchange.org>
Message-ID: 

Greg Ward  wrote on 2001-08-23 10:13:
> Seems to me that a much neater way to do this would be
> 
> .. grouch-instance-attributes::
> num_legs : int
> the number of legs this animal has
> furry : boolean
> whether this animal is furry or not
> 
> ie. drop the "Instance attributes:" line entirely, and just use a single
> reST directive.  It's just spelling; why say the same thing twice?

True. This would be the way to do Grouch-specific markup, if the 'term :
classifier' definition list markup is inadequate.

> 
...
> If you had simply used the Distutils "sdist" command

>From "Distributing Python Modules", section 5 "Creating a Source
Distribution":

    ** no MacOS support here **

Guess what OS I use. ;-) I could do sdist on SourceForge, but I don't know
if they even *have* DistUtils there (they still use 1.5.2, so I'd have to
install it myself; I wish they'd upgrade!).

Didn't I read on comp.lang.python that somebody was working on a tarlib.py?

> this would be "rst-0.3.tar.gz" which unpacks to "rst-0.3",
> which is the time-honoured convention for source distributions on Unix,
> used by thousands of programmers for well over a decade.  Grumble.  The
> Distutils exist for a reason!

Point taken; I'll be good in future.

BTW, did you notice install.py? I wrote it as a shortcut to do "python
setup.py install" especially for older Macs. As I'm sure you know, on MacOS
it's not easy to specify command-line options. When I run setup.py on MacOS,
a settings dialog box opens up, which is great, but it takes *forever* on my
old box; install.py avoids the wait (of make & eat a sandwich duration).

Anyhow, in order to avoid the dialog box, I had to write this:

    core._setup_stop_after = 'config'
    dist = do_setup()
    dist.commands = ['install']
    dist.run_commands()

That first line is *really* kludgey. Any chance of making this more
straightforward?

> 

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net



From goodger@users.sourceforge.net  Fri Aug 24 04:32:44 2001
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 23 Aug 2001 23:32:44 -0400
Subject: [Doc-SIG] quick_reST 0.4.6
In-Reply-To: <001d01c12bea$b1d480c0$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: 

Tony J Ibbs (Tibs)  wrote on 2001-08-23 11:45:
> (who's now having mad thoughts about::
> 
>   .. reSTexample::
>      :title: Inline markup
>      :link:  :rest:reStructuredText.html#inline_markup
>      :plain: ``*emphasis*``
>      :shown: *emphasis*
> 
> directives, despite having said to David that one couldn't use reST to
> produce the quick reference...)

Surely we could come up with better syntax than *that*! ;-)

/David



From tony@lsl.co.uk  Tue Aug 28 09:02:27 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Tue, 28 Aug 2001 09:02:27 +0100
Subject: [Doc-SIG] quick_reST 0.4.6
In-Reply-To: 
Message-ID: <006b01c12f97$c79ee110$f05aa8c0@lslp7o.int.lsl.co.uk>

David Goodger [mailto:goodger@users.sourceforge.net]
> Tony J Ibbs (Tibs)  wrote on 2001-08-23 11:45:
> > (who's now having mad thoughts about::
> >
> >   .. reSTexample::
> >      :title: Inline markup
> >      :link:  :rest:reStructuredText.html#inline_markup
> >      :plain: ``*emphasis*``
> >      :shown: *emphasis*
> >
> > directives, despite having said to David that one couldn't
> use reST to
> > produce the quick reference...)
>
> Surely we could come up with better syntax than *that*! ;-)

I *said* they were mad thoughts!

And yes, I'm sure we could come up with a better syntax (for, of course,
it is up to the "reSTexample" directive plugin what it does), but *that*
syntax leverages off what we already have, so is both very simple (for
one meaning of the word) and also uses what people have already learnt.

In fact, given the restrictions of the requirements, I would suspect one
would *actually* use something more like::

    .. reSTexample:: Inline markup (:rest:)
       ``*emphasis*`` | *emphasis*

i.e., a more abbreviated table format. But that would require writing
new code, and might (in the end) be harder to understand.

Anyway, time enough for the future.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
In Python it's clearer to talk about "names" and "bindings"
rather than "variables" and "values"... "you can't change
the binding of a name in your caller's namespace" doesn't
leave much room for misunderstanding. (Greg Ewing)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From tony@lsl.co.uk  Wed Aug 29 09:21:13 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Wed, 29 Aug 2001 09:21:13 +0100
Subject: [Doc-SIG] DPS and DOM trees
In-Reply-To: <006b01c12f97$c79ee110$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <009101c13063$90baa090$f05aa8c0@lslp7o.int.lsl.co.uk>

I've now got to a stage with dps_visit.py where I'm starting to play
with actually integrating DPS/reST into it. Yes, I know it isn't
finished yet (!), but I want to flesh out what it's going to do before
fining it down (putting that another way, I want to see some HTML output
from what I'm doing, and that means generating a DOM tree first).

This leads to a question/comment or two...

Firstly, the DOM support in dps/nodes.py is bound fairly strongly to
minidom. This has the advantage (to the user) that they don't have to do
anything particularly special to get a DOM tree (a few lines of code,
nicked from restructuredtext/tools/quicktest.py will do it), but it has
the downside that one *is* tied to minidom. I could well imagine someone
using 4DOM (for instance) wanting to cache the DOM trees for a variety
of Python modules - rather as Unix systems sometimes cache the results
of parsing man pages. Or wanting to do queries on the tree that minidom
doesn't provide support for.

I would thus like to propose that the user provide a DOM document
instance to the DOM generator methods - this allows them to derive that
however they like, and we can document which methods we require (the
writexml method is called outwith this context, so we can assume it's
being used by a caller who already knows which DOM system is being
used).

As a fallback position, one *might* make minidom the default - but I
prefer explicitness here, I think.

Secondly, the current nodes.py assumes that the document produced will
map to a single docstring - or at least so it look to me (after a short
time reading it, admittedly). This is a disadvantage if one is trying to
produce a DOM tree with (for instance) a Python module as the "top" of
the document tree, and docstrings hanging off various points.

Luckily, if the user is required to provide the DOM document to the
code, then this problem goes away - one just adds children to the
relevent element in the tree.

If these ideas seem sensible, would it be a Good Thing for me to work on
my own version of nodes.py, and integrate it back in later on (bearing
in mind my CVS-lessness)?

Thirdly, and separately, do we intend to support Python 1.5.2, or are we
starting support with 2.0? Whilst I think it was important that pydoc
worked for 1.5.2, I'm less worried for this - although it isn't *hard*
to do it, it may be inconvenient (although I'm still working with 1.5.2
at work, alas).

Tibs (who narrowly avoided starting to write docstrings for existing
code last night, instead of writing new code)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From goodger@users.sourceforge.net  Thu Aug 30 05:31:48 2001
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 30 Aug 2001 00:31:48 -0400
Subject: [Doc-SIG] Re: DPS and DOM trees
In-Reply-To: <009101c13063$90baa090$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: 

Tony J Ibbs (Tibs)  wrote on 2001-08-29 04:21:
> I've now got to a stage with dps_visit.py where I'm starting to play
> with actually integrating DPS/reST into it.

Great!

> Yes, I know it isn't finished yet (!), but I want to flesh out what
> it's going to do before fining it down

That's the way the rest of the development is going too, so no
problem; please go ahead.

> (putting that another way, I want to see some HTML output from what
> I'm doing, and that means generating a DOM tree first)

Why is a DOM tree a prerequisite for HTML output? I don't follow.

> I would thus like to propose that the user provide a DOM document
> instance to the DOM generator methods

Is there a reason to provide a DOM *document instance* rather than a
constructor? The reason I ask is that in my implementation of
nodes.py, if you say ``document.asdom()`` you'll get a DOM tree rooted
at a DOM Document object, but if you say ``element.asdom()`` you'll
get a tree fragment, rooted at the DOM element itself, not at
Document. I think this will be useful when we get into tree
transformations.

Will something like this work? ::

    document = Parser().parse(data)
    domtree = document.asdom(your_favourite_DOM_implementation_here)

Currently nodes.py uses the Document, Element, and Text constructors
of minidom. The Document object's appendChild(), createTextNode(), and
createElement() methods are used. The Element object's setAttribute()
and appendChild() methods are used.

Are the DOM implementations standard enough for this kind of
interoperability? If so, then the work is done (see the CVS or
snapshot). That was easy. Calling document.asdom() without an argument
defaults to the xml.dom.minidom implementation.

If that won't do it, I'll leave it to you to figure out how it should
be done. As xml.dom.minidom is the only applicable DOM implementation
in the standard library, I haven't tried any others and have no
experience with them.

> Secondly, the current nodes.py assumes that the document produced
> will map to a single docstring - or at least so it look to me (after
> a short time reading it, admittedly). This is a disadvantage if one
> is trying to produce a DOM tree with (for instance) a Python module
> as the "top" of the document tree, and docstrings hanging off
> various points.
> 
> Luckily, if the user is required to provide the DOM document to the
> code, then this problem goes away - one just adds children to the
> relevent element in the tree.

The Python docstring mode model that's evolving in my mind goes
something like this:

1. Extract the docstring/namespace tree from the module(s) and/or
   package(s).

2. Run the parser on each docstring in turn, producing a forest of
   trees (internal data structure as per nodes.py).

3. Run various transformations on the individual docstring trees.
   Examples: resolving cross-references; resolving hyperlinks;
   footnote auto-numbering; first field list -> bibliographic
   elements.

4. Join the docstring trees together into a single tree, running more
   transformations (such as creating various sections like "Module
   Attributes", "Functions", "Classes", "Class Attributes", etc.; see
   the DPS spec/ppdi.dtd).

5. Pass the resulting unified tree to the output formatter.

I've had trouble reconciling the roles of input parser and output
formatter with the idea of "modes". Does the mode govern the
tranformation of the input, the output, or both? Perhaps the mode
should be split into two.

For example, say the source of our input is a Python module. Our
"input mode" should be "Python Docstring Mode". It discovers (from
``__docformat__``) that the input parser is "reStructuredText". If we
want HTML, we'll specify the "HTML" output formatter. But there's a
piece missing. What *kind* or *style* of HTML output do we want?
PyDoc-style, LibRefMan style, etc. (many people will want to specify
and control their own style). Is the output style specific to a
particular output format (XML, HTML, etc.)? Is the style specific to
the input mode? Or can/should they be independent?

I envision interaction between the input parser, an "input mode" (would
control steps 1, 2, & 3), a "transformation style" (would control step
4), and the output formatter. The same intermediate data format would
be used between each of these, gaining detail as it progresses.

This requires thought.

> would it be a Good Thing for me to work on my own version of
> nodes.py,

I don't see nodes.py taking on these responsibilities (the ones you
mentioned, not my pie-in-the-sky ramblings above). Instead, I see
these functions being done by a set of tree transforms (using what, I
don't know yet) and transformation modes (each comprised of a subset
of the aforementioned tree transforms).

> and integrate it back in later on (bearing in mind my CVS-lessness)?

If you can't use CVS, please use the daily snapshots and send me
patches.

> Thirdly, and separately, do we intend to support Python 1.5.2, or
> are we starting support with 2.0?

I've absorbed the new features of 2.0 too completely to want to revert
to 1.5.2. String methods and augmented assignment have become second
nature. Of course, it's possible to back-port to 1.5.2 (the new syntax
is all so much sugar, if sweet). If enough need arises, fine.

A larger issue might be that relating to the docstring extraction
mechanism. Won't the code that uses compiler.py be very
version-dependent? It would be very convenient if both the DPS and
PyChecker used a common module for module parsing; this module could
be maintained independently.

> Tibs (who narrowly avoided starting to write docstrings for existing
> code last night, instead of writing new code)

We need more of those too!

/David (who tends to write docstrings when confused by his own code)

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net



From tony@lsl.co.uk  Thu Aug 30 10:12:15 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 30 Aug 2001 10:12:15 +0100
Subject: [Doc-SIG] Re: DPS and DOM trees
In-Reply-To: 
Message-ID: <00b401c13133$dc75df10$f05aa8c0@lslp7o.int.lsl.co.uk>

David Goodger wrote:
> Why is a DOM tree a prerequisite for HTML output? I don't follow.

Hmm - I hadn't thought about it much.

Firstly, I want to be able to take advantage of the parsers other people
are writing for the DPS project (I only need to provide the extra bits
for the Python specific structures outwith the docstring), and as I
understand it, those work off the DOM tree?

Secondly, I felt the DOM interface was more "published" (or, perhaps,
obvious by inspection, and less likely to change) than the "internal"
interface. I'm still at a *very* early stage in navigating around the
source code.

My "understanding" that DOM is the official interface between parser and
formatter may, of course, be, erm, flawed (I know Guido suggested it
need not be, and using Python classes directly can be much more
pleasant). Hmm - have I missed something in the documentation again?

Where is the actual structure of the document *as Python datastructure*
defined? Is the stuff in nodes.py the class structure for the Python
tree structure (of course, by the time you answer this, I may have
worked it out - time folding is fun).

Somehow I can't help feeling that the infoset is a natural for my
thinking of this "document" we're working with, as well - particularly
as we *are* talking about a document of sorts. That's what SGML (and
later XML) was designed to work with. Still doesn't mean we *have* to
use DOM at any particular stage, but...

> > I would thus like to propose that the user provide a DOM document
> > instance to the DOM generator methods
>
> Is there a reason to provide a DOM *document instance* rather than a
> constructor?

Hmm - I thought that in DOM the document instance (or perhaps class)
*was* the constructor - but I (think I) see what you mean.

I'll retrieve the latest snapshot again (I try to do so daily) and have
a look (I'm having a good run on getting stuff done in the evening at
the moment - this won't last, as school term starts again next
Wednesday, and life gets more frenetic).

> Are the DOM implementations standard enough for this kind of
> interoperability?

I believe that some of the methods are predetermined by translation from
the standard. But I may be wrong (in which case, of course, life is only
*slightly* more complex). I've yet to get fully to grips with Python XML
stuff.

> The Python docstring mode model that's evolving in my mind goes
> something like this:
>
> 1. Extract the docstring/namespace tree from the module(s) and/or
>    package(s).
>
> 2. Run the parser on each docstring in turn, producing a forest of
>    trees (internal data structure as per nodes.py).
>
> 3. Run various transformations on the individual docstring trees.
>    Examples: resolving cross-references; resolving hyperlinks;
>    footnote auto-numbering; first field list -> bibliographic
>    elements.
>
> 4. Join the docstring trees together into a single tree, running more
>    transformations (such as creating various sections like "Module
>    Attributes", "Functions", "Classes", "Class Attributes", etc.; see
>    the DPS spec/ppdi.dtd).
>
> 5. Pass the resulting unified tree to the output formatter.

OK - my model is not dissimilar, but goes like:

1. Parse the Python module(s) [remembering we may have a package]
   This locates the docstrings, amongst other things.

2. Trim the tree to lose stuff we didn't need (!).

3. Parse the docstrings (this might, instead, be done at the time
   that each docstring is "discovered").

4. Integrate the docstring into the tree - this *may* be as simple
   as having "thing.docstring = "

5. Perform internal resolutions on the docstring (footnotes, etc.)

6. Perform intra-module/package resolutions on the docstring
   (so this is when we work out that `Fred` in *this* docstring
   refers to class Fred over here in the datastructure).

7. Format.

Now, it may be that a DOM tree makes sense for the datastructure for
some of those steps - certainly if that's what the formatter is going to
want.

Also note that, if we go via a DOM tree, we can "cheat" with references,
a bit like Unix linkers do - thus if we have::

    :class:`Fred`

we might store that with a *reference* to
"#..Fred", and trust to there being a class in
the DOM tree that declares its id to be the same - this naive approach
gets one quick satisfaction for links that are easy, but doesn't give
one any error response for unsatisfied links, of course.

In my mind, I don't think of a great tidal change at the interface
between module documentation and docstring - I think of it all as one
structure (so there might be internal structure to a parameter list, and
there might be internal structure to a docstring - same idea).

> I've had trouble reconciling the roles of input parser and output
> formatter with the idea of "modes". Does the mode govern the
> tranformation of the input, the output, or both? Perhaps the mode
> should be split into two.

A mode needs to:

1. Provide plugins for parsing - this *may* go so far as to subsume
   the DPS functionality into a new program, as I'm doing for Python.
   In this case the "plugin" for parsing may be virtual - I just need
   to ferret around in the docstring looking for things that are
   already there, perhaps.

2. Provide plugins for formatting - again, these may subsume a
   DPS parser process. In the Python case, I clearly want to
   *use* the normal HTML parser for HTML output, but with
   extra support "around it" for the Python specific infrastructure.

I think this will become much clearer once I have an example (!).

Interestingly, I see directives as being split similarly - for a typical
(non-pragma) directive, one needs both code to parse the directive
content (or to manipulate what DPS/reST has already parsed), and code to
format it within a formatter. Clearly, formatters should cope well with
directives they *don't* understand, though!

> For example, say the source of our input is a Python module. Our
> "input mode" should be "Python Docstring Mode". It discovers (from
> ``__docformat__``) that the input parser is "reStructuredText". If we
> want HTML, we'll specify the "HTML" output formatter. But there's a
> piece missing. What *kind* or *style* of HTML output do we want?
> PyDoc-style, LibRefMan style, etc. (many people will want to specify
> and control their own style). Is the output style specific to a
> particular output format (XML, HTML, etc.)? Is the style specific to
> the input mode? Or can/should they be independent?
>
> I envision interaction between the input parser, an "input
> mode" (would
> control steps 1, 2, & 3), a "transformation style" (would control step
> 4), and the output formatter. The same intermediate data format would
> be used between each of these, gaining detail as it progresses.
>
> This requires thought.

Agreed - I think it will emerge as we try to do it.

This is, of course, another reason to consider the DOM as a useful
tool - people can be expected to learn about the DOM independently of
us, and to understand (in general) how to manipulate DOM trees. There
are standard ways of documenting the content of a DOM tree (DTD,
XMLSchema, etc.). There are Useful Tools.

Asking each person who wants to write a thingy to understand *our* tree
structure in depth may be more powerful in some ways, but more onerous
in others.

> I've absorbed the new features of 2.0 too completely to want to revert
> to 1.5.2. String methods and augmented assignment have become second
> nature. Of course, it's possible to back-port to 1.5.2 (the new syntax
> is all so much sugar, if sweet). If enough need arises, fine.

So far I've avoided doing this. But I think that for a tool like this,
we can probably make the break. And I do want to use the new syntactic
sugar (heck, OO is only some *very nice* syntactic sugar, albeit in
chunks rather than granules).

> A larger issue might be that relating to the docstring extraction
> mechanism. Won't the code that uses compiler.py be very
> version-dependent?

Not my experience. Indeed, that's one of its values - the compiler
package *itself* may differ from Python version to Python version, but
(except in dark corners) the code using it need not - and a try/except
or so will cope with those dark corners.

> It would be very convenient if both the DPS and
> PyChecker used a common module for module parsing;
> this module could be maintained independently.

Hmm. It should be doable - its just there would be a lot more
information extracted than we need. pydps/visit.py (what was until last
night's work dps_visit.py) is a good start towards that, I think.

> > Tibs (who narrowly avoided starting to write docstrings for existing
> > code last night, instead of writing new code)
>
> We need more of those too!

Yes...

> /David (who tends to write docstrings when confused by his own code)

Ah - that's why I like them too - but I always expect to be confused by
my code!

Whilst I'm at it - update on my code:

	http://www.tibsnjoan.co.uk/reST/pydps.tgz

contains::

    pydps/
        visit.py   -- broadly, what was dps_visit.py
        dom.py     -- the DPS tree and DOM tree stuff
        test.py

I may change the name of "dom.py" - indeed, I may change all sorts of
things!

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From goodger@users.sourceforge.net  Fri Aug 31 03:30:16 2001
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 30 Aug 2001 22:30:16 -0400
Subject: [Doc-SIG] Re: DPS and DOM trees
In-Reply-To: <00b401c13133$dc75df10$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: 

Tony J Ibbs (Tibs)  wrote on 2001-08-30 05:12:
> David Goodger wrote:
> > Why is a DOM tree a prerequisite for HTML output? I don't follow.
> 
> Hmm - I hadn't thought about it much.
> 
> Firstly, I want to be able to take advantage of the parsers other
> people are writing for the DPS project (I only need to provide the
> extra bits for the Python specific structures outwith the
> docstring), and as I understand it, those work off the DOM tree?

Actually, after trying to use the DOM (xml.dom.minidom) directly, I
saw what you & Garth & Guido meant by its inconvenience and coded up
the nodes.py class library instead. That let me make the classes
convenient to use, with polymorphism and other OO goodies.

I added DOM output (.asdom()) as an option, not because it was needed
for anything, but (violating XP, I know) because it was easy and
served as a proof of concept.

Nothing works off an actual DOM tree directly. The parser creates a
nodes.py tree, and unless necessity arises I don't see why the rest of
the DPS (output formatters included) shouldn't use the same as their
interface data structure.

> I'm still at a *very* early stage in navigating around the source
> code.

Not helped much by the paucity of documentation; apologies.

> Where is the actual structure of the document *as Python
> datastructure* defined?

PEP 258, "Intermediate Data Structure":

    A single intermediate data structure is used by the docstring
    processing system, in the interfaces between parsers, the DPS
    itself, and formatters.  It is not required that this data
    structure be used internally by any of the componentes.  This data
    structure is similar to a DOM tree whose schema is documented in
    an XML DTD ...

It started out being "a DOM tree", now it's "similar to a DOM tree".
Easy to miss.

> Is the stuff in nodes.py the class structure for the Python tree
> structure

Yes.

I have some updating to do on the PEPs. Will specify the nodes.py
implementation.

> Somehow I can't help feeling that the infoset is a natural for my
> thinking of this "document" we're working with...

Which "infoset"?

> > > I would thus like to propose that the user provide a DOM document
> > > instance to the DOM generator methods
> >
> > Is there a reason to provide a DOM *document instance* rather than a
> > constructor?
> 
> Hmm - I thought that in DOM the document instance (or perhaps class)
> *was* the constructor - but I (think I) see what you mean.

If the doc object is the constructor, we can change the interface to
.asdom() to accept such an object, or default to an
xml.dom.minidom.Document. That doesn't help with tree fragments
though.

> Interestingly, I see directives as being split similarly - for a
> typical (non-pragma) directive, one needs both code to parse the
> directive content (or to manipulate what DPS/reST has already
> parsed), and code to format it within a formatter. Clearly,
> formatters should cope well with directives they *don't* understand,
> though!

I think most directives won't survive (as directives) past the parsing
stage (they can't, since they're a *parser construct*). Instead,
they'll transform their contents into elements on the doc tree. Only
unknown directives will survive to any later stage, and be formatted
in a generic "directive" way, perhaps as a system warning.

Now, the newly transformed directive *contents* may be specialized
elements which require further processing later on, but they're no
longer raw directives.

> This is, of course, another reason to consider the DOM as a useful
> tool - people can be expected to learn about the DOM independently
> of us, and to understand (in general) how to manipulate DOM trees.
> There are standard ways of documenting the content of a DOM tree
> (DTD, XMLSchema, etc.). There are Useful Tools.
> 
> Asking each person who wants to write a thingy to understand *our*
> tree structure in depth may be more powerful in some ways, but more
> onerous in others.

Anybody who doesn't want to use the DPS structure can use .asdom() to
convert. If the need arises, we (they) can create a DOM->DPS tree
converter too.

> > It would be very convenient if both the DPS and
> > PyChecker used a common module for module parsing;
> > this module could be maintained independently.
> 
> Hmm. It should be doable - its just there would be a lot more
> information extracted than we need.

It's easier to prune a tree than to grow one! But until an alternative
exists, we must grow our own.

> I may change the name of "dom.py" - indeed, I may change all sorts
> of things!

Change is to be expected and embraced.

> --
> Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
> "Bounce with the bunny. Strut with the duck.
> Spin with the chickens now - CLUCK CLUCK CLUCK!"
> BARNYARD DANCE! by Sandra Boynton

We obviously have a parent of (recent, if not current) preschoolers.

I prefer, "But not the armadillo!" That's *funny*! (First time ;-)

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net



From tony@lsl.co.uk  Fri Aug 31 10:22:49 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Fri, 31 Aug 2001 10:22:49 +0100
Subject: [Doc-SIG] Re: DPS and DOM trees
In-Reply-To: 
Message-ID: <001601c131fe$80f7eb30$f05aa8c0@lslp7o.int.lsl.co.uk>

David Goodger wrote:
> Actually, after trying to use the DOM (xml.dom.minidom) directly, I
> saw what you & Garth & Guido meant by its inconvenience and coded up
> the nodes.py class library instead. That let me make the classes
> convenient to use, with polymorphism and other OO goodies.

Well, it's inconvenient to *create*, but I have an odd affection for it
as a datastructure to have to hand (too much XML stuff going on in the
background here, I guess - our field's extensive use of XML schema is
bound to be corrupting me as well).

I do still agree that the approach of regarding the DOM tree as an
"output format" in this case is Very Sensible.

> I added DOM output (.asdom()) as an option, not because it was needed
> for anything, but (violating XP, I know) because it was easy and
> served as a proof of concept.

No, it *is* useful.

I was looking again at PyPaSax again last night [1]_ - if it didn't
depend on PyXML being installed, I'd be considering that for doing the
Python parsing job (as it is, I've started to adopt some inspiration
from their (partial) DTD - at some point I'll write a Proper schema for
the Python part, and, for instance, using a "py" namespace seems very
sensible to me).

Having the DOM tree as interface means that we could slot the DPS
functionality into PyPaSax and lo, presto, they'd have docstring
structure instead of docstring #text. Alternatively, if the DOM tree is
the interface to the formatter, they benefit from that work as well
[bias]_.

.. [bias] I admit to historical bias here - I already know how easy
   it is to output HTML from a DOM tree - indeed, that's how the
   embrionic ``docutils`` did it, so I can learn from my experience
   with that code. I'll probably go that route because it's easy
   for me - we can always back port to the "internal" classes later
   on (I don't see that as hard). Also, selfishly, practice at
   thinking in XML related datastructures is a Useful Thing for me
   to have (that's *undoubtedly* bad XP practice!).

> Nothing works off an actual DOM tree directly. The parser creates a
> nodes.py tree, and unless necessity arises I don't see why the rest of
> the DPS (output formatters included) shouldn't use the same as their
> interface data structure.

I agree, save for the bias_ admitted above (heh, neat, a use for
footnotes-as-references!).

> > I'm still at a *very* early stage in navigating around the source
> > code.
>
> Not helped much by the paucity of documentation; apologies.

I think we code in different styles (or, perhaps, you code generically
earlier than I would), which means that there is more of a "tangle" of
interdependencies to unentwine, where I would introduce that later on
(refactoring being fun). But thinking is good for one, and generally
leads to good results.

And I can already see a niche for myself later on in adding docstrings
(yes, that probably was volunteering).

> > Is the stuff in nodes.py the class structure for the Python tree
> > structure
>
> Yes.

OK. Eventually we need to have direct documentation in there on how it
all hangs together - the DTD is not enough (indeed, is it still meant to
be correct?). But there's still time.

> I have some updating to do on the PEPs. Will specify the nodes.py
> implementation.

Neat.

> > Somehow I can't help feeling that the infoset is a natural for my
> > thinking of this "document" we're working with...
>
> Which "infoset"?

Erm - the general, wave-hands-in-the-air thingy that XML is just a
serialised encoding of [2] (see, I have some of the terms internalised
already). One of my "aha" moments with XML was (whilst reading [3])
realising that the "representation talked about" (i.e., XML) is not the
stuff that matters, which is the underlying infoset (I should, of
course, have realised that earlier, but noone had *said* "conceptual
schema", so my reflexes hadn't been triggered).

My other one was coming across the XPath (I think, or was it XPointer)
stuff that lets you treat a document as a tree structure and a linear
structure *at the same time* - I *like* that thinking.

> If the doc object is the constructor, we can change the interface to
> .asdom() to accept such an object, or default to an
> xml.dom.minidom.Document. That doesn't help with tree fragments
> though.

I'm not worrying - last night it took me ten minutes (I made a mistake
first time) to do what I wanted with the existing code - as soon as I
realised that the tagName attribute was what drove the DOM element
output, and thus could reset that from (the default) "document" to what
I wanted ("py:docstring") for the docstring.

So the current http://www.tibsnjoan.co.uk/reST/pydps.tgz contains code
that outputs an XML representation of a document, *including* the
structure of the docstring, integrated neatly in.

> Anybody who doesn't want to use the DPS structure can use .asdom() to
> convert. If the need arises, we (they) can create a DOM->DPS tree
> converter too.

Ooh - pretty toy. But can I think of a *need* for one?

> > > It would be very convenient if both the DPS and
> > > PyChecker used a common module for module parsing;
> > > this module could be maintained independently.
> >
> > Hmm. It should be doable - its just there would be a lot more
> > information extracted than we need.
>
> It's easier to prune a tree than to grow one! But until an alternative
> exists, we must grow our own.

The structure I am working with/towards at the moment has two phases
(three if one includes DOM) - well, maybe four:

1. Produce the AST using ``compiler``
2. Traverse the AST and produce appropriate objects to
   represent the higher level concepts - i.e., Package
   (still to come), Module, Class, Function, Method and
   (I realised late last night) probably Name.
3. For *our* purposes, produce a DPS tree from that
   - this is when we can ignore data we're not interested
   in.
4. If wished, produce a DOM tree from *that*.

Stage 2 is implemented by ``pydps.visit``, Stage 3 by ``pydps.nodes``,
and Stage 4 is a function within ``pydps.nodes``. At the moment, Stage 2
is not as general as it might be - whether it gets expanded by me or the
PyChecker people, later on, I'm not sure.

Also, Stages 1 and 2 together should work as a Useful Example for the
use of the ``compiler`` tool.

Hmm - if we're aiming at Python 2.3 for adoption of DPS/reST, we should
probably also be campaigning for ``compiler`` being moved from Tools to
Lib.

> > I may change the name of "dom.py" - indeed, I may change all sorts
> > of things!
>
> Change is to be expected and embraced.

And it's now (perhaps confusingly) called ``nodes.py``.

> > "Bounce with the bunny. Strut with the duck.
> > Spin with the chickens now - CLUCK CLUCK CLUCK!"
> > BARNYARD DANCE! by Sandra Boynton
>
> We obviously have a parent of (recent, if not current) preschoolers.

One current, one recent.

> I prefer, "But not the armadillo!" That's *funny*! (First time ;-)

Our favourite is (well, you guessed) Barnyard Dance. It survives being
read/chanted an infinite number of times rather well. Indeed, we
recently bought a "keeping" copy to supplement the one that Thomas has
chewed.

But I've been a fan of Sandra Boynton for a Long Time - it used to be
possible to buy birthday/christmas/etc. cards by her, which were
seriously neat (they appear and disappear from the shops over the
years). And, of course, there's Chocolate: The consuming passion.

Unfortunately, though, we don't have "But not the armadillo!" (at least
15 other titles, mind you, from a brief count on her publishers' pages).

(we do, however, as of a few weeks ago, have a tape of "Rhinoceros
Tap" - good stuff.)

.. [1] http://www.logilab.org/pypasax/index.html
.. [2] http://www.w3.org/TR/xml-infoset/ - heh, that's a new
   version just out...
.. [3] **Essential XML: Beyond Markup**
   by Don Box, John Lam, and Aaron Skonnard
   (Addison Wesley, ISBN: 0-201-70914-7)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Dinosaurs looking right at YOU
to say GOODBYE because we're through.
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)