From pvirketis at hbk.com  Mon May  3 10:06:02 2004
From: pvirketis at hbk.com (Pijus Virketis)
Date: Mon May  3 10:06:05 2004
Subject: [Doc-SIG] ReST: how to break at the end of each line?
Message-ID: <FB5014C3177D7E44989DA04617A39E1A02584A@nycdc1.hbk.com>

Dear all,

I am writing my website's links page using ReST. The format 
I'd like to achieve is very simple:

Python: favourite scripting language.
ReST: neat text processing system.
...

What I've got in the way of ReST is:

`Python <http://www.python.org>`__ favourite scripting language.
`ReST <http://docutils.sourceforge.net>`__ neat text processing system.

So far, so good. The only problem is that when html.py renders the 
text, it puts everything on one line:

Python: favourite scripting language. ReST: neat text processing system.

I realise that this is the way a paragraph is supposed to 
be handled; but now I would like to insert breaks at the end of each
line in a 
nice ReST-like way, without resorting to hacks. Literal block does not 
seem to be the ticket, since it does not process the ` <>`__ bit 
correctly. I'd appreciate any suggestions.

Thank you!

Pijus


From goodger at python.org  Mon May  3 10:38:13 2004
From: goodger at python.org (David Goodger)
Date: Mon May  3 10:38:18 2004
Subject: [Doc-SIG] ReST: how to break at the end of each line?
In-Reply-To: <FB5014C3177D7E44989DA04617A39E1A02584A@nycdc1.hbk.com>
References: <FB5014C3177D7E44989DA04617A39E1A02584A@nycdc1.hbk.com>
Message-ID: <40965955.3020302@python.org>

Pijus Virketis wrote:
> What I've got in the way of ReST is:
> 
> `Python <http://www.python.org>`__ favourite scripting language.
> `ReST <http://docutils.sf.net>`__ neat text processing system.
> 
> So far, so good. The only problem is that when html.py renders the 
> text, it puts everything on one line:
...
> now I would like to insert breaks at the end of each
> line in a nice ReST-like way, without resorting to hacks.

The way to do this is with line blocks.  For now, use the line-block
directive:

.. line-block::

    `Python <http://www.python.org>`__ favourite scripting language.
    `ReST <http://docutils.sf.net>`__ neat text processing system.

Soon, there will be specialized syntax for this.  It's on the to-do
list with a high priority:

| `Python <http://www.python.org>`__ favourite scripting language.
| `ReST <http://docutils.sf.net>`__ neat text processing system.

-- David Goodger

From Felix.Wiemann at gmx.net  Tue May 11 15:48:52 2004
From: Felix.Wiemann at gmx.net (Felix Wiemann)
Date: Tue May 11 16:20:31 2004
Subject: [Doc-SIG] Docutils 0.3.3 released
Message-ID: <87y8nyrbh7.fsf@news2.ososo.de>

Docutils 0.3.3 has been released.

Read <http://docutils.sourceforge.net/#unstable-releases> for details.

It's alpha software.  However, many new features have been added and
many bugs have been fixed since Docutils 0.3 (the latest 'stable'
release), so you might very well consider using it (on non-production
systems).

(Posted to Doc-SIG and Docutils-users.  Please direct discussion to
Docutils-users.)

-- 
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.

<http://www.ososo.de/>


From fdrake at acm.org  Wed May 12 00:28:52 2004
From: fdrake at acm.org (Fred L. Drake, Jr.)
Date: Wed May 12 00:29:08 2004
Subject: [Doc-SIG] Python 2.3.x doc tree closed
Message-ID: <200405120028.53006.fdrake@acm.org>

I'm cutting the docs for Python 2.3.4; please make no changes on the the 
release23-maint branch.

Thanks for everyone's help in getting this ready!


  -Fred

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


From cben at users.sf.net  Thu May 13 14:59:13 2004
From: cben at users.sf.net (Beni Cherniavsky)
Date: Thu May 13 15:59:28 2004
Subject: [Doc-SIG] Attribute docstrings (was: [Docutils-develop] concerns
	over futureof codebase)
In-Reply-To: <409A82AB.7000900@python.org>
References: <uisfcmhk9.fsf@boost-consulting.com>
	<4098200F.9060908@python.org>	<usmefgj02.fsf@boost-consulting.com>
	<40990161.4050607@python.org>
	<uwu3qetfa.fsf@boost-consulting.com> <409A82AB.7000900@python.org>
