From list-python@ccraig.org  Fri Sep  6 07:20:51 2002
From: list-python@ccraig.org (Christopher A. Craig)
Date: 06 Sep 2002 02:20:51 -0400
Subject: [Doc-SIG] Documentation inconsistency in re
Message-ID: <t1w65xjy6yk.fsf@kermit.wreck.org>

>From the Library Reference (2.2.1):

\b    Matches the empty string, but only at the beginning or end of a
      word. A word is defined as a sequence of alphanumeric characters, so
      the end of a word is indicated by whitespace or a non-alphanumeric
      character. Inside a character range, \b represents the backspace
      character, for compatibility with Python's string literals.

Now reality:

Python 2.2.1 (#2, Apr 22 2002, 17:53:10) 
[GCC 2.95.4 20011002 (Debian prerelease)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import re
>>> t = re.compile(r'\bbag\b')
>>> t.search('test bag')
<_sre.SRE_Match object at 0x812aad0>
>>> t.search('test+bag')
<_sre.SRE_Match object at 0x815d528>
>>> t.search('test_bag')
>>> [ chr(i) for i in xrange(256) if not t.search('test' + chr(i) +
'bag') ]
['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D',
'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R',
'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '_', 'a', 'b', 'c', 'd', 'e',
'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's',
't', 'u', 'v', 'w', 'x', 'y', 'z']
>>> 


So the implementation appears to define a word as a sequence of
alphanumeric characters or underscores, which means either the
documentation, or the library is wrong.  Now it happens that this was
found while a friend of mine and I were looking to get the exact
behavior that is implemented, so I'd prefer it if the documentation
were updated to meet the implementation <.8 wink>.

-- 
Christopher A. Craig <list-python@ccraig.org>
I develop for Linux for a living, I used to develop for DOS.  Going from
DOS to Linux is like trading a glider for an F117. - Lawrence Foard


From fredrik@pythonware.com  Fri Sep  6 07:47:12 2002
From: fredrik@pythonware.com (Fredrik Lundh)
Date: Fri, 6 Sep 2002 08:47:12 +0200
Subject: [Doc-SIG] Re: [Python-Dev] Documentation inconsistency in re
References: <t1w65xjy6yk.fsf@kermit.wreck.org>
Message-ID: <00e401c25571$3e6bc1f0$ced241d5@hagrid>

Christopher A. Craig wrote:

> >From the Library Reference (2.2.1):
> 
> \b    Matches the empty string, but only at the beginning or end of a
>       word. A word is defined as a sequence of alphanumeric characters, so
>       the end of a word is indicated by whitespace or a non-alphanumeric
>       character. Inside a character range, \b represents the backspace
>       character, for compatibility with Python's string literals.

as you suspected, the documentation is flawed: \b is defined
in terms of \w and \W.

</F>



From skip@pobox.com  Fri Sep  6 15:39:02 2002
From: skip@pobox.com (Skip Montanaro)
Date: Fri, 6 Sep 2002 09:39:02 -0500
Subject: [Doc-SIG] Re: [Python-Dev] Documentation inconsistency in re
In-Reply-To: <t1w65xjy6yk.fsf@kermit.wreck.org>
References: <t1w65xjy6yk.fsf@kermit.wreck.org>
Message-ID: <15736.48646.910216.93578@12-248-11-90.client.attbi.com>

    Christopher> So the implementation appears to define a word as a
    Christopher> sequence of alphanumeric characters or underscores, which
    Christopher> means either the documentation, or the library is wrong.

Documentation has been fixed.

Skip


From goodger@users.sourceforge.net  Sat Sep  7 18:24:07 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sat, 07 Sep 2002 13:24:07 -0400
Subject: [Doc-SIG] FW: [Docutils-develop] Forcing line breaks
In-Reply-To: <B99FABBE.28872%goodger@users.sourceforge.net>
Message-ID: <B99FAE76.28875%goodger@users.sourceforge.net>

(Forwarding to the Doc-SIG to solicit opinions.)

[Adam]
>>> Is there any way to force line breaks? Example of usage::
>>> 
>>>   :Name:    Adam Chodorowski
>>>   :Address: The Street
>>>             11111 The Town
>>>             The Country
>>>   :Phone:   +11-111111

[David]
>> If you're using a recent snapshot, it's already taken care of for
>> you. The "Address" field should produce the equivalent of a
>> line_block element, which is exactly what you describe.

[Adam]
> I'm guessing that is only valid for a bibliographic fields...

Yes.  Special processing in a specific context, which cannot be
assumed anywhere else.

>> - You shouldn't really be using field lists in the first place.
>>   They're for extension syntax (docinfo & directive options).  I'll
>>   make this more explicit in the docs.  Perhaps a table or a
>>   definition list would be better?
> 
> I disagree strongly on this. Why on earth shouldn't fields lists be
> usable as a construct of their own?

On April 25, I clarified the spec to say this about field lists: "They
are not intended to be an alternative to definition lists or tables."
I made this admonition stronger yesterday: "Field lists should only be
used when and where application code specifically expects them; they
should *not* be used as arbitrary constructs in documents."

Before you begin your reply, please read to the end.  (It's one of my
thinking-an-issue-through-to-the-end essays.)

> Definition lists do fit *conceptually*, but unfortunately not with
> regard to presentation. When you specify contact information or
> similar data, you almost always do it like this::
> 
>   Name:    Adam Chodorowski
>   Address: The Street 42
>            11111 The City
>   Country: Sweden
>   Phone:   +46-8-1111111

Actually, I would write it like this::

    Adam Chodorowski
    The Street 42
    11111 The City
    Sweden
    phone +46-8-1111111

Most of the labels are redundant; people know how to read addresses
from context.

> Having definition lists is *not* intuitive for the reader
...
> nobody excepts contact information to be presented that way.

I wouldn't expect contact information to be presented the "field list"
way either.  Are conventions so different in Sweden?  Do you really
need to label everything?  (But this is avoiding the real issue.)

> Field lists are IMHO perfect for "single vertical table rows". Just
> what the doctor ordered. ;-)

This may a case of abusing markup because it gives the desired
results.  In DocBook terms, it's like a doc writer using <emphasis>
instead of <glossterm>, because they want italics in the output.  A
*side effect* of <glossterm> may be italics, but the main effect may
be quite different (hyperlinking all glossterms to a glossary, for
example).

But I do see Adam's point.  I've been moving towards thinking about
field lists purely as an extension syntax, not as a generic construct.
 Partly this is due to outside influence, the incessant
"reStructuredText is too complex!" from certain parties.  So we have
to choose:

1. Field lists shall be restricted to extension syntax use (directive
   options, docinfo) only.

2. Field lists shall also be available to authors as a generic
   two-column table/list construct.

There are consequences.  If we choose #1, we should remove field list
support from writers; it would be an error for an unprocessed field
list to remain in the document tree.  If we choose #2, we should ask
ourselves, are field lists generic *enough*?

The current field list syntax (geared toward extension syntax use,
choice #1) was modeled after RFC 2822's fields and JavaDoc's "@tags".
It limits field names to single (possibly compound) words.  Anything
after whitespace is taken to be field arguments, which are
semantically and presentationally separate from field names.  Field
arguments allow the equivalent of a JavaDoc "@param name description"
tag.

In Adam's contact info block above, there's a "phone" field.  What if
he wants to differentiate between phone numbers (home, cell, pager)?
Let's assume that in Swedish we cannot rework the field names into
single words; we *have* to use multiple words.  We'd want this as
output::

    Home Phone:   +46-8-1111111
    Cell Phone:   +46-8-2222222
    Pager Number: +46-8-3333333

The closest we could get with current field lists would be like this::

    :Home-Phone:   +46-8-1111111
    :Cell-Phone:   +46-8-2222222
    :Pager-Number: +46-8-3333333

(Underscores could be used instead of hyphens.)  I doubt that this
would be acceptable to most document authors, and the output (with
hyphens intact) would look strange to readers.  The alternative is to
redefine field lists to allow multi-word field names, and use a
different syntax for field arguments.  Perhaps something like this::

    :Field name <field arguments>: Field body

Or perhaps we just drop the idea of field arguments altogether, and
rely on the application code to parse the field name as it likes.

Apart from the test suite, the only place where field arguments are
used is in the "meta" directive, which produces <meta> tags.  This is
from tools/test.txt::

    .. meta::
       :keywords: reStructuredText, test, parser
       :description lang=en: A test document, containing at least one
           example of each reStructuredText construct.

The "meta" directive code would have no problem extracting the
"lang=en" argument from the field name.  The "meta" directive would
specify that the first word of the field name would be taken as the
"name" attribute, and the rest should be "attname=value" attribute
definitions.

I'm beginning to like this change.  If we drop the notion of "field
arguments", field lists become simpler and fully generic.  Then I'd
drop my objection to their use as a generic document construct.  Any
objections to this change?

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From goodger@users.sourceforge.net  Wed Sep 11 04:06:38 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Tue, 10 Sep 2002 23:06:38 -0400
Subject: [Doc-SIG] Field arguments dropped (was Re: Forcing line breaks)
In-Reply-To: <B99FABBE.28872%goodger@users.sourceforge.net>
Message-ID: <B9A42B7D.28A8E%goodger@users.sourceforge.net>

I wrote:
> Or perhaps we just drop the idea of field arguments altogether, and
> rely on the application code to parse the field name as it likes.

And now it's implemented.  Field lists are now freely usable as generic
document constructs.  Field names may have multiple words, although
restrictions may be imposed by (and the interpretation depends on)
application code.  Short form: field lists are more general-purpose now,
with no problems anticipated.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From goodger@users.sourceforge.net  Sun Sep 15 15:35:02 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sun, 15 Sep 2002 10:35:02 -0400
Subject: [Doc-SIG] Relax the 4-character minimum on section title underlines?
Message-ID: <B9AA12D5.28DBB%goodger@users.sourceforge.net>

I am considering relaxing the 4-character minimum requirement for
reStructuredText section title underlines, and would like to determine
the best course of action.  The spec states:

    An underline/overline is a single repeated punctuation character
    that begins in column 1 and forms a line extending at least as far
    as the right edge of the title text. ...  An underline/overline
    must be at least 4 characters long (to avoid mistaking ellipses
    ["..."] for overlines).

    (http://docutils.sf.net/spec/rst/reStructuredText.html#sections)

The 4-character minimum on transition markers will remain, regardless.

Sometimes a title is less than 4 characters long, and it's natural to
want to use an underline of exactly the same length.  I've noticed
such cases in others' documents, and in my own.  In my own document, I
used a 3-character underline; the title was parsed as an ordinary
paragraph and it took some time to discover the problem and fix it,
because the parser produced no warning.

Here's the current entry in the "Bugs" section of the "To Do" list:

    Section headers must have underlines at least 4 characters long.
    But when the section title is only 3 characters long, it's natural
    to underline with "===" (I just did).  The parser should produce a
    warning in such cases.

    Or should the parser simply recognize such short underlines?  A
    zero-tolerance policy might work: over/underlines of 3 or fewer
    characters which are shorter than the "title" text are not
    recognized as titles, and should generate an "info" message.

There has also been a bug report submitted on the issue (by Jeremy
Hylton):
http://sf.net/tracker/?func=detail&atid=422030&aid=608108&group_id=38414

There's no problem with the typical case, where the over/underlines
are at least as long as the title text::

    ABC
    ===
    
    ---
    DEF
    ---

But what to do when the over/underline is too short?  Ellipsis ("...")
and m-dash (commonly written "---") both use 3 repeated punctuation
characters; this ambiguity is what the 4-character minimum avoided.  For
example::

    Is This Supposed To Be A Title?
    ---

    This, surely, is not
    ...

In these cases, I'm thinking of inserting INFO (level 1) system
messages that say, "Possible title underline, too short for the title
text.  Treating it as ordinary text because it's so short."  INFO
system messages are not normally visible (shown only if the
-v/--verbose option is used).  In other words, short underlines (<= 3
characters) are recognized as title adornments if they're long enough
for the title text, but if they're too short they're just wrapped text
plus a normally-invisible system message.  I think this is the right
balance of precision (unambiguous, unsurprising) and "do what I say"
(intuitive).

How about these cases, of overlines?  Unless stated otherwise, the
short overlines would each be treated as ordinary text and an INFO
system message inserted::

    ...
    This is not a title; perhaps an excerpt from a quote.

    ..
    This is interpreted as a comment start immediately followed by a
    paragraph.  Triggers a "no blank line; unexpected unindent"
    warning.

    ==
    These lines would not be interpreted as a title.
    ==

    ---
    The three dashes above might represent an m-dash.

    ==
      Would this become a definition list?

    ==
      And what about this?  A definition list item followed by a
      paragraph and a "no blank line; unexpected unindent" warning.
    ==

And when section titles are not expected/allowed::

    Ordinary paragraph.

        This title should trigger a SEVERE error (sections not allowed
        inside block quotes), as currently happens with longer titles:

        ABC
        ===

        This title should trigger an INFO message and be treated as an
        ordinary paragraph, since the underline is too short for the
        title:
        
        ABC
        ==

Does all of this seem reasonable?  Any gotchas I'm missing?

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From goodger@users.sourceforge.net  Sun Sep 15 17:59:06 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sun, 15 Sep 2002 12:59:06 -0400
Subject: [Doc-SIG] ANN: DocFactory wxPython app for Docutils
Message-ID: <B9AA3498.28DFB%goodger@users.sourceforge.net>

Gunnar Schwant has contributed DocFactory, a wxPython GUI application for
Docutils.  It is in the preliminary stages.  For details, please see

    http://docutils.sf.net/sandbox/gschwant/docfactory/README.html

I have begun a "To Do" list:

    http://docutils.sf.net/sandbox/gschwant/docfactory/NOTES.html

The code is available via CVS or snapshot:

    http://docutils.sf.net/docutils-sandbox-snapshot.tgz

Please try it out.  Feedback is welcome: bug reports, patches, feature
ideas, etc.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From ianatkin@blueyonder.co.uk  Thu Sep 19 12:37:51 2002
From: ianatkin@blueyonder.co.uk (Ian Atkin)
Date: Thu, 19 Sep 2002 12:37:51 +0100
Subject: [Doc-SIG] converting tex? use of docbook?
Message-ID: <3D89B70F.9030509@blueyonder.co.uk>

hello,

python newbie very interested in tech writing
while learning python i'm focusing on doc systems, tool-chains etc
comming from a java/xml/xslt/docbook background and want to dive in to 
python's doc platform

here's my views (to prevent flames, not provoke :-)
- structured markup is a Good Thing
- xml's simplicity outweighs sgml's power (in the end)
- tool-chains are a mess, so whatever works...
- authoring is in a state, so whatever syntax folks are prepared to use 
is sound
- docbook is a beast, but a beautiful one :-)

here's my questions:-
- is there any motivation to move python's doc format to xml docbook? 
can i contrib/promote in any way? (i read a mention of a "python doc 
project" like the ldp)
- what "types" of document are most commonly used/wanted in the python 
distro/apps and do these require unique markup?
- are there any open tools (or chains) around to convert tex source into 
xml (xslt scripts can do the rest)?

i've got loads of other questions and ideas, but need to fathom the 
world of python doc tools (docutils, happydoc, etc) in order not to 
appear more stupid than i am, expect more mails...






From goodger@users.sourceforge.net  Fri Sep 20 04:24:34 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 19 Sep 2002 23:24:34 -0400
Subject: [Doc-SIG] Re: Relax the 4-character minimum on section title underlines?
In-Reply-To: <B9AA12D5.28DBB%goodger@users.sourceforge.net>
Message-ID: <B9B00D30.29299%goodger@users.sourceforge.net>

I have removed the 4-character minimum requirement for section title
underlines and overlines.  The following section titles will now
process as expected::

    ABC
    ===

    ---
    DEF
    ---

The original reason for the minimum was to avoid misinterpretation of
common punctuation constructs, such as ellipsis ("...") and m-dash
("---").  The parser now allows for such constructs where they may
otherwise be misinterpreted as title adornments.  For example, all of
the following will parse as ordinary paragraphs::

    This is not a title
    ...

    ...
    nor is this

    Or this
    ---

Level-1/INFO system messages are inserted wherever there's any
question.  Normally, level-1/INFO messages are not visible; to see
them, use the --verbose, -v, or --report-level=info options.

There is still one limitaton.  A two-period overlined title is not
possible, because it will be parsed as a comment start.  The text
immediately following will generate a warning because there's no
intervening blank line::

    ..
    Hi
    ..

Extending the over/underlines to 3 characters makes it work::

    ...
    Hi
    ...

A two-period *underline* has no problem though::

    Hi
    ..

In other recent news:

* A subtle bug that introduced unwanted empty rows in some "simple"
  tables has been fixed.

* The locale-setting code in front ends has been made fault-tolerant.

* The definition of "simple reference names" has been altered
  slightly: internal hyphens, periods, and underscores may only occur
  one at a time, not two or more adjacent.  This prevents text like
  "object.__method__" from being parsed as a reference (because of the
  trailing underscores).  If any such text *does* exist, it can always
  be quoted like this::

    reference to `object.__method__`_

The CVS snapshot is always up to date and available at:

    http://docutils.sf.net/docutils-snapshot.tgz

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From goodger@users.sourceforge.net  Wed Sep 25 04:12:30 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Tue, 24 Sep 2002 23:12:30 -0400
Subject: [Doc-SIG] converting tex? use of docbook?
In-Reply-To: <3D89B70F.9030509@blueyonder.co.uk>
Message-ID: <B9B6A1DD.296DC%goodger@users.sourceforge.net>

Nobody has answered yet, so I'll give it a shot.  These are just my
opinions here, nothing official.

Ian Atkin wrote:
> here's my questions:-
> - is there any motivation to move python's doc format to xml
> docbook?

There has been discussion in the past, and there seems to have been
some consensus on moving towards XML, but I don't think there's enough
of a benefit to move away from the current TeX markup and toolchain.
The current setup is mature and works well ("it ain't broke"), so
there's little perceived need to "fix" it.

> can i contrib/promote in any way? (i read a mention of a "python doc
> project" like the ldp)

There's plenty of room for tech *writing* contributions.  As for
writing *code*, unless you're willing to do a very complete and
high-quality job, I doubt if an effort to replace the existing core
documentation system would be well-received.  But there are lots of
other places where you can contribute.  May I suggest you take a look
at Docutils (http://docutils.sf.net/)?  If you like DocBook, there's a
"DocBook output writer" component that's partially finished.

> - what "types" of document are most commonly used/wanted in the
> python distro/apps and do these require unique markup?

I can think of the following classifications for Python documents:

A) Core documentation.  This is what comes with Python.  The source
   files are TeX; HTML and others are generated from the TeX files.
   For details, see "Documenting Python" at

       http://www.python.org/doc/current/doc/doc.html

B) Inline documentation.  Python modules have documentation strings,
   or "docstrings", in the source code.  Modules in Python's standard
   library have some inline docs, but they're merely hints; the core
   documentation is emphasized.  Third-party projects often maintain
   their API docs in docstrings, and extract them with HappyDoc or
   Crystal or PythonDoc etc.; Docutils plans to support this
   functionality in the future too.  Sometimes the docstrings have
   markup, sometimes they're plaintext.  See PEP 257 for more:

       http://www.python.org/peps/pep-0257.html

C) Project standalone documentation.  These are documents specific to
   a project, and the markup used is up to the project contributors.
   Anything is possible here.

D) Online help.  Some projects have online help documentation, often
   in the native format supported by the platform.

> - are there any open tools (or chains) around to convert tex source
> into xml (xslt scripts can do the rest)?

That I don't know.  Have you checked Google?

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From fdrake@acm.org  Wed Sep 25 18:08:18 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 25 Sep 2002 13:08:18 -0400
Subject: [Doc-SIG] converting tex? use of docbook?
In-Reply-To: <B9B6A1DD.296DC%goodger@users.sourceforge.net>
References: <3D89B70F.9030509@blueyonder.co.uk>
 <B9B6A1DD.296DC%goodger@users.sourceforge.net>
Message-ID: <15761.60802.556455.999812@grendel.zope.com>

David Goodger writes:
 > Nobody has answered yet, so I'll give it a shot.  These are just my
 > opinions here, nothing official.

And what would constitute official anyway?  Sheesh!  ;-)  You're doing
just fine!

 > There has been discussion in the past, and there seems to have been
 > some consensus on moving towards XML, but I don't think there's enough
 > of a benefit to move away from the current TeX markup and toolchain.
 > The current setup is mature and works well ("it ain't broke"), so
 > there's little perceived need to "fix" it.

