From garth@deadlybloodyserious.com  Fri Mar  1 00:13:41 2002
From: garth@deadlybloodyserious.com (Garth Kidd)
Date: Fri, 1 Mar 2002 11:13:41 +1100
Subject: [Doc-SIG] some ideas for reStructuredText & document model
In-Reply-To: <B8A32523.1F470%goodger@users.sourceforge.net>
Message-ID: <000101c1c0b5$f4127b30$4600800a@gkiddlap>

> - Change footnote syntax from ``.. [1]`` to ``_[1]``? Has this been
>   discussed before?

Oh, probably, but do it anyway. :) 

> - Differentiate author-date "citations" (``[GVR2002]``) from numbered
>   footnotes? Create a new set of DTD elements: "citation" and
>   "citation_reference"?

Sounds good, especially the difference in rendering. 

> - Render footnote references as superscripts without "[]"? (But only
>   if we differentiate numerical footnotes from textual citations.)

This is where you start wanting to use XHTML/CSS. Or, of course, people
can just use the XML output and write their own transforms. 

> - Make footnotes two-way, GNU-style? What if there are multiple
>   references to a single footnote?

Ha! I told you that'd happen! :) 

> - Add a "sidebar" element to the DTD? Like a generic admonition or
>   floating mini-section. Useful for TOC, system messages section,
>   abstract, etc.

Lovely. 

> 
> - Add character processing? For example:
> 
>   - "--" -> em-dash (or "--" -> en-dash, and "---" -> em-dash)

Yes! Yes! My personal preference is -- for em-dashes, but I bet I'm
mis-using them. :) 

>   - convert quotes to curly quote entities

I hate it when that happens. 

>   - various forms of ":-)" to smily icons

That, too. 

>   How to represent entities in the text though? Unicode?

&euml; and friends?

Regards,
Garth.



From goodger@users.sourceforge.net  Fri Mar  1 03:30:03 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 28 Feb 2002 22:30:03 -0500
Subject: [Doc-SIG] some ideas for reStructuredText & document model
In-Reply-To: <000101c1c043$f21838a0$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <B8A45FEA.1F558%goodger@users.sourceforge.net>

[David]
> > - Change footnote syntax from ``.. [1]`` to ``_[1]``?

[Tony]
> Hmm. Colour me ambivalent on this one

Me too. But it has potential. See my followup, where I propose ``_1.``
as the footnote marker syntax and ``1_`` for footnote references. I'm
much happier about these.

> I quite like being able to scan down the left hand side of the text
> looking for "..<space>" to allow me to find the things being
> referenced.

Could that just be familiarity talking? Tibs, the voice of the
status-quo! ;-)

Acceptance of the new syntax would require accepting that a footnote
*isn't* the same type of element as a comment or directive.

> >   Note that the body of the footnote need not be indented.

Please note that my "note" was wrong. Revised:

    Note that the body of the footnote still needs to be indented, by
    at least one space. Without indentation, a footnote could only
    contain one paragraph.

> I'd suggest producing an example with mixed footnotes and reference
> targets

Please do!

> > - Differentiate author-date "citations" (``[GVR2002]``)
> >   from numbered footnotes? Create a new set of DTD elements:
> >   "citation" and "citation_reference"?
>
> Surely that's a presentation issue, and thus only relevant to the
> Writer? - i.e., if the footnote is numbered (or anonymously numbered)
> then present it one way, otherwise another.

Actually, I'm thinking of interpreting, representing (in the doctree),
and processing footnotes and citations (& their references) in
different ways.

> > - Render footnote references as superscripts without "[]"?
>
> This is definitely a Writer issue

I'm not so sure. I've since realized that my footnote/citation ideas
are all related, and point to changes in the reStructuredText syntax
as well as the docutils tree model. Don't forget, reStructuredText is
"what-you-see-is-what-you-get plaintext markup", so how it ends up
being rendered *does* influence the markup (we want the input to
resemble the output as much as possible). See my followup post,
"Reworking Footnotes", which I'm developing in alternatives.txt__.

__ http://structuredtext.sf.net/spec/alternatives.txt

> many HTML browsers, for instance, are rubbish at presenting
> superscripts (and I'd want to check our what lynx or links did with
> superscripts, too!), so if your HTML Writer were to adopt this
> approach, you might well get complaints.

I'm aiming this HTML Writer at late-model graphical browsers, and
writing it to standards: it uses HTML 4.01 (almost "strict") and CSS1
extensively, but no CSS2 (still not widely implemented it seems).
Implementation variations are to be expected, and user feedback will
of course be welcome.

If the demand warrants (and if time allows and/or volunteers arise),
several HTML variant Writers could be developed: for HTML 3.2, for
text browsers, etc. Each could render the output as best suited.

> > - Make footnotes two-way, GNU-style? What if there are multiple
> >   references to a single footnote?
>
> Again, this is a Writer issue.

Agreed. A transform issue, anyway.

> > - Directive ideas: TOC (GNU-style two-way), endnotes *here*,
> >   citations *here*.
>
> Surely also influenced by a command line option, in the same way
> that the choice of fold in or call out indirect hyperlinks is a run
> time choice?
>
> (a [set of] command line option[s] to say that all notes or
> footnotes or whatever are to be gathered together at the end (of the
> document, section, etc.), and what the section they are gathered
> into should be called, are surely things to consider strongly as
> options to the Writer, and thus also command line options to the
> interface to the system using that Writer)

We could have command-line options for some defaults or variations,
but they're limited. When I write a document, I want to be able to
specify where to put the table of contents. Similarly for an index or
a collection of endnotes (although I could see establishing defaults,
especially for endnotes & citations).

For a hypothetical example::

    The Book of All
    ===============

    .. toc:: Table of Contents
       :depth: 2

    Introduction
    ------------

    Revealed herein for the first time: the true meaning
    of life. After years of painstaking research...

> > - Add a list of pending transforms to the document node,
> >   generated by directives? Or add an element, "pending" perhaps,
> >   which encapsulates the transform, the point at which to apply
> >   it, and any data required.
>
> Not sure I understand this, but I'm behind in my understanding of
> the system at the moment anyway...

I think an example will clarify this. Say you want a table of contents
in your document. The easiest way to specify where to put it is from
within the document, with a directive::

    .. toc::

But the "toc" directive can't do its work until the entire document
has been parsed (and possibly transformed to some extent). So we need
to leave a placeholder behind that will trigger the second phase of
the directive's processing. The directive can leave an element at that
point in the doctree, something like this::

    <pending directive="toc" ...other attributes...>
        ...any directive data...

Simultaneously, we add the "pending" node to a list attached to the
document's root node, so that a later stage of processing can easily
run all pending directive transforms.

> > - Add a "sidebar" element to the DTD? Like a generic admonition or
> >   floating mini-section. Useful for TOC, system messages section,
> >   abstract, etc.
>
> Presentation again - it's usefulness depends entirely upon the
> target format

I think I didn't explain well enough. DocBook has a good example of
what I mean, the "simplesect", defined as "a section of a document
with no subdivisions":

    SimpleSect is one of the top-level sectioning elements in a
    component. There are three types of sectioning elements in
    DocBook:

    - Explicitly numbered sections, Sect1...Sect5, which must be
      properly nested and can only be five levels deep.

    - Recursive Sections, which are alternative to the numbered
      sections and have unbounded depth.

    - SimpleSects, which are terminal. SimpleSects can occur as the
      "leaf" sections in either recursive sections or any of the
      numbered sections, or directly in components.

    SimpleSects may be more convenient than numbered sections in some
    authoring environments because they can be moved around in the
    document hierarchy without renaming.

    None of the sectioning elements is allowed to "float" in a
    component. You can place paragraphs and other block elements
    before a section, but you cannot place anything after it.

    (From *DocBook: The Definitive Guide*, by Norman Walsh & Leonard
    Muellner; http://docbook.org/tdg/en/html/simplesect.html)

The Docutils tree implements recursive sections. A SimpleSect or a
"sidebar" is just like a section, except that it has no subsections,
and is allowed wherever a body element (list, table, etc.) is allowed,
but only at the top level of a section. In other words sidebars cannot
nest inside body elements, so you can't have a sidebar inside a table,
a list, or a block quote etc.

The existing abstract element is a fixed-title, fixed-position (in the
doctree) sidebar. The various admonition directives produce
fixed-title sidebar-equivalents (although they can nest inside body
elements). Sidebars would be useful for generic equivalents of
abstracts and admonitions. It gets tiring and cumbersome to keep
adding specialized elements to the DTD. I've already got the system
inserting a "Docutils System Messages" section. The DTD will need an
element to store a table of contents, and I'm sure we'll come up with
other specialized section-equivalents.

Advantages: Sidebars don't have to conform to section placement rules
(e.g., there can be paragraphs before and after, at the same level as
the sidebar). They can be excluded from a table of contents.

> (keep thinking of plain text, LaTeX and PDF as alternatives to
> HTML!)

Actually, I'm basing these ideas on my experience with document
analysis and SGML processing systems. I'm trying to come up with a
format-independent document representation. This is a case where I
don't have a DTD construct suited to the task.

> > - Add character processing? For example:
> >
> >   - "--" -> em-dash (or "--" -> en-dash, and "---" -> em-dash)
>
> Some of us would quite like these particular cases - I'd look for
> pre-existing conventions, though, as to how many hyphens mean what.

Noted.

> >   - convert quotes to curly quote entities
>
> A presentation issue - for HTML, don't bother, as it's essentially
> impossible. For [La]TeX, don't bother as it will do it for you
> anyway(!).

Noted.

> >   - various forms of ":-)" to smily icons
>
> Can we all say "ick"?

What, wouldn't you like to see little yellow happy faces interspersed
in your documents? :-P

I think the Wiki people would. 8-}

> >   - others?
>
> Forced linebreak (without paragraph break) and non-breaking space
> are the other obvious ones, but syntax is problematical (as we've
> found before!).

I had those in rst-notes.txt already. I've merged it all together.

> >   How to represent entities in the text though? Unicode?
>
> I'd say that this is definitely getting too ambitious for this stage
> of the project.

Yes, probably. Just throwing it out there to see what comes back. Just
like the PEP process, recording all these questions, decisions, and
to-dos is useful for the future.

> Tibs
>
> (who still thinks that "::" blocks should be indented in the HTML
> output for neat appearance, but realises that others may disagree)

In my stylesheet, they are indented. Or should be. 2 em's worth.

BTW, what browser/version & OS/version are you using?

> .. [1] In the output at
>    http://structuredtext.sourceforge.net/spec/test.html, the example
>    admonitions are uniformly set into boxes that are wider than my
>    browser page. This presumably means that something in the
>    document is of fixed width, rather than relative.

In the test document, the only things with fixed widths are the
graphics (which were actually broken; no "title.png" file where it was
supposed to be) and the literal blocks. In my browser, the "Doctest
Blocks" literal block was the determining factor.

>    I suspect it may actually be the fault of the "docinfo" table at
>    the top of the document, in particular the "copyright" field,
>    which is also too wide. I don't, however, understand stylesheets
>    well enough to see any obvious problem...

I'm just learning about stylesheets myself. From my reading of the
specs, the docinfo table should expand to fill whatever width is
available, but shouldn't force the browser to scroll horizontally.
It's probably exactly as wide as the widest fixed-width element, which
is probably the doctest block. Could be browser-specific, though.
"Abandon hope, all ye who enter here."

-- 
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 Mar  1 03:35:58 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 28 Feb 2002 22:35:58 -0500
Subject: [Doc-SIG] some ideas for reStructuredText & document model
In-Reply-To: <000101c1c0b5$f4127b30$4600800a@gkiddlap>
Message-ID: <B8A4614D.1F55A%goodger@users.sourceforge.net>