Message-ID: <40A3C581.8000402@users.sf.net>

[Moving this spin-off discussion to Doc-SIG where it belongs]

David Goodger wrote:
 > David Abrahams wrote:
 >  > David Goodger wrote:
>  > >     document = None
>  > >     """The document to write."""
>  >
>  > Whaa??  This attribute is on the class, not an instance, if I
>  > remember my Python.  It strikes me as meant to be per-instance data.
>  > What if you have several writers active at once?
> 
> Notice that these variables are being set to None.  I've updated the
> docstrings with text like "set by `write`".  They're initialized to
> bogus values in the class scope because that's one of the places where
> their docstrings will be recognized; see PEP 258.
> 
What?!?  You are initializing a value in code *only* because that's a 
precondition to the docstring being recognized?  Not having seen the 
code, I can't say whether initializing it there is healthy on other 
merits -- but it certainly sounds bad that the documentation format 
forces you to write code in a certain way.

>  > """docstrings""" used in this way are discarded by Python, and
>  > should be replaced by comments preceding the variable IMO.  I
>  > *think* that's what most people expect.
> 
> PEP 258 describes "attribute docstrings"; for full details, see
> <http://docutils.sf.net/spec/pep-0258.html#docstring-extraction-rules>,
> item 2 ("Where").
> 
Let me join the "Urf" sentiment.  I've resented this solution/syntax 
since I saw it for the following reasons:

* It provides no way to introspect these docstrings.  That's a design
   decision:

       Since attribute docstrings and additional docstrings are ignored
       by the Python byte-code compiler, no namespace pollution or
       runtime bloat will result from their use.

   but I disagree with the motivation.  I can understand the desire for
   "secondary" docstrings to limit code bloat but who said that *all*
   attribute docstrings *must* be secondary?  What if do want them at
   runtime (and I do)?  Why shouldn't I have the option?

   + Instance variables can't have the docstring attached to the value
     (because the value comes and goes, the docstring is for the slot,
     not the value).  Schemes like storing the docstring in
     `__doc_<name>__` are also ugly.  I feel that attribute docstrings
     belong at the end of the class docstring.

   + If the attribute docstring is to be appended to the class docstring,
     it should be textually marked as belonging to the attribute.  How to
     do it depends on the doc format one uses.  E.g. for reST, a
     definition list is a natural choise::

         Main class docsrting
         ...

         attr1
             Doc for attr1

         attr2
             Doc for attr2

      User control over the format is desirable.

   + It's not always convenient to document attributes one-by-one.  There
     are usaully interactions between attributes, so there might be
     better ways to structure the documentation.

     It's the same sentiment that applies to comments - frequently a
     single comment covers several statements.

* I don't like the syntax that is magically sensitive to assignments.  I
   could stand that, but being magically sensitive to assignments to
   attributes of `self` in `__init__` is way too magical to be Pythonic
   IMHO.

   I'm not sure yet whether I like the docstring before or after the
   assignment - but probably before is better.  Think of::

       foo = [
              long,
              {data: structure},
              here
             ]
       """Docstring"""

    Does it belong there?  No - for the same reasons we put comments that
    don't fit on the same line before the code: the code might be long.
    Anybody quoting the Python style for class/function docstrings as a
    precedent for putting the docstrings after the code forgets that the
    bulk of the class/function code comes after the docstring.  It
    follows only the header line (for indentation aesthetics reasons),
    which is almost guaranteed to be short.

    That's another reason the after-assignment syntax is weak.  There is
    no explicit connection of the docstring with the variable.  If
    backward-compatibility was not an issue, the following syntax would
    solve this (but only this) issue::

        attr = Value
           """Docstring"""

For all these reasons, I propose the following extremely unmagical
solution: all bare-string statements are simply concatenated together to
form this scope's docstring.  Well, not simply - at least a newline (or
two?) should be inserted because most docstrings don't end with one.

In other words, we simply allow the docstring to be split into parts
with code between them, which brings docstrings one step closer to
literate programming.

The examples from `PEP 258`__ then become::

     """g
         This is g's docstring."""
     g = 'module attribute (module-global variable)'

     class AClass:

         """c
             This is AClass.c's docstring."""
         c = 'class attribute'

         """i
             This is i's docstring."""

         def __init__(self):
             """Method __init__'s docstring."""

             self.i = 'instance attribute'

     def f(x):
         """Function f's docstring."""
         return x**2

         """a
             Function attribute f.a's docstring."""

     f.a = 1