You got it!  For all the pain of parsing LaTeX markup, there's little
need to do so.  The light weight of LaTeX is actually quite
compelling.

At the last Python conference, we discussed moving to XML for the
purpose of being able to use next-gen tools to support translation
efforts, but no one has even had time to summarize the discussion,
much less make progress on that front.

 > There's plenty of room for tech *writing* contributions.

That's certainly what I would think is most useful; markup can be
applied with relative ease once we have content.

 > C) Project standalone documentation.  These are documents specific to
 >    a project, and the markup used is up to the project contributors.
 >    Anything is possible here.

Not too surprisingly, I think an increasing number of projects are
using the Python LaTeX styles to do this.  In spite of LaTeX
disappearing in most places, the Python world is in an unusual
situation in that we have an easy-to-use markup built on top of
standard LaTeX with a variety of output formats (where the most common
forms actually look pretty good, IM(NSH)O).

Ian Atkin asked:
 > - are there any open tools (or chains) around to convert tex source
 > into xml (xslt scripts can do the rest)?

There's some stuff checked into Doc/tools/sgmlconv/, very specific to
the Python documentation format, and not always working.  It's in a
broken state now, but I've not had time to really look at the problem.


  -Fred

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


From uhe@stahl-groeditz.de  Wed Sep 25 23:05:12 2002
From: uhe@stahl-groeditz.de (Uwe Hentzschel)
Date: Thu, 26 Sep 2002 00:05:12 +0200
Subject: [Doc-SIG] table with border="0"
Message-ID: <20020925220512.GA22106@lxhost.stahl-groeditz.de>