What's this? Garth the yes-man? Strange days.

[David]
>> - Render footnote references as superscripts without "[]"?

[Garth
> This is where you start wanting to use XHTML/CSS.

My HTML Writer uses CSS1 extensively, but only HTML 4.01. Is XHTML support
ready for prime time?

>> - Make footnotes two-way, GNU-style? What if there are multiple
>>   references to a single footnote?
> 
> Ha! I told you that'd happen! :)

Did you? And did you have any useful suggestions at the time? ;)

>> How to represent entities in the text though? Unicode?
> 
> &euml; and friends?

No, I think not, unless the character processing is done by the Writer.
If we have to represent esoteric characters in the doctree, Unicode
will probably be the medium. But that's a decision for another day.

-- 
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 Mar  1 03:38:23 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 28 Feb 2002 22:38:23 -0500
Subject: [Doc-SIG] Reworking Footnotes
Message-ID: <B8A461DE.1F55B%goodger@users.sourceforge.net>

(From http://structuredtext.sourceforge.net/spec/alternatives.txt)

Earlier today (late last night) I posted several ideas for changes to
footnote syntax:

    - Change footnote syntax from ``.. [1]`` to ``_[1]``? ...
    - Differentiate (with new DTD elements) author-date "citations"
      (``[GVR2002]``) from numbered footnotes? ...
    - Render footnote references as superscripts without "[]"? ...

These ideas are all related, and suggest changes in the
reStructuredText syntax as well as the docutils tree model.

The footnote has been used for both true footnotes (asides expanding
on points or defining terms) and for citations (references to external
works). Rather than dealing with one amalgam construct, we could
separate the current footnote concept into strict footnotes and
citations.  Citations could be interpreted and treated differently
from footnotes.  Footnotes would be limited to numerical labels:
manual ("1") and auto-numbered (anonymous "#", named "#label").

The footnote is the only explicit markup construct (starts with ".. ")
that directly translates to a visible body element.  I've always been
a little bit uncomfortable with the ".. " marker for footnotes because
of this; ".. " has a connotation of "special", but footnotes aren't
especially "special".  Printed texts often put footnotes at the bottom
of the page where the reference occurs (thus "foot note").  Some HTML
designs would leave footnotes to be rendered the same positions where
they're defined.  Other online and printed designs will gather
footnotes into a section near the end of the document, converting them
to "endnotes" (perhaps using a directive in our case); but this
"special processing" is not an intrinsic property of the footnote
itself, but a decision made by the document author or processing
system.

Citations are almost invariably collected in a section at the end of a
document or section.  Citations "disappear" from where they are
defined and are magically reinserted at some well-defined point.
There's more of a connection to the "special" connotation of the ".. "
syntax.  The point at which the list of citations is inserted could be
defined manually by a directive (e.g., ".. citations::"), and/or have
default behavior (e.g., a section automatically inserted at the end of
the document) that might be influenced by options to the Writer.

Syntax proposals:

+ Footnotes:

  - Current syntax::

        .. [1] Footnote 1
        .. [#] Auto-numbered footnote.
        .. [#label] Auto-labeled footnote.

  - The syntax proposed in the original 2002-02-28 Doc-SIG post:
    remove the ".. ", prefix a "_"::

        _[1] Footnote 1
        _[#] Auto-numbered footnote.
        _[#label] Auto-labeled footnote.

    The leading underscore syntax (earlier dropped because
    ``.. _[1]:`` was too verbose) is a useful reminder that footnotes
    are hyperlink targets.

  - Minimal syntax: remove the ".. [" and "]", prefix a "_", and
    suffix a "."::

        _1. Footnote 1.
        _#. Auto-numbered footnote.
        _#label. Auto-labeled footnote.

                 ``_1.``, ``_#.``, and ``_#label.`` are markers,
                 like list markers.

    Footnotes could be rendered something like this in HTML
    
        | 1. This is a footnote.  The brackets could be dropped
        |    from the label, and a vertical bar could set them
        |    off from the rest of the document in the HTML.
  
    Two-way hyperlinks on the footnote marker ("1." above) would also
    help to differentiate footnotes from enumerated lists.
  
    If converted to endnotes (by a directive/transform), a horizontal
    half-line might be used instead.  Page-oriented output formats
    would typically use the horizontal line for true footnotes.

+ Footnote references::

  - Current syntax::

        [1]_, [#]_, [#label]_

  - Minimal syntax to match the minimal footnote syntax above::

        1_, #_, #label_

    As a consequence, pure-numeric hyperlink references would not be
    possible; they'd be interpreted as footnote references.

+ Citation references: no change is proposed from the current footnote
  reference syntax::

      [GVR2001]_

+ Citations:

  - Current syntax (footnote syntax)::

        .. _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
           http://www.python.org/doc/

  - Possible new syntax::

        _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
                   http://www.python.org/doc/

        _[DJG2002]
            Docutils: Python Documentation Utilities project; Goodger et
            al.; http://docutils.sourceforge.net/

    Without the ".. " marker, subsequent lines would either have to
    align as in one of the above, or we'd have to allow loose alignment
    (I'd rather not)::

        _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
            http://www.python.org/doc/

I propose adopting the "minimal" syntax for footnotes and footnote
references, and adding citations and citation references to
reStructuredText's repertoire. The current footnote syntax for
citations is better than the alternatives given.

-- 
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 mwh@python.net  Fri Mar  1 09:36:09 2002
From: mwh@python.net (Michael Hudson)
Date: 01 Mar 2002 09:36:09 +0000
Subject: [Doc-SIG] some ideas for reStructuredText & document model
In-Reply-To: David Goodger's message of "Thu, 28 Feb 2002 22:35:58 -0500"
References: <B8A4614D.1F55A%goodger@users.sourceforge.net>
Message-ID: <2mlmdczl2u.fsf@starship.python.net>

David Goodger <goodger@users.sourceforge.net> writes:

> What's this? Garth the yes-man? Strange days.
> 
> [David]
> >> - Render footnote references as superscripts without "[]"?
> 
> [Garth
> > This is where you start wanting to use XHTML/CSS.
> 
> My HTML Writer uses CSS1 extensively, but only HTML 4.01. Is XHTML
> support ready for prime time?

So long as you're careful about your HTML, use lower case tags and
write "<br />" instead of "<br>", you won't miss XHTML by much, in my
limited experience.

Kind of the point of XHTML is that browsers already support it by
accident :)

Cheers,
M.

-- 
  I never realized it before, but having looked that over I'm certain
  I'd rather have my eyes burned out by zombies with flaming dung
  sticks than work on a conscientious Unicode regex engine.
                                             -- Tim Peters, 3 Dec 1998


From tony@lsl.co.uk  Fri Mar  1 10:19:06 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Fri, 1 Mar 2002 10:19:06 -0000
Subject: [Doc-SIG] Reworking Footnotes
In-Reply-To: <B8A461DE.1F55B%goodger@users.sourceforge.net>
Message-ID: <001001c1c10a$848de510$545aa8c0@lslp862.int.lsl.co.uk>

First off, I'm glad you want to keep the "citation" form as::

     For more information refer to [GVR2001]_.

     .. _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
        http://www.python.org/doc/

since I like that.


David Goodger wrote:
> Footnotes would be limited to numerical labels:
> manual ("1") and auto-numbered (anonymous "#", named "#label").

I have no problem with regarding footnotes as distinct from citations,
and limiting them to numeric (although I've always like using little
symbols when doing "real" text processing!).

I can also see the usefulness in allowing them to be distinguished for
presentation purposes.

> The footnote is the only explicit markup construct (starts with ".. ")
> that directly translates to a visible body element.  I've always been
> a little bit uncomfortable with the ".. " marker for footnotes because
> of this; ".. " has a connotation of "special", but footnotes aren't
> especially "special".

Hmm - we obviously differed in what we thought ".." meant, but so it
goes.

However, I think easier with examples, so let's create one::

    Fans of Terry Pratchett are perhaps more likely to use
    footnotes [1]_ in their own writings than other people
    [2]_. Of course, in *general*, one only sees footnotes
    in academic or technical writing - it's use in fiction
    and letter writing is not normally considered good
    style [4]_, particularly in emails (not a medium that
    lends itself to footnotes).

    .. [1] That is, little bits of referenced text at the
       bottom of the page.
    .. [2] Because Terry himself does, of course [3]_
    .. [3] Although he has the distinction of being
       *funny* when he does it, and his fans don't always
       achieve that aim.
    .. [4] Presumably because it detracts from linear
       reading of the text - this is, of course, the point.

and look at it with the second syntax proposal:

    Fans of Terry Pratchett are perhaps more likely to use
    footnotes [1]_ in their own writings than other people
    [2]_. Of course, in *general*, one only sees footnotes
    in academic or technical writing - it's use in fiction
    and letter writing is not normally considered good
    style [4]_, particularly in emails (not a medium that
    lends itself to footnotes).

    _[1] That is, little bits of referenced text at the
         bottom of the page.
    _[2] Because Terry himself does, of course [3]_
    _[3] Although he has the distinction of being
         *funny* when he does it, and his fans don't always
         achieve that aim.
    _[4] Presumably because it detracts from linear
         reading of the text - this is, of course, the point.

(I note here that if I have gotten the indentation of the footnotes
themselves correct, this is clearly not as nice. And if the indentation
should be to the left margin instead, I like that even less).

and the third (new) proposal:

    Fans of Terry Pratchett are perhaps more likely to use
    footnotes 1_ in their own writings than other people
    2_. Of course, in *general*, one only sees footnotes
    in academic or technical writing - it's use in fiction
    and letter writing is not normally considered good
    style 4_, particularly in emails (not a medium that
    lends itself to footnotes).

    _1. That is, little bits of referenced text at the
        bottom of the page.
    _2. Because Terry himself does, of course 3_
    _3. Although he has the distinction of being
        *funny* when he does it, and his fans don't always
        achieve that aim.
    _4. Presumably because it detracts from linear
        reading of the text - this is, of course, the point.

I think I don't, in practice, mind the targets too much (the use of a
dot after the number helps a lot here), but I do have a problem with the
body text, in that I don't naturally separate out the footnotes as
different than the rest of the text - instead I keep wondering why there
are numbers interspered in the text. The use of brackets around the
numbers ([ and ]) made me somehow parse the footnote references as
"odd" - i.e., not part of the body text - and thus both easier to skip,
and also (paradoxically) easier to pick out so that I could follow them.

Thus, for the moment (and as always susceptable to argument), I'd say -1
on the new form of footnote reference (i.e., I much prefer the existing
``[1]_`` over the proposed ``1_``), and ambivalent over the proposed
target change.

That leaves David's problem of wanting to distinguish footnotes and
citations - and the only thing I can propose there is that footnotes are
numeric or # and citations are not (which, as a human being, I can
probably cope with!).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
.. "equal" really means "in some sense the same, but maybe not
.. the sense you were hoping for", or, more succinctly, "is
.. confused with". (Gordon McMillan, Python list, Apr 1998)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)




From Paul.Moore@atosorigin.com  Fri Mar  1 10:35:28 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Fri, 1 Mar 2002 10:35:28 -0000
Subject: [Doc-SIG] Reworking Footnotes
Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B221@UKRUX002.rundc.uk.origin-it.com>

From: Tony J Ibbs (Tibs) [mailto:tony@lsl.co.uk]
> I think I don't, in practice, mind the targets too much
> (the use of a dot after the number helps a lot here),
> but I do have a problem with the body text, in that I
> don't naturally separate out the footnotes as different
> than the rest of the text - instead I keep wondering why
> there are numbers interspered in the text. The use of
> brackets around the numbers ([ and ]) made me somehow
> parse the footnote references as "odd" - i.e., not part
> of the body text - and thus both easier to skip, and also
> (paradoxically) easier to pick out so that I could follow
> them.

I agree with this entirely. I think the current footnote syntax ``[1]_`` is
*exactly* the right balance of distinctness vs unobtrusiveness. I very
definitely don't think this should change.

On the target change, it doesn't matter much to me.

> Thus, for the moment (and as always susceptable to
> argument), I'd say -1 on the new form of footnote
> reference (i.e., I much prefer the existing ``[1]_`` over
> the proposed ``1_``), and ambivalent over the proposed
> target change.

Exactly.

> That leaves David's problem of wanting to distinguish
> footnotes and citations - and the only thing I can propose
> there is that footnotes are numeric or # and citations are
> not (which, as a human being, I can probably cope with!).

I can (sort-of) see the value in distinguishing footnotes and citations. As
a Pratchett fan (:-)) I'd probably use footnotes, but not so much citations.
So I don't have much of a view on citations. But I suspect that using some
form of DWIM [1]_ which distinguishes footnotes and citations based on the
style of the reference (footnote is numeric or #, others are citation) would
work fine in practice.

  _1. [2]_ Do What I Mean - is that a common term in Python
      circles? I picked it up from Perl...
  _2. Just trying out the new form. Hmm, feels OK...


Paul.


From tony@lsl.co.uk  Fri Mar  1 11:30:46 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Fri, 1 Mar 2002 11:30:46 -0000
Subject: [Doc-SIG] Reworking Footnotes
In-Reply-To: <001001c1c10a$848de510$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <001101c1c114$87cde950$545aa8c0@lslp862.int.lsl.co.uk>

More on footnote forms.

Whilst only one datum [1]_, I note that I've now finished reading my
email fix for the day, and in both the Python and HPV (human powered
vehicle) lists, people writing email tend to compose footnotes as::

   Here is some text, with a footnote [1] - note that
   these are always numerical (although Michael Hudson
   is about the only person I've ever seen to use "0"
   as the footnote number!)

   [1] and here is the footnote itself.

Given I believe there to be little overlap between these two (sets of)
email lists (!), and given I've also seen this form elsewhere (the Terry
Pratchett newsgroup *does* spring to mind!), it must surely be a
significant datum.

Clearly [2]_ this is a form people are used to, and thus we should
consider it strongly (in the same way that the usage of ``*..*`` to mean
emphasis was taken partly from email practise).

Equally clearly, there is something "magical" for people in the use of a
similar form (i.e., ``[1]``) for both footnote reference and footnote
target - it seems natural to keep them similar.

reST is already pushing it a *little* bit by requiring the footnote
indicators to bear extra markup beyond the square brackets - but we can
justify that with some fast talking (mainly because otherwise,
particularly in Python-describing text, we lose easy use of square
brackets for other purposes).

I think that this established plaintext usage leads me to strongly
believe we should retain square brackets at both ends of a footnote. The
markup of the reference end (a single trailing underscore) seems about
as minimal as we can get away with. The markup of the target end depends
on how one envisages the thing - if ".." means "I am a target" (as I
tend to see it), then that's good, but one can also argue that the
"_[1]" syntax has a neat symmetry with the footnote reference itself, if
one wishes (in which case ".." presumably means "hidden/special" as
David seems to think, which is why one needs a ".." *and* a leading
underline for hyperlink targets [3]_.

Has anyone come across any other pre-existing plaintext representation
for footnotes?

.. [1] That is, the fact of it all being email is
   singular - clearly the *instances* of usage are
   not.

.. [2] Is that like saying "obviously", which normally
   means "not at all obviously, but I can't be bothered
   to explain or justify"?

.. [3] The use of *two* leading underscores for anounymous
   hyperlinks is then an oddity to be learnt separately,
   but that was discussed another time, and I can cope
   with the occasional oddity.

Tibs
--
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  Sat Mar  2 02:30:11 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Fri, 01 Mar 2002 21:30:11 -0500
Subject: [Doc-SIG] "Topic" (was Re: some ideas for reStructuredText & document model)
In-Reply-To: <B8A45FEA.1F558%goodger@users.sourceforge.net>
Message-ID: <B8A5A362.1F652%goodger@users.sourceforge.net>

Two nights ago I wrote:
>> - Add a "sidebar" element to the DTD? Like a generic admonition or
>>   floating mini-section. Useful for TOC, system messages section,
>>   abstract, etc.

I further explained the idea last night, in terms of DocBook's
"SimpleSect". Tony Ibbs wrote back to me:

[Tony]
> When you say "sidebar", I think of text run down the side of the main
> body of text, essentially in a figure. It's still not entirely clear to
> me if that's what you mean by the term.

That's not my intended meaning, and I apologize for the misleading term.
Similarly to a literal "sidebar", the construct doesn't fall into the
strict section-subsection hierarchy, but it's not meant to be floating
or rendered along the side (although it could be). I don't like the
DocBook term "SimpleSect" at all (many DocBook names are similar:
gratuitously verbose and abbreviated at the same time). Racking my
brains (lightly) for another term, I recall one I came up with for a
client's documentation, "topic". Yes, that's better I think.

>> - SimpleSects...
> 
> I still don't understand the purpose of these, unless they are
> essentially text in a "figure".

Essentially, yes. I imagine rendering them offset from the rest of the text
somehow, perhaps indented, perhaps in a box or with a different-coloured
background.

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

So, "topic" it is. I've reworked the DTD's structural model::

    <!ENTITY % structure.model
      " ( ( (%body.elements; | topic)+,
            (transition, (%body.elements; | topic)+ )*,
            (%structural.elements;)* )
        | (%structural.elements;)+ ) ">

This model is rather imposing but necessarily so. It is used in the
"document" and "section" elements' content models, after their titles
etc. In essence, it says that each document or section contains either:

- multiple body elements and/or topics, optionally interspersed with
  transitions (but transitions cannot occur at the beginning or end, nor
  may there be two transitions in a row), followed by zero or more
  sections; or

- one or more sections (whose contents are recursively the same as this
  model).

There's currently no way to directly create a "topic" in reStructuredText,
although it would be easy to create a directive to do so. I see them being
generated by the processing system for various purposes.

-- 
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  Sat Mar  2 02:58:11 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Fri, 01 Mar 2002 21:58:11 -0500
Subject: [Doc-SIG] Footnotes with symbols (was: Reworking Footnotes)
In-Reply-To: <001001c1c10a$848de510$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <B8A5A9F2.1F654%goodger@users.sourceforge.net>

Tony J Ibbs (Tibs) wrote:
> I have no problem with regarding footnotes as distinct from citations,
> and limiting them to numeric (although I've always like using little
> symbols when doing "real" text processing!).

That suggests a good idea: how about, in addition to auto-numbered
footnotes, we add "auto-symbol" footnotes? They'd have a syntax like::

    Here's an auto-symbol reference [*]_.

    .. _[*] Here's the footnote itself (modulo any syntax changes
       yet to come).

I like symbols for footnotes too. The Chicago Manual of Style lists the
following symbols for "Note Reference Marks" (section 12.51 in the 14th
edition): asterisk/star ("*"), dagger, double dagger, section mark,
parallels ("||"), number sign ("#"). For more symbols, it suggests using
doubles and triples of these symbols, ("**" etc.) in the same sequence, but
I'm sure we could come up with some more interesting glyphs.

More "gilding on the lily" perhaps, but I like it!

-- 
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  Sat Mar  2 03:49:54 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Fri, 01 Mar 2002 22:49:54 -0500
Subject: [Doc-SIG] Reworking Footnotes
In-Reply-To: <001001c1c10a$848de510$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <B8A5B611.1F657%goodger@users.sourceforge.net>

Thanks, Tony, for the excellent examples [*]_. Concrete examples
really help.

.. [*] I recently read Pratchett & Gaiman's *Good Omens*, which was
   moderately entertaining [*]_, so I know what you're talking about.

.. [*] (Just trying out the proposed symbol form here.)

   I cannot fully appreciate humorous fiction though; I much prefer
   real-time audio or video comedy. Perhaps it's due to how I read
   prose; there's a lack of what Steve Martin calls "Thai Ming" [*]_
   [*]_.

.. [*] Timing.

   Get it? :-D

.. [*] I'll add a note to the spec about the care that must be taken
   with the order of footnotes and references when footnote references
   are added inside footnotes. It's confusing; they can easily get out
   of sync.

I will implement the new "citation" and "citation_reference" elements
as discussed. I think they encapsulate a useful distinction from
footnotes.

[Tony]
> Thus, for the moment (and as always susceptable to argument), I'd say -1
> on the new form of footnote reference (i.e., I much prefer the existing
> ``[1]_`` over the proposed ``1_``), and ambivalent over the proposed
> target change.

[Paul]
> I think the current footnote syntax ``[1]_`` is *exactly* the right
> balance of distinctness vs unobtrusiveness. I very definitely don't
> think this should change.

I agree. The reference syntax will stay as is, and I'll let the target
syntax percolate through my ganglia for a while.

[Paul]
> _1. [2]_ Do What I Mean - is that a common term in Python
>     circles? I picked it up from Perl...

It exists in all computing circles, all the way down to the mythical ideal
CPU with a single instruction: "DWIM". Programs written for this CPU vary
only in length, if that. (A future version of this CPU will have a second
instruction: "NWIS" [Not What I Say]. Alas, it remains beyond current
technology.)

[Tony, on the "[1]" form and actual usage in email]
> Clearly [2]_ this is a form people are used to, and thus we should
> consider it strongly (in the same way that the usage of ``*..*`` to mean
> emphasis was taken partly from email practise).
> 
> Equally clearly, there is something "magical" for people in the use of a
> similar form (i.e., ``[1]``) for both footnote reference and footnote
> target - it seems natural to keep them similar.

Good points.

> I think that this established plaintext usage leads me to strongly
> believe we should retain square brackets at both ends of a footnote. The
> markup of the reference end (a single trailing underscore) seems about
> as minimal as we can get away with. The markup of the target end depends
> on how one envisages the thing - if ".." means "I am a target" (as I
> tend to see it), then that's good, but one can also argue that the
> "_[1]" syntax has a neat symmetry with the footnote reference itself, if
> one wishes (in which case ".." presumably means "hidden/special" as
> David seems to think, which is why one needs a ".." *and* a leading
> underline for hyperlink targets [3]_.

Also good points, and a good summary of the thinking process that has
resulted in the current syntax. It's the art of balancing -- nay, of
juggling! It certainly helps that there are multiple brains to cushion
the impact whenever a juggling pin is missed [*]_.

.. [*] I do love these grotesque mixed metaphors!

-- 
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 garth@deadlybloodyserious.com  Mon Mar  4 00:50:35 2002
From: garth@deadlybloodyserious.com (Garth Kidd)
Date: Mon, 4 Mar 2002 11:50:35 +1100
Subject: [Doc-SIG] some ideas for reStructuredText & document model
In-Reply-To: <B8A4614D.1F55A%goodger@users.sourceforge.net>
Message-ID: <000001c1c316$99e98780$4600800a@gkiddlap>

> What's this? Garth the yes-man? Strange days.

I don't have the time to argue. :) 
 
> My HTML Writer uses CSS1 extensively, but only HTML 4.01. Is 
> XHTML support ready for prime time?

Getting there, from what I here. If you're already using decent HTML and
CSS together, XHTML is either not that big a step or not that necessary
a step, depending on how you look at it. :) 

>>> - Make footnotes two-way, GNU-style? What if there are multiple
>>>   references to a single footnote?
>> 
>> Ha! I told you that'd happen! :)
> 
> Did you? And did you have any useful suggestions at the time? ;)

My memory is fading, so I might well get it wrong, but I *think* I was
arguing for a unified namespace for footnotes and link targets, such
that auto-numbered footnotes could be named and normal links could be
used to target them. Useful enough? :P

Regards,
Garth.



From tony@lsl.co.uk  Mon Mar  4 10:12:32 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Mon, 4 Mar 2002 10:12:32 -0000
Subject: [Doc-SIG] Reworking Footnotes
In-Reply-To: <B8A5B611.1F657%goodger@users.sourceforge.net>
Message-ID: <003301c1c365$19744cd0$545aa8c0@lslp862.int.lsl.co.uk>

David Goodger wrote:
>    I cannot fully appreciate humorous fiction though; I much prefer
>    real-time audio or video comedy. Perhaps it's due to how I read
>    prose; there's a lack of what Steve Martin calls "Thai Ming" [*]_
>    [*]_.

Hmm. Or how text-centred one is - much of my own sense of humour is
based around word-play as such, which means that text-on-the-page works
well (and also means that the Goons, Firesign Theater, etc. are also
appreciated), and also means that other people often don't see why I
think something funny.

Of course, it may also be that everyone's taste is different - many of
the authors cited as "you'll love this if you love Pratchett" leave me
cold, and I can imagine the phenomenum working the other way around as
well.

> .. [*] Timing.
>
>    Get it? :-D
>
> .. [*] I'll add a note to the spec about the care that must be taken
>    with the order of footnotes and references when footnote references
>    are added inside footnotes. It's confusing; they can easily get out
>    of sync.

Hmm. I think that this example is itself enough to warn people to be
very careful about using autogenerated footnotes (of whatever sort - the
"*" could equally well be "#") in an other-than-trivial manner - two
anonymous footnotes in a row are confusing! On the other hand, I also
think it's relatively unlikely - I'd be much more likely to attach tags
to things if they are that complex. On the other other hand, if we're
going to allow generated footnote indices, I don't see a way to limit
it, so we'll have to cope.

> Also good points, and a good summary of the thinking process that has
> resulted in the current syntax. It's the art of balancing -- nay, of
> juggling! It certainly helps that there are multiple brains to cushion
> the impact whenever a juggling pin is missed [*]_.
>
> .. [*] I do love these grotesque mixed metaphors!

And the man says he doesn't like prose humour. Ho hum.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
A single element tuple needs a trailing comma, and an empty tuple needs
brackets to distinguish it from a coffee stain. - Duncan Booth, in his
intro to Python for the ACCU Spring 2002 conference
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)