__ http://docutils.sf.net/spec/pep-0258.html#attribute-docstrings

I had to pull the docstring for self.i out of `__init__`; this is
somewhat unfortunate.  OTOH I'm not sure the documentation of the 
attribute's *purpose* belongs with the initial assignment to it.  If 
separating the docstring from the initialization is problematic, its
separation from any other access to the attribute must be no less 
problematic...

There is no difference in this scheme between documenting a class
attribute and an instance attribute.  If important, this is better
documented in the docstring itself, because in Python there are many 
shades of it (e.g. class attributes might actually be defaults for
instance attributes).

The documentation of `f.a` is also torn away from it's assignment.
But I find it extremely hard to image a situation where there is a
special maining to an attribute of a specific function.  The meaning
of the attribute (`a`) would normally be common to all functions that 
have such an attribute.  The meaning of the attribute's value (1) should
be associated with the value (if it were a class/function, it would have
it's own docstring; number won't have docstrings in the forseable future 
;-).

-- 
Beni Cherniavsky <cben@users.sf.net>
Note: I can only read email on week-ends...

From cben at users.sf.net  Sat May 15 18:57:57 2004
From: cben at users.sf.net (Beni Cherniavsky)
Date: Sat May 15 19:58:05 2004
Subject: [Doc-SIG] Idea: make double-space between sentences meaningful
Message-ID: <40A6A075.4090502@users.sf.net>

Some formats (notably LaTeX) support the typographical convention (of
some languages, e.g. English but not French IIRC) of putting a bigger
space after the end of a sentence than between words.  LaTeX tries to
guess intellegently but can fail.  Its guessing can be explicitly
overriden [1]_.

Currently, reST provides no way to convey this information to the output
format.  Producing high-quality output requires this information.  There
already exists an obvious convention supported by programs (e.g. Emacs) 
for representing it in plain text: just use a double space after the end
of a sentence.  I propose to make this official for reStructuredText:
more than one space between words after punctuation [2]_ signifies a
sentence end [3]_.

Backward compatiblity: at worse, it will force all sentence ends to
single spaces in existing documents that don't use the double-space
convention in the reST source.  It's a good bet that anybody who cares
about it in his LaTeX output also cares about his source, but it's a
good idea to make this a parser option (defaulting off?)...

It is even possible, if desired, to support this in HTML output, using
some hack (``&nbsp;`` won't do because we *want* it to be breakable -
it's even better there; perhaps ``<span class="sentence-end"> </span>``
with appropriate CSS?).

.. [1] By using ``\@.`` for a sentence end and ``.\ `` for a sentence
        non-end.  See `The Not So Short Introduction to LaTeX 2?`__,
        section 2.6.

        __ http://www.ctan.org/tex-archive/info/lshort/english/lshort.pdf

.. [2] Punctuation should be taken in a wide sense of the word.  E.g.
        many people end a sentence with a smiley without putting a period
        after it ;-).

.. [3] A period at end-of-line should be considered a sentence end per
        Emacs conventions (it acutally avoids putting non-sentence-end
        periods at end-of-line when refilling paragraphs!).  However, if
        there is a trailing whitespace, it should be used to decide (in
        the style of RFC 2646 - wrap lines *after* the whitespace - which
        is the only unambiguos way to retain spacing info at line ends;
        some editors (pico/nano) use this only when there is more than 

        one space - this algorithm will support them all).

-- 
Beni Cherniavsky <cben@users.sf.net>
Note: I can only read email on week-ends...

From Felix.Wiemann at gmx.net  Sun May 16 11:12:59 2004
From: Felix.Wiemann at gmx.net (Felix Wiemann)
Date: Sun May 16 11:19:12 2004
Subject: [Doc-SIG] Re: Attribute docstrings
References: <uisfcmhk9.fsf@boost-consulting.com> <4098200F.9060908@python.org>
	<usmefgj02.fsf@boost-consulting.com> <40990161.4050607@python.org>
	<uwu3qetfa.fsf@boost-consulting.com> <409A82AB.7000900@python.org>
	<40A3C581.8000402@users.sf.net>
Message-ID: <87vfiwtngk.fsf@news2.ososo.de>

Beni Cherniavsky wrote:

> [Proposal:] The examples from `PEP 258`__ then become::
>
>      """g
>          This is g's docstring."""
>      g = 'module attribute (module-global variable)'
>
> [snip]

I don't like, because it has redundancy -- the attribute name is
mentioned twice.