Is it possible to provide a table with border="0" ? 

uhe


From goodger@users.sourceforge.net  Thu Sep 26 00:04:45 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 25 Sep 2002 19:04:45 -0400
Subject: [Doc-SIG] table with border="0"
In-Reply-To: <20020925220512.GA22106@lxhost.stahl-groeditz.de>
Message-ID: <B9B7B94C.29708%goodger@users.sourceforge.net>

Uwe Hentzschel wrote:
> Is it possible to provide a table with border="0" ?

In what?  What software, what markup, what medium?  Details!

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From goodger@users.sourceforge.net  Thu Sep 26 02:55:57 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 25 Sep 2002 21:55:57 -0400
Subject: [Doc-SIG] converting tex? use of docbook?
In-Reply-To: <15761.60802.556455.999812@grendel.zope.com>
Message-ID: <B9B7E16C.297AD%goodger@users.sourceforge.net>

David Goodger writes:
 > These are just my opinions here, nothing official.

and Fred Drake replied:
> And what would constitute official anyway?

Why, the words of our Documentation Czar, of course!  I'm just the
lowly Tyrant-Vassal of Docutils.

> Sheesh!  ;-) You're doing just fine!

Thanks.  And thanks for the official corroboration. ;-)

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From edloper@gradient.cis.upenn.edu  Thu Sep 26 08:12:50 2002
From: edloper@gradient.cis.upenn.edu (Edward Loper)
Date: Thu, 26 Sep 2002 03:12:50 -0400
Subject: [Doc-SIG] epydoc 1.0 release
Message-ID: <3D92B372.1010605@gradient.cis.upenn.edu>