From fdrake@acm.org  Tue Mar  5 04:24:13 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Mon,  4 Mar 2002 23:24:13 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020305042413.3598528696@beowolf.fdrake.net>

The development version of the documentation has been updated:

    http://python.sourceforge.net/devel-docs/

Minor accumulated updates.


From rjones@ekit-inc.com  Wed Mar  6 05:43:23 2002
From: rjones@ekit-inc.com (Richard Jones)
Date: Wed, 6 Mar 2002 16:43:23 +1100
Subject: [Doc-SIG] Re: [Structuredtext-develop] docutils teaser
In-Reply-To: <B8A31B46.1F46C%goodger@users.sourceforge.net>
References: <B8A31B46.1F46C%goodger@users.sourceforge.net>
Message-ID: <200203060543.FAA08503@crown.off.ekorp.com>

On Thu, 28 Feb 2002 15:24, David Goodger wrote:
> I've made a lot of progress on my HTML Writer. Everything works, if crudely
> at times. I don't have time to check in the files to CVS right now, but
> here's a teaser. Check out these documents:
>
> - http://structuredtext.sourceforge.net/spec/test.html (published from
>   source at http://structuredtext.sourceforge.net/tools/test.txt)

... I'm still getting

Reporter: ERROR (3) Unknown directive type "image" at line 629.