Another problem is that it's currently impossible to assign a new value
to an integer's docstring.

>>> a = 5
>>> a.__doc__ = "new docstring"
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'int' object attribute '__doc__' is read-only

So at the moment the only possibility to publicly and reliably document
an attribute is to document it in the parent object's docstring.

-- 
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.

<http://www.ososo.de/>


From Felix.Wiemann at gmx.net  Sun May 16 11:28:08 2004
From: Felix.Wiemann at gmx.net (Felix Wiemann)
Date: Sun May 16 11:28:06 2004
Subject: [Doc-SIG] Re: Idea: make double-space between sentences meaningful
References: <40A6A075.4090502@users.sf.net>
Message-ID: <87r7tktmrb.fsf@news2.ososo.de>

Beni Cherniavsky wrote:

> Some formats (notably LaTeX) support the typographical convention (of
> some languages, e.g. English but not French IIRC) of putting a bigger
> space after the end of a sentence than between words.
>
> Currently, reST provides no way to convey this information to the
> output format.  Producing high-quality output requires this
> information.  There already exists an obvious convention supported by
> programs (e.g. Emacs) for representing it in plain text: just use a
> double space after the end of a sentence.  I propose to make this
> official for reStructuredText: more than one space between words after
> punctuation [2]_ signifies a sentence end [3]_.

Sounds good.  I'd like that very much.  IMO it can be added to
alternatives.txt or notes.txt (David, what d'you think?).

> It's a good bet that anybody who cares about it in his LaTeX output
> also cares about his source, but it's a good idea to make this a
> parser option (defaulting off?)...

It should be activated by default, because it doesn't hurt if it isn't
used.

> It is even possible, if desired, to support this in HTML output, using
> some hack (``&nbsp;`` won't do because we *want* it to be breakable -
> it's even better there; perhaps ``<span class="sentence-end"> </span>``
> with appropriate CSS?).

No.  It's bloat, it's unnecessary, it's hackish.

-- 
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.

<http://www.ososo.de/>


From edloper at gradient.cis.upenn.edu  Sun May 16 20:30:26 2004
From: edloper at gradient.cis.upenn.edu (Edward Loper)
Date: Sun May 16 20:28:56 2004
Subject: [Doc-SIG] Re: Attribute docstrings
In-Reply-To: <E1BOfAI-0005Dl-CX@mail.python.org>
References: <E1BOfAI-0005Dl-CX@mail.python.org>
Message-ID: <40A807A2.5060801@gradient.cis.upenn.edu>

Felix Wiemann wrote:
>> Another problem is that it's currently impossible to assign a new value
>> to an integer's docstring.
>> 
>>    >>> a = 5
>>    >>> a.__doc__ = "new docstring"
>> 
>> Traceback (most recent call last):
>>   File "<stdin>", line 1, in ?
>> AttributeError: 'int' object attribute '__doc__' is read-only

It's important to note that values and variables are fundamentally 
different things.  Strictly speaking, only *values* can have docstrings 
(i.e., description strings accessible via .__doc__).  It will *never* be 
possible to access variable docstrings via the variables themselves; as 
Beni noted, the only reasonable place to store description strings for 
variables (if we want them to be accessible via inspection) is in the 
enclosing object (either in its docstring or in some other attribute).

To avoid confusion, let's call these variable-docstrings "pseudo- 
docstrings", to distinguish them from real docstrings (which are
accessible via .__doc__).

Beni Cherniavsky wrote:
> For all these reasons, I propose the following extremely unmagical
> solution: all bare-string statements are simply concatenated together to
> form this scope's docstring.  

I've been going back and forth on whether I like this idea.  I agree 
with Felix that writing each variable name twice is somewhat ugly.

The main advantage of Beni's proposal is its simplicity.  A number of 
subtle issues came up when I was writing the pseudo-docstrings extractor 
for epydoc.  E.g., what do you do with...

     x,y = 1,2
     """docstring"""

     x = y = 0
     """docstring"""

     x[0] = 5
     """docstring"""

     x.y = 5
     """docstring"""

     x.y = z = 1,2
     """docstring"""

     self.x = 10
     """docstring"""