I just released version 1.0 of epydoc.  Epydoc is a tool for generating
API documentation for Python modules, based on their docstrings.

     <http://epydoc.sourceforge.net/>

It uses a markup language that is similar in some ways to reST, but
simpler (and I would say cleaner :) ).  It produces output similar to
javadoc; for an example of its output, see the API documentation for
epydoc itself:

     <http://epydoc.sourceforge.net/api/epydoc.html>

For a more extensive example (and a different stylesheet), see the API
documentation for NLTK (the natural language toolkit):

     <http://nltk.sourceforge.net/ref/nltk.html>

Epydoc is now fairly mature, and I don't plan to do much more work on
it in the near future.  But if/when docutils becomes The Standard
Framework for docstring tools, I will look into integrating epydoc into
the docutils framework (as a reader/parser and a writer/formatter).
I've been pretty happy with epydoc's markup langauge (epytext), and
hopefully if it gets integrated with docutils, other people will find
it useful too.

Below is a description of how the epytext markup language relates to
reST (the current standard markup language for docutils), for anyone
who's interested.  If you're interested in the epytext markup language
itself, but don't care how it relates to reST, then see the epytext
manual <http://epydoc.sourceforge.net/epytext.html>.  If you're not
interested at all, then go read the rest of your email. :)

-Edward

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First of all, let me note that epytext and reST have very different
goals: reST is a very general-purpose markup language, that is good
for PEPs, webpages, etc.  Epytext is intended only for API
documentation generation.