.. yet your example has an image used in it... help? :)



    Richard


From goodger@users.sourceforge.net  Thu Mar  7 02:18:32 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 06 Mar 2002 21:18:32 -0500
Subject: [Doc-SIG] Re: [Structuredtext-develop] docutils teaser
In-Reply-To: <200203070208.CAA12491@crown.off.ekorp.com>
Message-ID: <B8AC3827.1F9C0%goodger@users.sourceforge.net>

Richard Jones wrote:
> Fixed in CVS. Was an import that didn't handle ReST being installed.

Because of the two-project split, some fancy dancing is required in imports
(because I don't work on the projects in their "installed" state). I missed
a few steps. Thanks for finding them, Richard.

That's just one of the many reasons I'm eager to merge the projects. I'll
concentrate on fixing docs and essentials, then release, then merge to form
"Docutils 0.1" ASAP.

-- 
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 fdrake@acm.org  Wed Mar 13 05:16:57 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Wed, 13 Mar 2002 00:16:57 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020313051657.CF40428696@beowolf.fdrake.net>

The development version of the documentation has been updated:

    http://python.sourceforge.net/devel-docs/

Mostly minor updates; closed a few bug reports.


From fdrake@acm.org  Thu Mar 14 23:09:19 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Thu, 14 Mar 2002 18:09:19 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020314230919.8838E18ECEF@grendel.zope.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/maint-docs/

Current version of docs in preparation for the 2.2.1 candidate.



From fdrake@acm.org  Mon Mar 18 18:33:30 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Mon, 18 Mar 2002 13:33:30 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020318183330.4F9B618ED52@grendel.zope.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/maint-docs/

Documentation for 2.2.1 release candidate 1.


From fdrake@acm.org  Sat Mar 23 22:24:21 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Sat, 23 Mar 2002 17:24:21 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020323222421.8D11C28696@beowolf.fdrake.net>

The development version of the documentation has been updated:

    http://python.sourceforge.net/csstest-docs/

This is a test version of some style changes.  The changes are
localized to the navigation areas (I hope!), and probably only work
for the browsers with the most-compliant CSS2 implementations.

I've tested this with Mozilla 0.9.9 and MSIE 6 -- and it only worked
in Mozilla.  This isn't going to be usable until more browsers support
the CSS needed to make this work, but I've never seen this done
without frames before now (though I've played with the idea several
times over the last couple of years).

If you can't tell what the changes are, visit a page that needs to be
scrolled to see the whole thing, and try scrolling it!

Comments are welcome; send to python-docs@python.org.


From goodger@users.sourceforge.net  Sun Mar 24 00:07:40 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sat, 23 Mar 2002 19:07:40 -0500
Subject: [Doc-SIG] [development doc updates]
In-Reply-To: <20020323222421.8D11C28696@beowolf.fdrake.net>
Message-ID: <B8C282FB.20501%goodger@users.sourceforge.net>

Fred L. Drake wrote:
> This is a test version of some style changes.  The changes are
> localized to the navigation areas (I hope!), and probably only work
> for the browsers with the most-compliant CSS2 implementations.

Cool!  It worked in MSIE 5.1.3 on MacOS 8.6, except that about one line's
worth of the scrolling page text showed through above the navigation bar
(between the window's title bar and the navigation bar).

-- 
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 barry@zope.com  Sun Mar 24 01:47:14 2002
From: barry@zope.com (Barry A. Warsaw)
Date: Sat, 23 Mar 2002 20:47:14 -0500
Subject: [Doc-SIG] Re: [Python-Dev] [development doc updates]
References: <20020323222421.8D11C28696@beowolf.fdrake.net>
Message-ID: <15517.12322.143006.15447@anthem.wooz.org>

>>>>> "Fred" == Fred L Drake <fdrake@acm.org> writes:

    Fred> If you can't tell what the changes are, visit a page that
    Fred> needs to be scrolled to see the whole thing, and try
    Fred> scrolling it!

Fred!  Very very cool.  Since I'm using the one true browser <0.9.9
wink> this works great.  Would this work with a side bar a la
ht2html's output?

-Barry


From fdrake@acm.org  Sun Mar 24 04:42:00 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Sat, 23 Mar 2002 23:42:00 -0500
Subject: [Doc-SIG] Re: [Python-Dev] [development doc updates]
In-Reply-To: <15517.12322.143006.15447@anthem.wooz.org>
References: <20020323222421.8D11C28696@beowolf.fdrake.net>
 <15517.12322.143006.15447@anthem.wooz.org>
Message-ID: <15517.22808.837156.773060@grendel.zope.com>

Barry A. Warsaw writes:
 > Fred!  Very very cool.  Since I'm using the one true browser <0.9.9
 > wink> this works great.  Would this work with a side bar a la
 > ht2html's output?

I was wondering about that myself!  Haven't had time to play with that
yet, though.  I still need to a file a bug with Mozilla that I noticed
while working with this.  Erin was up late tonight, though, thanks to
her being sick & taking a long nap this afternoon.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation


From fdrake@acm.org  Sun Mar 24 18:58:35 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Sun, 24 Mar 2002 13:58:35 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020324185835.2D25928696@beowolf.fdrake.net>

The development version of the documentation has been updated:

    http://python.sourceforge.net/csstest-docs/

This is the experimental formatting for the documentation.

This version should work better for Opera users; it should work fine
for Opera 6, and works (slightly) better than it did for Opera 5.
There's probably no change for other browsers.


From fdrake@acm.org  Mon Mar 25 20:37:41 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Mon, 25 Mar 2002 15:37:41 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020325203741.2CD5118EAD0@grendel.zope.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/maint-docs/

Documentation for Python 2.2.1 release candidate 2.


From goodger@users.sourceforge.net  Tue Mar 26 05:37:52 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Tue, 26 Mar 2002 00:37:52 -0500
Subject: [Doc-SIG] New PEP: reStructuredText Standard Docstring Format
Message-ID: <B8C5735F.2063C%goodger@users.sourceforge.net>

Please comment on this new PEP.  I intend to post it to comp.lang.python &
python-dev later this week, but wanted the Doc-SIG's reaction first.  Any
chance at consensus?  Do the "docstring format goals" truly reflect the
goals of the group?  Any questions or answers to add to the Q & A?  Any
glaring omissions?

Barry, could I get a PEP number please?

Thank you.

-- 
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


PEP: 
Title: reStructuredText Standard Docstring Format
Version: $Revision$
Last-Modified: $Date$
Author: goodger@users.sourceforge.net (David Goodger)
Discussions-To: doc-sig@python.org
Status: Draft
Type: Informational
Created: 2002-03-25
Post-History: 


Abstract

    This PEP proposes that the reStructuredText [1]_ markup be adopted
    as the standard markup format for plaintext documentation in
    Python docstrings, and (optionally) for PEPs and ancillary
    documents as well.  reStructuredText is a rich and extensible yet
    easy-to-read, what-you-see-is-what-you-get plaintext markup
    syntax.

    Only the low-level syntax of docstrings is addressed here.  This
    PEP is not concerned with docstring semantics or processing at
    all.


Goals

    These are the generally accepted goals for a docstring format, as
    discussed in the Python Documentation Special Interest Group
    (Doc-SIG) [2]_:

    1. It must be easy to type with any standard text editor.

    2. It must be readable to the casual observer.

    3. It must not need to contain information which can be deduced
       from parsing the module.

    4. It must contain sufficient information (structure) so it can be
       converted to any reasonable markup format.

    5. It must be possible to write a module's entire documentation in
       docstrings, without feeling hampered by the markup language.

    [[Are these in fact the goals of the Doc-SIG members?  Anything to
    add?]]

    reStructuredText meets and exceeds all of these goals, and sets
    its own goals as well, even more stringent.  See "Features" below.

    The goals of this PEP are as follows:

    1. To establish a standard docstring format by attaining
       "accepted" status (Python community consensus; BDFL
       pronouncement). Once reStructuredText is a Python standard, all
       effort can be focused on tools instead of arguing for a
       standard.  Python needs a standard set of documentation tools.

    2. To address any related concerns raised by the Python community.

    3. To encourage community support.  As long as multiple competing
       markups are out there, the development community remains
       fractured.  Once a standard exists, people will start to use
       it, and momentum will inevitably gather.

    4. To consolidate efforts from related auto-documentation
       projects.  It is hoped that interested developers will join
       forces and work on a joint/merged/common implementation.

    5. (Optional.)  To adopt reStructuredText as the standard markup
       for PEPs.  One or both of the following strategies may be
       applied:

       a) Keep the existing PEP section structure constructs (one-line
          section headers, indented body text).  Subsections can either
          be forbidden or supported with underlined headers in the
          indented body text.

       b) Replace the PEP section structure constructs with the
          reStructuredText syntax.  Section headers will require
          underlines, subsections will be supported out of the box, and
          body text need not be indented (except for block quotes).

       Support for RFC822 headers will be added to the
       reStructuredText parser (unambiguous given a specific context:
       the first contiguous block of a PEP document).  It may be
       desired to concretely specify what over/underline styles are
       allowed for PEP section headers, for uniformity.

    6. (Optional.)  To adopt reStructuredText as the standard markup
       for README-type files and other standalone documents in the
       Python distribution.