(If you're curious, epydoc will write a shared description for the first 
two cases, ignore the 3rd and 4th case, and treat the last case as an 
instance variable, assuming it's in a class's __init__ and 'self' is 
equal to __init__'s first parameter name.)

Using Beni's proposal, the programmer can handle these cases as they see 
fit.  E.g.:

     """:Parameters x,y: docstring for x and y."""
     x,y = 1,2

> Well, not simply - at least a newline (or
> two?) should be inserted because most docstrings don't end with one.

You'd also have to magically deduce the indentation for the first line 
of the docstring.  And note that in the examples you gave, 
inspect.getdoc() will *not* give you what you want.  E.g., the 
pesudo-docstring:

     """c
         This is Aclass.c's docstring."""

would get translated into: "c\nThis is Aclass.c's docstring" (note the 
lack of indentation on the second line).  But leaving the indentation 
as-is will result in invalid ReST.  This seems like a potential 
show-stopper to me, because it would basically mean that you need to add 
an extra CR for each attribute docstring:

     """
     c
         This is Aclass.c's docstring."""

Besides looking ugly, this makes a 3-line docstring out of something 
that really should have been a one-liner.

> I had to pull the docstring for self.i out of `__init__`; this is
> somewhat unfortunate.  

If you made the rule "any bare string literal is appended to the 
containing namespace object (module or class) docstring," then you could 
put instance variable docstrings inside of __init__ methods.  (Note that 
it doesn't make any sense to document a function's variable, because 
functions aren't namespaces.)

> OTOH I'm not sure the documentation of the 
> attribute's *purpose* belongs with the initial assignment to it.  

But the good thing about pseudo-docstrings is that it lets the 
*programmer* decide where it's appropriate to document variables. 
Sometimes this will be in the containing object's docstring, sometimes 
this will be next to one of the assignments.

Despite its appealing simplicity, my main problems with Beni's proposal 
are...
     - Duplication of variable names
     - It should be possible to write variable docstrings in one line
       (or less; see the psuedo-docstring for z, below).

For comparison, I'm currently planning to extend epydoc to accept 3 
formats for pseudo-docstrings:

     x = 12
     """pseudo-docstring for x"""

     #: pseudo-docstring for y
     y = 20

     z = 99     #: pseudo-docstring for z

Where the "#:" sequence is used to disambiguate psuedo-docstrings from 
normal comments (I picked this sequence because it looked reasonable to 
me, but I'd be open to changing it if there's a reason to).

Of course, these pseudo-docstrings won't be accessible via inspection; 
but I don't see that as a huge problem, as long as...
   - The tools that need them (e.g., epydoc/pydoc) can get at them.
   - Programmers *also* have the option of documenting variables in
     the containing namespace object.

And if these formats become standard, then we can add a module the the 
stdlib to extract them.

-Edward


From goodger at python.org  Mon May 17 16:52:45 2004
From: goodger at python.org (David Goodger)
Date: Mon May 17 16:52:47 2004
Subject: [Doc-SIG] API doc tool
Message-ID: <40A9261D.7080500@python.org>

Howdy!

I am writing from the offices of Enthought, in Austin Texas.
Enthought is funding development work on an API documentation
generation tool that they need, which they're releasing under a
BSD-style license.  I'm here for a week of planning and initial
development.  I will be completing the development part-time over the
next several months.

This is a great opportunity to make significant progress on the tool
that I've been talking and thinking about for some time.  There is a
lot of good prior art that will be examined for this (Epydoc,
HappyDoc, others).  The initial basis of the tool will PEP 258's
description of the Python Source Reader [1], but I'm sure there will
be additions and changes as time goes on.  What form the final tool
takes is open to discussion right now, so feedback is welcome.

[1] http://docutils.sf.net/spec/pep-0258.html#python-source-reader

-- David Goodger

From goodger at python.org  Mon May 17 16:56:07 2004
From: goodger at python.org (David Goodger)
Date: Mon May 17 16:56:09 2004
Subject: [Doc-SIG] Idea: make double-space between sentences meaningful
In-Reply-To: <40A6A075.4090502@users.sf.net>
References: <40A6A075.4090502@users.sf.net>
Message-ID: <40A926E7.5020500@python.org>

Beni Cherniavsky wrote:
 > Some formats (notably LaTeX) support the typographical convention
 > (of some languages, e.g. English but not French IIRC) of putting a
 > bigger space after the end of a sentence than between words.  LaTeX
 > tries to guess intellegently but can fail.  Its guessing can be
 > explicitly overriden [1]_.

If the input text contains double spaces, the output will too, in all
the existing core writers.  For example:

     $ cat ds
     A sentence.  Another.
     New line.

     New paragraph.  Another sentence.
     $ rst2html.py ds
     ...
     <p>A sentence.  Another.
     New line.</p>
     <p>New paragraph.  Another sentence.</p>
     ...

No writer so far does any whitespace normalization [*]_, so whatever
whitespace is in the input (spaces, newlines) comes out as-is in the
output.  LaTeX and any other back-end formatter is free to treat this
whitespace as significant.

.. [*] The parser converts tabs to spaces.

 > Currently, reST provides no way to convey this information to the
 > output format.  Producing high-quality output requires this
 > information.

How should this information be conveyed?  Please provide examples.

 > There already exists an obvious convention supported by programs
 > (e.g. Emacs) for representing it in plain text: just use a double
 > space after the end of a sentence.  I propose to make this official
 > for reStructuredText: more than one space between words after
 > punctuation [2]_ signifies a sentence end [3]_.

It seems to me that Docutils and reStructuredText already support this
standard, simply by not messing with whitespace unduly.  I don't see
how making this "official" would benefit users of reStructuredText.
Do we want the reST parser to be in the business of guessing sentence
endings?

How would we represent it internally?  Please show a doctree
implementing your proposal.

 > It's a good bet that anybody who cares about it in his LaTeX output
 > also cares about his source, but it's a good idea to make this a
 > parser option (defaulting off?)...

How would the parser option behave; what would it do?

 > It is even possible, if desired, to support this in HTML output,
 > using some hack (``&nbsp;`` won't do because we *want* it to be
 > breakable - it's even better there; perhaps ``<span
 > class="sentence-end"> </span>`` with appropriate CSS?).

&nbsp; followed by a regular space works OK.  Something like a
&thinsp; (U+2009) followed by a regular space ought to work, but
doesn't.

-- David Goodger

From aahz at pythoncraft.com  Mon May 17 17:40:59 2004
From: aahz at pythoncraft.com (Aahz)
Date: Mon May 17 17:41:05 2004
Subject: [Doc-SIG] Idea: make double-space between sentences meaningful
In-Reply-To: <40A926E7.5020500@python.org>
References: <40A6A075.4090502@users.sf.net> <40A926E7.5020500@python.org>
Message-ID: <20040517214059.GA26316@panix.com>

On Mon, May 17, 2004, David Goodger wrote:
>
> No writer so far does any whitespace normalization [*]_, so whatever
> whitespace is in the input (spaces, newlines) comes out as-is in the
> output.  LaTeX and any other back-end formatter is free to treat this
> whitespace as significant.

In fact, the OOwriter went to some lengths to *not* do whitespace
normalization -- the XML format used by OpenOffice.org condenses
whitespace just like HTML does.  So all sequences of more than one space
in reST source had special handling.
-- 
Aahz (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/

Adopt A Process -- stop killing all your children!

From goodger at python.org  Mon May 17 20:55:23 2004
From: goodger at python.org (David Goodger)
Date: Mon May 17 20:55:24 2004
Subject: [Doc-SIG] Re: Attribute docstrings
In-Reply-To: <40A3C581.8000402@users.sf.net>
References: <uisfcmhk9.fsf@boost-consulting.com>
	<4098200F.9060908@python.org>	<usmefgj02.fsf@boost-consulting.com>
	<40990161.4050607@python.org>	 <uwu3qetfa.fsf@boost-consulting.com>
	<409A82AB.7000900@python.org> <40A3C581.8000402@users.sf.net>
Message-ID: <40A95EFB.3040304@python.org>

Beni Cherniavsky wrote:
 > What?!?  You are initializing a value in code *only* because that's
 > a precondition to the docstring being recognized?  Not having seen
 > the code, I can't say whether initializing it there is healthy on
 > other merits -- but it certainly sounds bad that the documentation
 > format forces you to write code in a certain way.

When you put it that way, it does sound bad.

I like to think of it in terms of optional functionality, so you don't
*have* to use it if you don't want to.  Docstring writers are welcome
to describe attributes in class docstrings with definition lists, etc.

 > Let me join the "Urf" sentiment.  I've resented this solution/syntax
 > since I saw it for the following reasons:
 >
 > * It provides no way to introspect these docstrings.  That's a
 >   design decision:

Yes, it was.  The same syntax was proposed in PEP 224, with support
for introspection, but was rejected.  That's why PEP 258 proposes it
as a convention in application space, without requiring Python
interpreter support.

 >   I can understand the desire for "secondary" docstrings to limit
 >   code bloat but who said that *all* attribute docstrings *must* be
 >   secondary?  What if do want them at runtime (and I do)?  Why
 >   shouldn't I have the option?

If you'd like to lobby for that option, please go ahead.  Start with
PEP 224, and come up with a better syntax or solution.  In PEP 258 I
intentionally avoided the issue.

 > For all these reasons, I propose the following extremely unmagical
 > solution: all bare-string statements are simply concatenated
 > together to form this scope's docstring.

That's a good idea.  It could be an alternative to attribute
docstrings.  In any case, I'll document it in the PEP.

 > Well, not simply - at least a newline (or two?) should be inserted
 > because most docstrings don't end with one.

Two.  Extra newlines don't hurt.

 > In other words, we simply allow the docstring to be split into parts
 > with code between them, which brings docstrings one step closer to
 > literate programming.
 >
 > The examples from `PEP 258`__ then become::
 >
 >     """g
 >         This is g's docstring."""
 >     g = 'module attribute (module-global variable)'

I see two problems with that:

1. You have redundant information: the attribute name.  The "magic"
    equivalent doesn't need that repetition.

2. As Edward pointed out, getting the relative indentations right is
    very tricky.  The first line of the docstring has no indentation at
    all.

But it is a simpler proposal, much easier to explain and understand.

 >     def f(x):
 >         """Function f's docstring."""
 >         return x**2
 >
 >         """a
 >             Function attribute f.a's docstring."""
 >
 >     f.a = 1

This is stretching things a bit.  I understand why the docstring is at
a different indentation level (inside the function), but there's too
much of a disconnect for my liking.

-- David Goodger

From goodger at python.org  Mon May 24 17:10:49 2004
From: goodger at python.org (David Goodger)
Date: Mon May 24 17:10:56 2004
Subject: [Doc-SIG] Idea: make double-space between sentences meaningful
In-Reply-To: <40A6A075.4090502@users.sf.net>
References: <40A6A075.4090502@users.sf.net>
Message-ID: <40B264D9.8020401@python.org>

[Forwarding to the list with permission]

 >> From: Beni Cherniavsky [mailto:cben@users.sf.net]
 >>
 >> Some formats (notably LaTeX) support the typographical
 >> convention (of some languages, e.g. English but not French
 >> IIRC) of putting a bigger space after the end of a sentence
 >> than between words.  LaTeX tries to guess intellegently but
 >> can fail.  Its guessing can be explicitly overriden.
 >>
 >> Currently, reST provides no way to convey this information to
 >> the output format.  Producing high-quality output requires
 >> this information.  There already exists an obvious convention
 >> supported by programs (e.g. Emacs)
 >> for representing it in plain text: just use a double space
 >> after the end of a sentence.  I propose to make this official
 >> for reStructuredText: more than one space between words after
 >> punctuation  signifies a sentence end.
 >>
 >> Backward compatiblity: at worse, it will force all sentence
 >> ends to single spaces in existing documents that don't use
 >> the double-space convention in the reST source.  It's a good
 >> bet that anybody who cares about it in his LaTeX output also
 >> cares about his source, but it's a good idea to make this a
 >> parser option (defaulting off?)...

The one-space-vs-two-spaces-after-a-sentence debate can be as
religious as any other (as demonstrated by a recent,
embarrassingly-long thread on TECHWR-L). I personally am in the camp
that says that two spaces is OK in monospaced text, but unnecessary
and ugly in a proportional typeface. Thus, I would want two
(end-of-sentence) spaces in source text to result in one space in
proportionally-laid-out output.

It's fine for the parser to convey this information to the writer,
which can then choose whether to use it or ignore it. I would want to
configure most writers to ignore it.

-------------------------
Janet Swisher
Senior Technical Writer
Enthought, Inc.
1-512-536-1057

From Felix.Wiemann at gmx.net  Mon May 31 12:58:13 2004
From: Felix.Wiemann at gmx.net (Felix Wiemann)
Date: Mon May 31 12:57:35 2004
Subject: [Doc-SIG] ``invisible`` reST-directive
Message-ID: <87r7t0a5zu.fsf@news2.ososo.de>

I propose adding a new directive 'invisible' to the reST-syntax, which
translates to the already existing doctree element 'comment'.

Thus, comments could be written as::

    Normal text.

    .. invisible:: This is a comment.
       
       This still belongs to the comment.

    Normal text again.

IMO it's much more intuitive than the '..' syntax for comments.

When the '.. invisible::' directive is available and when it is being
used, we can start phasing out the present comment syntax.

At first, old-style comments can issue an informational system message,
so that one can start replacing old-style comments (with '..') by the
'invisible::' directive.

After some moths, we can start issuing a warning on old-style comments.

Again after some months, we can maybe change the warnings to errors
(that doesn't have to be decided now) and start allowing directives with
a single colon::

    .. image: foo.png

... which is IMO much easier to write and a little bit better to read.
(Of course, there is no need to drop support for the old syntax with two
colons.)

The new directive-syntax with one colon is only possible after having
phased out the old comment-syntax -- see the second point in
<http://docutils.sourceforge.net/spec/rst/alternatives.html#reworking-explicit-markup-round-2>.


IMO an invisible-directive would be a good way to get rid of the the
unintuitive and difficult-to-explain comment-syntax *and* the
double-colon directive-syntax.

What do you think?

-- 
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.

<http://www.ososo.de/>


From goodger at python.org  Mon May 31 13:05:25 2004
From: goodger at python.org (David Goodger)
Date: Mon May 31 13:05:39 2004
Subject: [Doc-SIG] objections to renaming "--exit" option / "exit_level"
	setting?
Message-ID: <40BB65D5.70607@python.org>

Does anybody use the "exit_level" setting ("--exit" option)?  I'm
thinking of changing the names to better reflect the function.
 From docs/config.txt:

"""
exit_level
     A system message level threshold; non-halting system messages at
     or above this level will produce a non-zero exit status at normal
     exit.  Exit status is the maximum system message level plus 10 (11
     for INFO, etc.).

     Default: disabled (5).  Options: ``--exit``.
"""

I think the option originally suggested by Beni Cherniavsky,
"--exit-status", is better.  I'd also change the setting to
"exit_status_level".  I'm sending this message to gauge the impact;
will this break a lot of people's systems?

-- 
David Goodger <http://python.net/~goodger>

From goodger at python.org  Mon May 31 13:28:21 2004
From: goodger at python.org (David Goodger)
Date: Mon May 31 13:28:25 2004
Subject: [Doc-SIG] ``invisible`` reST-directive
In-Reply-To: <87r7t0a5zu.fsf@news2.ososo.de>
References: <87r7t0a5zu.fsf@news2.ososo.de>
Message-ID: <40BB6B35.4060906@python.org>

Felix Wiemann wrote:
 > I propose adding a new directive 'invisible' to the reST-syntax,
 > which translates to the already existing doctree element 'comment'.

I don't like the name "invisible".  Why not "comment"?  There's a
possible objection that it might be confused with admonition
directives, like "note" and "caution", but I consider that to be
minor.

+1 with the name "comment".

And please, let's use another thread for the syntax discussion.

-- 
David Goodger <http://python.net/~goodger>

From goodger at python.org  Mon May 31 13:30:15 2004
From: goodger at python.org (David Goodger)
Date: Mon May 31 13:30:19 2004
Subject: [Doc-SIG] changing comment & directive syntax
In-Reply-To: <87r7t0a5zu.fsf@news2.ososo.de>
References: <87r7t0a5zu.fsf@news2.ososo.de>
Message-ID: <40BB6BA7.1020108@python.org>

(was Re: ``invisible`` reST-directive)

Felix Wiemann wrote:
 > IMO it's much more intuitive than the '..' syntax for comments.
 >
 > When the '.. invisible::' directive is available and when it is
 > being used, we can start phasing out the present comment syntax.

I'm still unconvinced that any change in the syntax is necessary.
I don't see enough benefit to justify the cost in broken documents.
This needs a lot of discussion before we make any changes at all.

Please read and consider all of the points in the entire "Reworking
Explicit Markup (Round 2)" section before forming an opinion:
http://docutils.sourceforge.net/spec/rst/alternatives.html

-- 
David Goodger <http://python.net/~goodger>

From goodger at python.org  Mon May 31 23:42:00 2004
From: goodger at python.org (David Goodger)
Date: Mon May 31 23:42:06 2004
Subject: [Doc-SIG] reStructuredText Cheat Sheet
Message-ID: <40BBFB08.2010505@python.org>

I whipped together a cheat sheet for reStructuredText:
1 page for syntax, and a 1 page reference for directives
and roles.  Please take a look:
<http://docutils.sf.net/docs/rst/cheatsheet.txt> (not
meant to be converted to HTML; use the source text as-is).
Feedback is welcome.

-- 
David Goodger <http://python.net/~goodger>