Both epytext and reST markup can be divided into "block structure"
(paragraphs, lists, etc) and "inline markup" (italics, hyperlinks,
etc).  I'll discuss them separately.

Block structure
===============
   Epytext's block structure is basically a "light" version of reST,
   that's somewhat less leniant (e.g., underline length must match
   heading length).  In particular, it supports the following block
   structure constructs using basically the same syntax that reST
   uses:

       - paragraphs
       - unordered lists (bullet must be "-")
       - ordered lists (bullets must match "(\d+[.])+", like "12." or
         "3.2.")
       - literal blocks
       - doctest blocks
       - sections (underlines only, heading underline characters
         restricted to '=', '-', and '~'.)

   It also defines "field lists," which are like reST field lists,
   but have a different syntax -- bullets have the form "@\w+:" or
   "@\w+ \w+:", like "@return:" or "@param x:"

Inline markup
=============
   Epytext inline markup is fairly different from reST inline markup.
   All epytext inline markup has the form "x{...}", where "x" is a
   single capital letter.  This makes markup easy to spot, and makes
   nesting obvious.

   A matching pair of curly braces is only interpreted as inline markup
   if the left brace is immediately preceeded by a capital letter.  So
   in most cases, you can use curly braces in your text without any
   form of escaping.  However, you do need to escape curly braces when:

       - You want to include a single (un-matched) curly brace.
       - You want to preceed a matched pair of curly braces with a
         capital letter.

   I grepped through a pretty large number of docstrings, and both of
   these cases seem pretty rare.  Note that there is no valid Python
   expression where a pair of matched curly braces is immediately
   preceeded by a capital letter (except within string literals).  In
   particular, you never need to escape braces when writing Python
   dictionaries.

   I think that reST uses too many different inline markup constructs,
   that can interact with each other in weird and non-intuitive ways.
   A couple of them may have some value as "intuitive".  In particular,
   *emphasis* is widely used (though it's not obvious to me whether
   that should be bold or italics).  But constructs like ``this`` and
   #this# and `this`_ seem significantly less obvious to me.  I prefer
   a single unified inline markup syntax, that almost never requires
   any escaping.