Rationale

    The __doc__ attribute is called a documentation string, or
    docstring.  It is often used to summarize the interface of the
    module, class or function.  The lack of a standard syntax for
    docstrings has hampered the development of standard tools for
    extracting docstrings and transforming them into documentation in
    standard formats (e.g., HTML, DocBook, TeX).  There have been a
    number of proposed markup formats and variations, and many tools
    tied to these proposals, but without a standard docstring format
    they have failed to gain a strong following and/or floundered
    half-finished.

    The adoption of a standard will, at the very least, benefit
    docstring processing tools by preventing further "reinventing the
    wheel".

    Throughout the existence of the Doc-SIG, consensus on a single
    standard docstring format has never been reached.  A lightweight,
    implicit markup has been sought, for the following reasons (among
    others):

    1. Docstrings written within Python code are available from within
       the interactive interpreter, and can be 'print'ed.  Thus the
       use of plaintext for easy readability.

    2. Programmers want to add structure to their docstrings, without
       sacrificing raw docstring readability.  Unadorned plaintext
       cannot be transformed ('up-translated') into useful structured
       formats.

    3. Explicit markup (like XML or TeX) is widely considered
       unreadable by the uninitiated.

    4. Implicit markup is aesthetically compatible with the clean and
       minimalist Python syntax.

    Proposed alternatives have included:

    - XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_

      XML and SGML are explicit, well-formed meta-languages suitable
      for all kinds of documentation.  XML is a variant of SGML.  They
      are best used behind the scenes, because they are verbose,
      difficult to type, and too cluttered to read comfortably as
      source.  DocBook, HTML, and XHTML are all applications of SGML
      and/or XML, and all share the same basic syntax and the same
      shortcomings.

    - TeX [8]_

      TeX is similar to XML/SGML in that it's explicit, not very easy
      to write, and not easy for the uninitiated to read.

    - Perl POD [9]_

      Most Perl modules are documented in a format called POD -- Plain
      Old Documentation.  This is an easy-to-type, very low level
      format with strong integration with the Perl parser.  Many tools
      exist to turn POD documentation into other formats: info, HTML
      and man pages, among others.  However, the POD syntax takes
      after Perl itself in terms of readability.

    - JavaDoc [10]_

      Special comments before Java classes and functions serve to
      document the code.  A program to extract these, and turn them
      into HTML documentation is called javadoc, and is part of the
      standard Java distribution.  However, the only output format
      that is supported is HTML, and JavaDoc has a very intimate
      relationship with HTML, using HTML tags for most markup.  Thus
      it shares the readability problems of HTML.

    - Setext [11]_, StructuredText [12]_

      Early on, variants of Setext (Structure Enhanced Text),
      including Zope Corp's StructuredText, were proposed for Python
      docstring formatting.  Hereafter these variants will
      collectively be call 'STexts'.  STexts have the advantage of
      being easy to read without special knowledge, and relatively
      easy to write.

      Although used by some (including in most existing Python
      auto-documentation tools), until now STexts have failed to
      become standard because:

      - STexts have been incomplete.  Lacking "essential" constructs
        that people want to use in their docstrings, STexts are
        rendered less than ideal.  Note that these "essential"
        constructs are not universal; everyone has their own
        requirements.

      - STexts have been sometimes surprising.  Bits of text are
        marked up unexpectedly, leading to user frustration.

      - SText implementations have been buggy.

      - Most STexts have have had no formal specification except for
        the implementation itself.  A buggy implementation meant a
        buggy spec, and vice-versa.

      - There has been no mechanism to get around the SText markup
        rules when a markup character is used in a non-markup context.

    Proponents of implicit STexts have vigorously opposed proposals
    for explicit markup (XML, HTML, TeX, POD, etc.), and the debates
    have continued off and on since 1996 or earlier.

    reStructuredText is a complete revision and reinterpretation of
    the SText idea, addressing all of the problems listed above.


Features

    Rather than repeating or summarizing the extensive
    reStructuredText spec, please read the originals available from
    http://structuredtext.sourceforge.net/spec/ (.txt & .html files).
    Reading the documents in following order is recommended:

    - An Introduction to reStructuredText [13]_

    - Problems With StructuredText [14]_ (optional, if you've used
      StructuredText; it explains many markup decisions made)

    - reStructuredText Markup Specification [15]_

    - A Record of reStructuredText Syntax Alternatives [16]_ (explains
      markup decisions made independently of StructuredText)

    - reStructuredText Directives [17]_

    There is also a "Quick reStructuredText" user reference [18]_.

    A summary of features addressing often-raised docstring markup
    concerns follows:

    - A markup escaping mechanism.

      Backslashes (``\``) are used to escape markup characters when
      needed for non-markup purposes.  However, the inline markup
      recognition rules have been constructed in order to minimize the
      need for backslash-escapes.  For example, although asterisks are
      used for *emphasis*, in non-markup contexts such as "*" or "(*)"
      or "x * y", the asterisks are not interpreted as markup and are
      left unchanged.  For many non-markup uses of backslashes (e.g.,
      describing regular expressions), inline literals or literal
      blocks are applicable; see the next item.

    - Markup to include Python source code and Python interactive
      sessions: inline literals, literal blocks, and doctest blocks.

      Inline literals use ``double-backquotes`` to indicate program
      I/O or code snippets.  No markup interpretation (including
      backslash-escape [``\``] interpretation) is done within inline
      literals.

      Literal blocks (block-level literal text, such as code excerpts
      or ASCII graphics) are indented, and indicated with a
      double-colon ("::") at the end of the preceding paragraph (right
      here -->)::

          if literal_block:
              text = 'is left as-is'
              spaces_and_linebreaks = 'are preserved'
              markup_processing = None

      Doctest blocks begin with ">>> " and end with a blank line.
      Neither indentation nor literal block double-colons are
      required.  For example::

          Here's a doctest block:

          >>> print 'Python-specific usage examples; begun with ">>>"'
          Python-specific usage examples; begun with ">>>"
          >>> print '(cut and pasted from interactive sessions)'
          (cut and pasted from interactive sessions)

    - Markup that isolates a Python identifier: interpreted text.

      Text enclosed in single backquotes is recognized as "interpreted
      text", whose interpretation is application-dependent.  In the
      context of a Python docstring, the default interpretation of
      interpreted text is as Python identifiers.  The text will be
      marked up with a hyperlink connected to the documentation for
      the identifier given.  Lookup rules are the same as in Python
      itself: LGB namespace lookups (local, global, builtin).  The
      "role" of the interpreted text (identifying a class, module,
      function, etc.) is determined implicitly from the namespace
      lookup.  For example::

          class Keeper(Storer):

              """
              Extend `Storer`.  Class attribute `instances` keeps track
              of the number of `Keeper` objects instantiated.
              """

              instances = 0
              """How many `Keeper` objects are there?"""

              def __init__(self):
                  """
                  Extend `Storer.__init__()` to keep track of
                  instances.  Keep count in `self.instances` and data
                  in `self.data`.
                  """
                  Storer.__init__(self)
                  self.instances += 1

                  self.data = []
                  """Store data in a list, most recent last."""

              def storedata(self, data):
                  """
                  Extend `Storer.storedata()`; append new `data` to a
                  list (in `self.data`).
                  """
                  self.data = data

      Each piece of interpreted text is looked up according to the
      local namespace of the block containing its docstring.

    - Markup that isolates a Python identifier and specifies its type:
      interpreted text with roles.

      Although the Python source context reader is designed not to
      require explicit roles, they may be used.  To classify
      identifiers explicitly, the role is given along with the
      identifier in either prefix or suffix form::

          Use :method:`Keeper.storedata` to store the object's data in
          `Keeper.data`:instance_attribute:.

      The syntax chosen for roles is verbose, but necessarily so (if
      anyone has a better alternative, please post it to the Doc-SIG).
      The intention of the markup is that there should be little need
      to use explicit roles; their use is to be kept to an absolute
      minimum.

    - Markup for "tagged lists" or "label lists": field lists.

      Field lists represent a mapping from field name to field body.
      These are mostly used for extension syntax, such as
      "bibliographic field lists" (representing document metadata such
      as author, date, and version) and extension attributes for
      directives (see below).  They may be used to implement docstring
      semantics, such as identifying parameters, exceptions raised,
      etc.; such usage is beyond the scope of this PEP.

      A modified RFC822 syntax is used, with a colon *before* as well
      as *after* the field name.  Field bodies are more versatile as
      well; they may contain multiple field bodies (even nested field
      lists).  For example::

          :Date: 2002-03-22
          :Version: 1
          :Authors:
              - Me
              - Myself
              - I

      Standard RFC822 header syntax cannot be used for this construct
      because it is ambiguous.  A word followed by a colon at the
      beginning of a line is common in written text.  However, with
      the addition of a well-defined context, such as when a field
      list invariably occurs at the beginning of a document (e.g.,
      PEPs and email messages), standard RFC822 header syntax can be
      used.

    - Markup extensibility: directives and substitutions.

      Directives are used as an extension mechanism for
      reStructuredText, a way of adding support for new block-level
      constructs without adding new syntax.  Directives for images,
      admonitions (note, caution, etc.), and tables of contents
      generation (among others) have been implemented.  For example,
      here's how to place an image::

          .. image:: mylogo.png

      Substitution definitions allow the power and flexibility of
      block-level directives to be shared by inline text.  For
      example::

          The |biohazard| symbol must be used on containers used to
          dispose of medical waste.
      
          .. |biohazard| image:: biohazard.png

    - Section structure markup.

      Section headers in reStructuredText use adornment via underlines
      (and possibly overlines) rather than indentation.  For example::

          This is a Section Title
          =======================

          This is a Subsection Title
          --------------------------

          This paragraph is in the subsection.

          This is Another Section Title
          =============================

          This paragraph is in the second section.


Questions & Answers

    Q: Is reStructuredText rich enough?

    A: Yes, it is for most people.  If it lacks some construct that is
       require for a specific application, it can be added via the
       directive mechansism.  If a common construct has been
       overlooked and a suitably readable syntax can be found, it can
       be added to the specification and parser.

    Q: Is reStructuredText *too* rich?

    A: No.

       Since the very beginning, whenever a markup syntax has been
       proposed on the Doc-SIG, someone has complained about the lack
       of support for some construct or other.  The reply was often
       something like, "These are docstrings we're talking about, and
       docstrings shouldn't have complex markup."  The problem is that
       a construct that seems superfluous to one person may be
       absolutely essential to another.

       reStructuredText takes the opposite approach: it provides a
       rich set of implicit markup constructs (plus a generic
       extension mechanism for explicit markup), allowing for all
       kinds of documents.  If the set of constructs is too rich for a
       particular application, the unused constructs can either be
       removed from the parser (via application-specific overrides) or
       simply omitted by convention.

    Q: Why not use indentation for section structure, like
       StructuredText does?  Isn't it more "Pythonic"?

    A: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG
       post:

           I still think that using indentation to indicate sectioning
           is wrong.  If you look at how real books and other print
           publications are laid out, you'll notice that indentation
           is used frequently, but mostly at the intra-section level.
           Indentation can be used to offset lists, tables,
           quotations, examples, and the like.  (The argument that
           docstrings are different because they are input for a text
           formatter is wrong: the whole point is that they are also
           readable without processing.)

           I reject the argument that using indentation is Pythonic:
           text is not code, and different traditions and conventions
           hold.  People have been presenting text for readability for
           over 30 centuries.  Let's not innovate needlessly.

       See "Section Structure via Indentation" in "Problems With
       StructuredText" [14 ]_ for further elaboration.

    Q: Why use reStructuredText for PEPs?  What's wrong with the
       existing standard?

    A: The existing standard for PEPs is very limited in terms of
       general expressibility, and referencing is especially lacking
       for such a reference-rich document type.  PEPs are currently
       converted into HTML, but the results (mostly monospaced text)
       are less than attractive, and most of the value-added potential
       of HTML is untapped.

       Making reStructuredText the standard markup for PEPs will
       enable much richer expression, including support for section
       structure, inline markup, graphics, and tables.  In several
       PEPs there are ASCII graphics diagrams, which are all that
       plaintext documents can support.  Since PEPs are made available
       in HTML form, the ability to include proper diagrams would be
       immediately useful.

       Current PEP practices allow for reference markers in the form
       "[1]" in the text, and the footnotes/references themselves are
       listed in a section toward the end of the document.  There is
       currently no hyperlinking between the reference marker and the
       footnote/reference itself (it would be possible to add this to
       pep2html.py, but the "markup" as it stands is ambiguous and
       mistakes would be inevitable).  A PEP with many references
       (such as this one ;-) requires a lot of flipping back and
       forth.  When revising a PEP, often new references are added or
       unused references deleted.  It is painful to renumber the
       references, since it has to be done in two places and can have
       a cascading effect (insert a single new reference 1, and every
       other reference has to be renumbered; always adding new
       references to the end is suboptimal).  It is easy for
       references to go out of sync.

       PEPs use references for two purposes: simple URL references and
       footnotes.  reStructuredText differentiates between the two.  A
       PEP might contain references like this::

           Abstract

               This PEP proposes a adding frungible doodads [1] to the
               core.  It extends PEP 9876 [2] via the BCA [3]
               mechanism.

           References and Footnotes

               [1] http://www.doodads.org/frungible.html

               [2] PEP 9876, Let's Hope We Never Get Here
                   http://www.python.org/peps/pep-9876.html

               [3] "Bogus Complexity Addition"

       Reference 1 is a simple URL reference.  Reference 2 is a
       footnote containing text and a URL.  Reference 3 is a footnote
       containing text only.  Rewritten using reStructuredText, this
       PEP could look like this::

           Abstract
           ========

           This PEP proposes a adding `frungible doodads`_ to the
           core.  It extends PEP 9876 [#pep9876] via the BCA [#]
           mechanism.

           .. _frungible doodads:
              http://www.doodads.org/frungible.html

           .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here

           __ http://www.python.org/peps/pep-9876.html

           .. [#] "Bogus Complexity Addition"

       URLs and footnotes can be defined close to their references if
       desired, making them easier to read in the source text, and
       making the PEPs easier to revise.  The "References and
       Footnotes" section can be auto-generated with a document tree
       transform.  Footnotes from throughout the PEP would be gathered
       and displayed under a standard header.  If URL references
       should likewise be written out explicitly (in citation form),
       another tree transform could be used.

       URL references can be named ("frungible doodads"), and can be
       referenced from multiple places in the document without
       additional definitions.  When converted to HTML, references
       will be replaced with inline hyperlinks (HTML <A> tags).  The
       two footnotes are automatically numbered, so they will always
       stay in sync.  The first footnote also contains an internal
       reference name, "pep9876", so it's easier to see the connection
       between reference and footnote in the source text.  Named
       footnotes can be referenced multiple times, maintaining
       consistent numbering.

       The "#pep9876" footnote could also be written in the form of a
       citation::

           It extends PEP 9876 [PEP9876]_ ...

           .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here

       Footnotes are numbered, whereas citations use text for their
       references.

    Q: Wouldn't it be better to keep the docstring and PEP proposals
       separate?

    A: The PEP markup proposal is an option to this PEP.  It may be
       removed if it is deemed that there is no need for PEP markup.
       The PEP markup proposal could be made into a separate PEP if
       necessary.  If accepted, PEP 1, PEP Purpose and Guidelines [19]_,
       and PEP 9, Sample PEP Template [20]_ will be updated.

       It seems natural to adopt a single consistent markup standard
       for all uses of plaintext in Python.

    Q: The existing pep2html.py script converts the existing PEP
       format to HTML.  How will the new-format PEPs be converted to
       HTML?

    A: One of the deliverables of the Docutils project [21]_ will be a
       new version of pep2html.py with integrated reStructuredText
       parsing.  The Docutils project will support PEPs with a "PEP
       Reader" component, including all functionality currently in
       pep2html.py (auto-recognition of PEP & RFC references).

    Q: Who's going to convert the existing PEPs to reStructuredText?

    A: A call for volunteers will be put out to the Doc-SIG and
       greater Python communities.  If insufficient volunteers are
       forthcoming, I (David Goodger) will convert the documents
       myself, perhaps with some level of automation.  A transitional
       system whereby both old and new standards can coexist will be
       easy to implement (and I pledge to implement it if necessary).

    Q: Why use reStructuredText for README and other ancillary files?

    A: The same reasoning used for PEPs above applies to README and
       other ancillary files.  By adopting a standard markup, these
       files can be converted to attractive cross-referenced HTML and
       put up on python.org.  Developers of Python projects can also
       take advantage of this facility for their own documentation.


References and Footnotes

    [1] http://structuredtext.sourceforge.net/

    [2] http://www.python.org/sigs/doc-sig/

    [3] http://www.w3.org/XML/

    [4] http://www.oasis-open.org/cover/general.html

    [5] http://docbook.org/tdg/en/html/docbook.html

    [6] http://www.w3.org/MarkUp/

    [7] http://www.w3.org/MarkUp/#xhtml1

    [8] http://www.tug.org/interest.html

    [9] http://www.perldoc.com/perl5.6/pod/perlpod.html

    [10] http://java.sun.com/j2se/javadoc/

    [11] http://docutils.sourceforge.net/mirror/setext.html

    [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage

    [13] An Introduction to reStructuredText
         http://structuredtext.sourceforge.net/spec/introduction.txt

    [14] Problems with StructuredText
         http://structuredtext.sourceforge.net/spec/problems.txt

    [15] reStructuredText Markup Specification
         http://structuredtext.sourceforge.net/spec/reStructuredText.txt

    [16] A Record of reStructuredText Syntax Alternatives
         http://structuredtext.sourceforge.net/spec/alternatives.txt

    [17] reStructuredText Directives
         http://structuredtext.sourceforge.net/spec/directives.txt

    [18] Quick reStructuredText
         http://structuredtext.sourceforge.net/docs/quickref.html

    [19] PEP 1, PEP Guidelines, Warsaw, Hylton
         http://www.python.org/peps/pep-0001.html

    [20] PEP 9, Sample PEP Template, Warsaw
         http://www.python.org/peps/pep-0009.html

    [21] http://docutils.sourceforge.net/

    [22] PEP 216, Docstring Format, Zadka
         http://www.python.org/peps/pep-0216.html


Copyright

    This document has been placed in the public domain.


Acknowledgements

    Some text is borrowed from PEP 216, Docstring Format, by Moshe
    Zadka [22]_.

    Special thanks to all members past & present of the Python Doc-SIG.



Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:



From tony@lsl.co.uk  Tue Mar 26 09:23:46 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Tue, 26 Mar 2002 09:23:46 -0000
Subject: [Doc-SIG] New PEP: reStructuredText Standard Docstring Format
In-Reply-To: <B8C5735F.2063C%goodger@users.sourceforge.net>
Message-ID: <003601c1d4a7$ee463510$545aa8c0@lslp862.int.lsl.co.uk>

Great stuff. Some minor nitpicking (really, that's all it is).

BTW - I haven't copied to Barry Warsaw - please feel free to forward it
explicitly if you feel he needs to follow the details!

1. It *may* be that the aim is, more pedantically, to provide
   the markup syntax for docstrings *when markup is wanted*.

   That is: clearly plain text is always going to be legitimate
   docstring content, and certainly for the near future this will
   be the default. Thus markup is an alternative.

   The start of the document sounds a little, to me, as if it is
   deprecating plain text as docstring content. Of course, that
   may just be me.

2. The example docstrings are not laid out according to the
   normal style - for example::

            class Keeper(Storer):

              """
              Extend `Storer`.  Class attribute `instances`
              keeps track of the number of `Keeper` objects
              instantiated.
              """

   doesn't start with a single summary line, and that single summary
   line (!) isn't on the same line as the opening triple quotes.

   Also, I would argue that the first sentence is redundant - it
   doesn't tell us anything new.

   A better comment would be more like::

            """A useful jacket for lists. (well, OK, one might quibble!)

            The class attribute `instances` is used to keep track
            of the number of `Keeper` objects instantiated.
            """

   (I believe that that layout follows the style guide better, and if
   we're trying to push a PEP, that's a good idea.)

   This comment obviously applies to the other docstrings as well.

3. When discussing field lists, I would separate the point about RFC
headers
   (in PEPs) out - it confuses the matter.

   Strictly speaking, dealing with RFC headers is an extension, and
*that*
   is reasonable enough, but being able to deal with PEPs is only an
   optional aim, so we shouldn't let it "muddy the water" too much in
   the summary.

   Perhaps something more like::

      Standard RFC822 header syntax cannot be used for this construct
      because it is ambiguous.  A word followed by a colon at the
      beginning of a line is common in written text.

          :Note: If this proposal is accepted for representation
          of PEPs, then a PEP-specific extension would be added
          to allow standard RFC822 header syntax in the first
          "block" of the document. This is a sufficiently well-
          defined context that such support would not be a
          problem.

   Or even move the "note" stuff into the question about support
   for PEPs later on in the docment, possibly with a cross reference
   to it from here.

4. In the revamped-PEP examples (both "before" and "after"),
   the text::

        This PEP proposes a adding frungible doodads

   should (I assume) be::

        This PEP proposes adding frungible doodads

5. I note that www.doodads.org claims that frungible.html
   does not exist.

6. I was just thinking about the "should markup and PEPs
   be separate" question when you addressed it (!). So
   that's a good thing.

   Hmm - would it be a good idea to *number* the questions
   (and answers) - it would make it easier to discuss them
   (e.g., Q6 and A6 rather than Q and A).

7. Personally, I probably *would* have separated the issue
   of docstring markup and PEPs, mainly because it makes
   this PEP longer. But I've been wrong before.

8. When the document is finalised, will you also put up a
   version in reST?

Oh - I guess I should address your *specific* questions!

> Any chance at consensus?

I sincerely hope so - certainly none of my points are (so far as I'm
concerned) things to stop it going forwards.

> Do the "docstring format goals" truly reflect the goals
> of the group?

I think they're one good version of them.

> Any questions or answers to add to the Q & A?  Any
> glaring omissions?

Not that spring to my mind. Oh - except that you don't actually point
out that this is all *working*, right now and as of this moment.

(erm - well, your bits anyway. Since we've got my parent's-in-law
visiting, I've even begun work on pydps again, though)

Tibs
--
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 Paul.Moore@atosorigin.com  Tue Mar 26 11:56:36 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Tue, 26 Mar 2002 11:56:36 -0000
Subject: [Doc-SIG] RE: New PEP: reStructuredText Standard Docstring Format
Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B296@UKRUX002.rundc.uk.origin-it.com>

(Third try at this - I'm groping for a way to express my point here...)

I only really have one issue with the document, which is that it reads a
little too much like it's trying to be the "how to write your comments"
section of a programming standard.

Wait - before you start throwing rocks at me, let me explain...

As I was reading it, I had no complaint with any of the details, but there
was this nagging feeling in the back of my mind saying "Why should I agree
to these rules? Even Guido doesn't have the right to tell *me* how to write
my documentation!" There isn't enough emphasis on why using reST in my
docstrings provides *me* with benefit. At the end of the day, we're all
pretty selfish about how we write our code - we document the bits we think
we, personally, might not understand later, and we excuse the areas where we
skip documentation with the excuse that "it's obvious". (OK, maybe it's just
me - but I suspect most people have a little bit of this attitude)

I'd suggest that you add a "Benefits" section, explaining the advantages to
the individual programmer - *not* to the community as a whole - of the
proposal. My characterisation of the benefits would be:

  - The proposed format (reST) is entirely readable in
    plaintext format, and many of the markup forms match
    common usage (e.g., ``*emphasis*``), so there is no
    significant downside to using it (beyond the initial
    learning curve) [1]_
  - Tools will become available in the (hopefully near)
    future, which will allow me to generate HTML for
    online help, and PDF/DocBook/LaTeX (?) for printed
    documentation, essentially "for free" from the existing
    docstrings. [2]_
  - Other automated tools will understand my documentation
    strings, and be able to respect my formatting requirements
    [3]_

.. [1] Actually, it's arguable that the similarity to "existing
       practice" makes getting the syntax right *harder*. I never
       get footnote syntax right without checking (and I may have
       got this lot wrong!) This may be because of all the recent
       changes, but it is still something that probably needs
       covering in a Q&A. "Q: Won't the superficial similarity to
       existing markup conventions cause problems, and result in
       people writing invalid markup (and not noticing, because
       the plaintext looks natural)?"
.. [2] It's pretty important *not* to give the impression that
       these tools could be "vapourware". People are cynical...
.. [3] This one's vague - I'm sort of thinking about pydoc.

Interestingly (and possibly relevantly) it's not clear to me that these
benefits are overwhelming. It's more a case of the cost being minimal [4]_,
and the potential benefits being reasonable. Maybe we need to focus more
strongly on getting tools working. Something on the level of "look - I
generated a help file and some printed documentation, and pydoc produces
well-formatted information - all without doing anything more than using reST
in my docstrings". People respond better to demonstrations than to
standards...

.. [4] Which argues that people may well end up only using subsets
       of the full reST spec - just the bits they remember or find
       particularly hard to express any other way [5]_ ...
.. [5] So we need to consider how the dps will cope with the sort-of
       reST which may be written by (for example) someone who didn't
       know that reST had a table construct, and just typed in a
       table in a "natural" ASCII-art form. In other words, how
       forgiving is reST going to be of "not quite right" constructs?

I know the tools are coming (and I'm not doing much to help, so I shouldn't
criticise). But I'm a little concerned that a standard without supporting
"gee whizz" tools could turn some people off the idea, rather than
generating enthusiasm...

Paul.

PS I just noticed that I manually numbered the footnotes in this message -
even though I needed to renumber at one point. In practice, I don't think
I'd ever use the ``[#]`` notation for auto-numbering. It's too hard to
follow in "raw text" form. Just a data point...


From fdrake@acm.org  Tue Mar 26 20:30:32 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Tue, 26 Mar 2002 15:30:32 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020326203032.DB2D218EAD0@grendel.zope.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/devel-docs/

Minor update; shows how the "What's New" document is linked in.


From goodger@users.sourceforge.net  Wed Mar 27 03:44:13 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Tue, 26 Mar 2002 22:44:13 -0500
Subject: [Doc-SIG] New PEP: reStructuredText Standard Docstring Format
In-Reply-To: <003601c1d4a7$ee463510$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <B8C6AA3C.206A8%goodger@users.sourceforge.net>

The updated PEP can be found at
http://docutils.sourceforge.net/spec/pep-xxxx.txt,
until it's assigned a number.

Tony J Ibbs (Tibs) wrote:
> 1. It *may* be that the aim is, more pedantically, to provide
>    the markup syntax for docstrings *when markup is wanted*.

Added.

>    The start of the document sounds a little, to me, as if it is
>    deprecating plain text as docstring content. Of course, that
>    may just be me.

How a proposal is perceived *is* important.  Best not to start off on
a wrong note.

> 2. The example docstrings are not laid out according to the
>    normal style - for example::
> 
>             class Keeper(Storer):
...
>    doesn't start with a single summary line,

Fixed.

>    and that single summary line (!) isn't on the same line as the
>    opening triple quotes.

I don't see that requirement specified anywhere in the style guide.
My preference is to start multi-line docstrings with triple-quotes on
a separate line.  I've added a sentence to PEP 257 to clarify.

>    Also, I would argue that the first sentence is redundant - it
>    doesn't tell us anything new.

I'm using it to illustrate namespaces.  The entire class is useless,
just a simple example.

> 3. When discussing field lists, I would separate the point about RFC
>    headers (in PEPs) out - it confuses the matter.

Gone.

There's already a note in Goal 5; should be sufficient.

> 4. In the revamped-PEP examples (both "before" and "after"),
>    the text::
> 
>         This PEP proposes a adding frungible doodads

Fixed.

> 5. I note that www.doodads.org claims that frungible.html
>    does not exist.

I shoulda known that *someone* would try out that URL.  And I shoulda
guessed that such a site exists.  I've changed it to
www.frungible-doodads.org.

Is there a URL equivalent of a 555-prefix telephone number?  One
that's guaranteed *not* to exist, therefore safe to use in examples,
movies, and TV shows?

>    Hmm - would it be a good idea to *number* the questions
>    (and answers) - it would make it easier to discuss them
>    (e.g., Q6 and A6 rather than Q and A).

Done.

> 7. Personally, I probably *would* have separated the issue
>    of docstring markup and PEPs, mainly because it makes
>    this PEP longer. But I've been wrong before.

I don't want to be accused of being PEP-happy.  If instructed so by
the powers that be, I'll split it up.

> 8. When the document is finalised, will you also put up a
>    version in reST?

But of course!  I was thinking about writing it *first* in
reStructuredText, then converting it to old-PEP-style.  It would make
a neat project.  But the to-do list grows, and I wanted to get this
out there.

> > Any questions or answers to add to the Q & A?  Any
> > glaring omissions?
> 
> Not that spring to my mind. Oh - except that you don't actually point
> out that this is all *working*, right now and as of this moment.

Done.

And thanks.

-- 
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  Wed Mar 27 03:44:35 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Tue, 26 Mar 2002 22:44:35 -0500
Subject: [Doc-SIG] Re: New PEP: reStructuredText Standard Docstring Format
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B296@UKRUX002.rundc.uk.origin-it.com>
Message-ID: <B8C6AA52.206A8%goodger@users.sourceforge.net>

The updated PEP can be found at
http://docutils.sourceforge.net/spec/pep-xxxx.txt,
until it's assigned a number.

Paul Moore wrote:
> I'd suggest that you add a "Benefits" section, explaining the
> advantages to the individual programmer - *not* to the community as
> a whole - of the proposal.

Good idea.  Your list of benefits added.  Any others?

> .. [1] Actually, it's arguable that the similarity to "existing
>        practice" makes getting the syntax right *harder*. I never
>        get footnote syntax right without checking (and I may have
>        got this lot wrong!) This may be because of all the recent
>        changes, but it is still something that probably needs
>        covering in a Q&A. "Q: Won't the superficial similarity to
>        existing markup conventions cause problems, and result in
>        people writing invalid markup (and not noticing, because
>        the plaintext looks natural)?"

Question & answer added (#9)

> Interestingly (and possibly relevantly) it's not clear to me that
> these benefits are overwhelming. It's more a case of the cost being
> minimal [4]_, and the potential benefits being reasonable.

I think it's a case of the benefits not being obviously significant,
until the standards and tools are there, and then we'll all wonder how
we ever lived without them!  Perhaps not *that* significant, but you
get my meaning.

> Maybe we need to focus more strongly on getting tools working.

Yes, of course, and any help is gladly appreciated.  The thing about
scratching itches, is that you never know where or how they'll
manifest.

> Something on the level of "look - I generated a help file and some
> printed documentation, and pydoc produces well-formatted information
> - all without doing anything more than using reST in my
> docstrings". People respond better to demonstrations than to
> standards...

This is a classic chicken-and-egg situation.  Without tools, we can't
get acceptance, but in this case producing the tools is such a big job
that some form of acceptance up front is needed to keep up enthusiasm
(mine, if nobody else's).  One reason for putting this PEP out there
now, is that I'm at a point where I've put a lot of work into this
project, and it's starting to pay off, but I need some reassurance to
keep me going.  I want to know that I'm on the right track, that I'm
not wasting my time, and getting this PEP accepted would go a long way
in that direction.

Even if this PEP is rejected, that will be useful information.  If
accepted, then I can forget about supporting multiple markup parsers
in Docutils, at least for now.  If rejected, support for multiple
parsers may be its saving grace.

>        ... how forgiving is reST going to be of "not quite right"
>        constructs?

Added to the Q&A as part of the other question (#9).

> PS I just noticed that I manually numbered the footnotes in this
> message - even though I needed to renumber at one point. In
> practice, I don't think I'd ever use the ``[#]`` notation for
> auto-numbering. It's too hard to follow in "raw text" form. Just a
> data point...

That's where using labels helps.  Instead of plain ``[#]``, use
``[#a]`` or something more meaningful like ``[#subset]``.  You get
both automatic numbering and easy to follow references.

Thanks for the feedback.

-- 
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 Mar 27 10:19:00 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Wed, 27 Mar 2002 10:19:00 -0000
Subject: [Doc-SIG] New PEP: reStructuredText Standard Docstring Format
In-Reply-To: <B8C6AA3C.206A8%goodger@users.sourceforge.net>
Message-ID: <005401c1d578$cfe5f2f0$545aa8c0@lslp862.int.lsl.co.uk>

David Goodger wrote:
> The updated PEP can be found at
> http://docutils.sourceforge.net/spec/pep-xxxx.txt,
> until it's assigned a number.

I strain to find more niggles - but yes, by hard enough work anything is
possible...


"""There is no significant downside to using reStructuredText."""

Hmm. Somehow that feels like damning with faint praise. I think this
needs a more positive way of saying the same thing. Or to be left out,
if a better phrase can't be found. (The pedant in me [1]_ immediately
wants to know whether your idea of a "significant" downside matches
mine, for a start.)

Perhaps something like (forgive the "sentence starting with
'because'")::

   Because reStructuredText reads as sensible plaintext, there
   is no significant downside for the reader of such documentation,
   whilst the advantages are still available.

(well, I felt some alternative proposal was better than none, and this
does defuse that "significant" a bit)

.. [1] some would argue "the pedant coincident with me"
   would be better phrasing.

"""The Docutils project is at the point where standalone
reStructuredText documents can be converted to HTML."""

...and other output formats are in preperation? (I know you address that
in the next paragraph, but that's more in the docstring context)

Also, aren't there some tool users keeping track of events - both
HappyDoc and one of the Wikis? Might it be worth finding out explicitly
if they are considering adopting reStructuredText as one of their bag of
input formats?


Anyway, looking good...

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 doug@hellfly.net  Wed Mar 27 11:49:24 2002
From: doug@hellfly.net (Doug Hellmann)
Date: Wed, 27 Mar 2002 06:49:24 -0500
Subject: [Doc-SIG] New PEP: reStructuredText Standard Docstring Format
In-Reply-To: <005401c1d578$cfe5f2f0$545aa8c0@lslp862.int.lsl.co.uk>
References: <005401c1d578$cfe5f2f0$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <200203271149.GAA06758@branagan>

On Wednesday 27 March 2002 05:19, Tony J Ibbs (Tibs) wrote:
> Also, aren't there some tool users keeping track of events - both
> HappyDoc and one of the Wikis? Might it be worth finding out explicitly
> if they are considering adopting reStructuredText as one of their bag of
> input formats?

I've been following the progress of reST without getting too involved.  I'm 
definitely considering adding support for it to HappyDoc's set of docstring 
parsers.  Making it the default parser would depend on support from the 
community at large.

Doug


From Taradino@subdimension.com  Wed Mar 27 13:44:26 2002
From: Taradino@subdimension.com (Johannes L. Gijsbers)
Date: Wed, 27 Mar 2002 13:44:26 GMT
Subject: [Doc-SIG] New PEP: reStructuredText Standard Docstring Format
Message-ID: <3ca1ccba.519.1804289383@subdimension.com>

> I shoulda known that *someone* would try out that URL. 
> And I shoulda guessed that such a site exists.  I've
> changed it to www.frungible-doodads.org.
> 
> Is there a URL equivalent of a 555-prefix telephone
> number?  One that's guaranteed *not* to exist, therefore
> safe to use in examples, movies, and TV shows?

Actually, there is. Check http://www.example.com.
There was someone before you who thought of this, it even
made it into RFC2606.

jlg
_____________________________________________________________________
// free anonymous email || forums \\ subZINE || anonymous browsing 
            subDIMENSION -- http://www.subdimension.com


From goodger@users.sourceforge.net  Thu Mar 28 01:05:52 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 27 Mar 2002 20:05:52 -0500
Subject: [Doc-SIG] Re: New PEP: reStructuredText Standard Docstring
 Format
In-Reply-To: <m3adstehls.fsf@linux.local>
Message-ID: <B8C7D69F.20796%goodger@users.sourceforge.net>

Thanks for your kind words, Ueli.  Hmm, that gives me an idea: I think I'll
start a "Testimonials" page...

Ueli Schl=E4pfer wrote:
> All essential constructs for everyday use are there, and much more if nee=
ded.
> If I can think of one exception, it would be auto-numbered lists

Allow me to borrow Guido's time machine. See
http://structuredtext.sourceforge.net/spec/rst-notes.html
#auto-numbered-enumerated-lists.

--=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  Thu Mar 28 03:23:58 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 27 Mar 2002 22:23:58 -0500
Subject: [Doc-SIG] New PEP: reStructuredText Standard Docstring Format
In-Reply-To: <005401c1d578$cfe5f2f0$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <B8C7F6FD.207A8%goodger@users.sourceforge.net>

Tony J Ibbs (Tibs) wrote:
> """There is no significant downside to using reStructuredText."""
> 
> Hmm. Somehow that feels like damning with faint praise.

Agreed; dropped.

> """The Docutils project is at the point where standalone
> reStructuredText documents can be converted to HTML."""
> 
> ...and other output formats are in preperation?

Added "other output format writers will become available over time."

The updated PEP is still available at
http://docutils.sourceforge.net/spec/pep-xxxx.txt.

> Also, aren't there some tool users keeping track of events - both
> HappyDoc and one of the Wikis? Might it be worth finding out
> explicitly if they are considering adopting reStructuredText as one
> of their bag of input formats?

I contacted several tool authors privately in the past.  Some
expressed interest, most were noncommittal; no-one was against the
idea.  I think time constraints and/or a "wait and see" attitude
prevent most from active participation.  And rightly so -- there have
been many similar projects started which haven't caught on -- once
bitten, twice shy.  HappyDoc has been the most successful, I think,
but I have yet to dig into its source code so I can't complain that we
haven't joined forces.

With accepted PEPs to rally around, I hope more people will join in
the fun.

-- 
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 usc@ieee.org  Wed Mar 27 23:06:07 2002
From: usc@ieee.org (Ueli Schläpfer)
Date: 28 Mar 2002 00:06:07 +0100
Subject: [Doc-SIG] Re: New PEP: reStructuredText Standard Docstring Format
In-Reply-To: <B8C6AA52.206A8%goodger@users.sourceforge.net>
References: <B8C6AA52.206A8%goodger@users.sourceforge.net>
Message-ID: <m3adstehls.fsf@linux.local>

Hi all,

been away at paid work for a long long time, and it's not going to get
better any time soon unfortunately...

David Goodger <goodger@users.sourceforge.net> writes:
[...]

> Paul Moore wrote:
> > I'd suggest that you add a "Benefits" section, explaining the
> > advantages to the individual programmer - *not* to the community as
> > a whole - of the proposal.
> 
> Good idea.  Your list of benefits added.  Any others?

[...]

I haven't been programming Python a whole lot recently, so my
suggestion may be a bit off in the context of a PEP.  

Anyway, I have adopted reST as my tool of choice for producing notes
while doing lab work (mostly in a matlab environment).  Since then,
the quality of such documentation has increased noticeably, mostly for
two reasons:

- I no longer need to switch to another tool, so the threshold has
  fallen to very low.  Note that "another tool" means Winword...
- Still, I have a powerful set of markup constructs at my fingertips
  that let me create the kind of documents I need [#1]_ with more ease
  than any other tool I can think of [#2]_.

Thanks to reST/DPS, I'll soon be able to go ahead and apply the same
tools for extracting documentation out of my python code.  Hey, that's
a printable and a browsable version *for free*!  Personally, I consider
this a large benefit.

BTW, echo from a few colleagues at work that I've exposed to reST has
been very positive so far.  Not sure whether anybody is using it,
though...

Ueli

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

.. [#1] Notes interspersed with code snippets, foornotes, maybe
        hyperlinks, and the  occasional screenshot.
.. [#2] My experience so far is that David has done an excellent job
	on the specs as well as on the implementation!  All essential
	constructs for everyday use are there, and much more if
	needed.  If I can think of one exception, it would be
	auto-numbered lists -- I have been thinking of suggesting this
	as a new feature, but I haven't had the time to think through
	whether my candidate syntax ::

	  #. The first item
	  #. And this item was introduced later on.
	  #. Originally the second item.  Glad I didn't have to
	     renumber by hand!

        will work out all right.  Consider the suggestion made,
        then...



From fdrake@acm.org  Fri Mar 29 21:24:15 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 29 Mar 2002 16:24:15 -0500
Subject: [Doc-SIG] "Don't Kill Opera" documentation release
Message-ID: <15524.56191.459903.271423@grendel.zope.com>

I've just made an "emergency" release of the 2.2 documentation (based
on the release22-maint branch in CVS.  If you use Opera 6.01, you can
now feel a little safer on python.org.  ;-)


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation


From fdrake@acm.org  Fri Mar 29 22:48:51 2002
From: fdrake@acm.org (Fred L. Drake)
Date: Fri, 29 Mar 2002 17:48:51 -0500 (EST)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20020329224851.02DAD18EAD1@grendel.zope.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/devel-docs/

Started to update the Extending & Embedding manual with information on the
new support for types.

There's still a long way to go -- contributions welcome!



From David Abrahams" <david.abrahams@rcn.com  Fri Mar 29 22:59:14 2002
From: David Abrahams" <david.abrahams@rcn.com (David Abrahams)
Date: Fri, 29 Mar 2002 17:59:14 -0500
Subject: [Doc-SIG] Re: [Python-Dev] [development doc updates]
References: <20020329224851.02DAD18EAD1@grendel.zope.com>
Message-ID: <0ffe01c1d775$c84ba270$0202a8c0@boostconsulting.com>

I'll see what I can do. It would help to have some guidance as to:

* What needs to be done
* What format(s) would be appropriate (patches to TeX source, plain
text...)
* What approach to take (e.g. "just document what the existing Python
source does", or "ask Guido what the intended functionality is and
transcribe what he says")
* ...etc. (I'm sure you can think of more).

-Dave

----- Original Message -----
From: "Fred L. Drake" <fdrake@acm.org>
To: <python-dev@python.org>; <doc-sig@python.org>;
<python-list@python.org>
Sent: Friday, March 29, 2002 5:48 PM
Subject: [Python-Dev] [development doc updates]


> The development version of the documentation has been updated:
>
>     http://python.sourceforge.net/devel-docs/
>
> Started to update the Extending & Embedding manual with information on
the
> new support for types.
>
> There's still a long way to go -- contributions welcome!
>
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev@python.org
> http://mail.python.org/mailman/listinfo/python-dev



From slrlfl2000@yahoo.co.kr  Sat Mar 30 04:31:51 2002
From: slrlfl2000@yahoo.co.kr (slrlfl2000)
Date: Sat, 30 Mar 2002 13:31:51 +0900
Subject: [Doc-SIG] [±¤°í] Á¾·®Á¦ ºÀÅõ Àý¾àÇü ¾ÐÃྲ·¹±âÅë ¼Ò°³
Message-ID: <E16rAaH-00068Q-00@mail.python.org>

<html>
<body bgcolor=white>
<p align=center><a href="http://www.softface.co.kr/magichome.htm" target="_blank"><img src="http://www.dic4u.com/images2/magicpower.gif" width="675" height="1023" border=0></a><br><br>&nbsp;</p>
<table border="0" align="center">
<tr>
<td>
<p style="LINE-HEIGHT: 120%"><span style="FONT-SIZE: 9pt">¢¹&nbsp;¿øÄ¡¾ÊÀº Á¤º¸¿´´Ù¸é Á¤ÁßÈ÷ »ç°ú µå¸®¸ç, ¼ö½Å °ÅºÎ¸¦ ÇØÁÖ½Ã¸é ´ÙÀ½ºÎÅÍ´Â ¸ÞÀÏÀÌ ¹ß¼ÛµÇÁö ¾ÊÀ» °ÍÀÔ´Ï´Ù.<br>¢¹&nbsp;¸ÞÀÏŬ¶óÀ̾ðÆ®ÀÇ ÇÊÅÍ ±â´ÉÀ» ÀÌ¿ëÇÏ¿© [±¤°í] ¹®±¸¸¦ ÇÊÅ͸µÇÏ¸é ¸ðµç ±¤°í ¸ÞÀÏÀ» ÀÚµ¿À¸·Î Â÷´ÜÇÏ½Ç ¼ö ÀÖ½À´Ï´Ù.</span></p>
</td>
</tr>
<tr>
<td align="center"><a href="http://www.softface.co.kr/unsub.asp?flag=magicpower&email=doc-sig@python.org"><span style="font-size:9pt;">¼ö½Å°ÅºÎ(Unsubscribe)</span></a></td>
</tr>
</table>
</body>
</html>