For a more detailed description of the epytext markup language, see
the epytext manual on the epydoc homepage:

     <http://epydoc.sourceforge.net/epytext.html>



From goodger@users.sourceforge.net  Fri Sep 27 02:21:21 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 26 Sep 2002 21:21:21 -0400
Subject: [Doc-SIG] epydoc 1.0 release
In-Reply-To: <3D92B372.1010605@gradient.cis.upenn.edu>
Message-ID: <B9B92AD0.298B2%goodger@users.sourceforge.net>

Edward Loper wrote:
> I think that reST uses too many different inline markup constructs,
> that can interact with each other in weird and non-intuitive ways.

You're entitled to your opinion, of course.  But can you back up this
claim of "weird and non-intuitive" interaction?

> But constructs like ``this`` and
> #this# and `this`_ seem significantly less obvious to me.

Correction: #this# has no meaning in reStructuredText.

> I prefer a single unified inline markup syntax, that almost never
> requires any escaping.

To each his own. :-)  But please note that reStructuredText inline
markup rarely requires any escaping.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From edloper@gradient.cis.upenn.edu  Fri Sep 27 02:55:46 2002
From: edloper@gradient.cis.upenn.edu (Edward Loper)
Date: Thu, 26 Sep 2002 21:55:46 -0400
Subject: [Doc-SIG] epydoc 1.0 release
References: <B9B92AD0.298B2%goodger@users.sourceforge.net>
Message-ID: <3D93BAA2.3030303@gradient.cis.upenn.edu>

> Edward Loper wrote:
>>I think that reST uses too many different inline markup constructs,
>>that can interact with each other in weird and non-intuitive ways.

David Goodger wrote:
> You're entitled to your opinion, of course.  But can you back up this
> claim of "weird and non-intuitive" interaction?

The rules that govern when "*" is markup vs. just an asterisk.  For 
example, at least according to my understanding of the rules..
   - This will not be marked as emph: *un*believable
   - This will be marked as emph: *.*
   - This will be marked as emph: *.txt and foo.* (even if those two
     words are separated by several lines?)
   - This will be not be marked as emph: *edloper*@wherever

As for interaction, it's not obvious which markups should nest inside 
which other markups..  E.g., is ***this* ok**?

One of the problems with trying to guess what the user is thinking is 
that there will always be borderline cases.  And as the algorithm that's 
doing the guessing gets more complex, the user is less likey to remember 
what they need to escape.  Also, as the algorithm gets more accurate, 
the user is less likely to notice the occasional places where it doesn't 
get things right.

I think that *given* the goal of guessing what the user means, you've 
done a very admirable job of coming up with high-coverage rules (on the 
docutils page you imply 90% mind-reading coverage for non-markup use of 
"*".. I'd actually say it's significantly higher).  But I actually find 
it easier in the long run for me to try to understand the markup, rather 
than having the markup trying to understand me.  And it's much easier 
for me to understand inline markup if it can be explained in 2 or 3 
sentences, rather than 10 or 15 paragraphs. :)

> Correction: #this# has no meaning in reStructuredText.

Sorry, I haven't been paying attention to which markup is current (I 
remember #this# being proposed at some point).  But there are others 
like |this|

>>I prefer a single unified inline markup syntax, that almost never
>>requires any escaping.
> 
> To each his own. :-)  But please note that reStructuredText inline
> markup rarely requires any escaping.

I agree..  The problem I have is that I'm not smart enough to remember 
when it *does* require escaping. :)

I think that reST is a pretty good markup language, and I know a lot of 
thought has gone into it..  I just don't think it's the markup language 
for me. :)

-Edward



From dallasm@aiinet.com  Mon Sep 30 23:40:03 2002
From: dallasm@aiinet.com (Mahrt, Dallas)
Date: Mon, 30 Sep 2002 18:40:03 -0400
Subject: [Doc-SIG] Docstring Standards
Message-ID: <638AA0336D7ED411928700D0B7B0D75B02E1F012@aimail.aiinet.com>

Background: I am in the process of defining some internal programming
standards for my company. One aspect we are keenly interested in is defining
the docstring syntax such that we can facilitate documentation generation
(similar to Doxygen or JavaDoc which we use currently) I have read about the
docutils project and feel it is probably the best fit (in the long term) for
our needs, however I have a question.

1) Method signatures. 
In Doxygen and JavaDoc, there is an explicit ''@param'' syntax for defining
the documentation related to a parameter. There are similar constructs for
''@exception'' and ''@return''. The only thing similar I have found in
docutils documentations is the use of explicit roles. Ex.

    def foo(bar):
        """This is foo.

        :parameter"`foo` - This is a foo
        """

Is this the *standard* way of documenting parameters? If not is there a
standard? If so is there a similar concept for raised exceptions and return
values? 

The only thing I've noticed in practice are English descriptions with
literal references. Ex.

    def foo(bar):
        """This is foo.

        Passes `foo` which is a foo.
        """

This seems to be more difficult to extract the description from the
identifier for a more tabular representation (like JavaDoc)

---
Dallas S. Mahrt              dallasm@aiinet.com
Software Engineer            Applied Innovation Inc.