From goodger@users.sourceforge.net  Wed Feb  6 03:37:44 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Tue, 05 Feb 2002 22:37:44 -0500
Subject: [Doc-SIG] DPS & reStructuredText updated
Message-ID: <B8860F37.1E3B5%goodger@users.sourceforge.net>

I've been adding features lately. Latest snapshots available in 90 minutes
from:

    http://docstring.sourceforge.net/dps-snapshot.tgz
    http://structuredtext.sourceforge.net/rst-snapshot.tgz

New:

- A "Visitor" pattern to the doctree (dps/nodes.py).
- Functional "Reader" (dps/readers/standalone.py; thanks Ueli!).
- Minimal "Writer" (dps/writers/pprint.py).
- Reworked system_warning/Reporter mechanism with log4j influence.
- A bunch of transforms (dps/transforms/).

I'd like to add a bit more functionality (such as access from
tools/quicktest.py or some other front-end, plus a simple HTML writer) and
update the PEPs, then I'll make and announce new releases (v0.4 of each).
Following this, I'll merge the parser into the DPS project; there's too much
duplication in the test code now. The project will be renamed to "docutils"
as well.

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



From fdrake@acm.org  Fri Feb  8 18:25:35 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 8 Feb 2002 13:25:35 -0500
Subject: [Doc-SIG] Support for non-English-speaking users
Message-ID: <15460.6175.409706.680370@grendel.zope.com>

Currently, there is a single Web page at python.org which provides
links to non-English resources:

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

This page includes entries for 18 different languages (at the moment),
including many which aren't served well by the default Latin-1
encoding for the Web page containing the list.  We've gotten by so far
because most of the descriptions are written in English, which doesn't
make a lot of sense for the target audience.

What I'd like to do is get a group of voluteers to maintain a set of
pages, one for each language, written in the same language as the
resources being described.  Each page could use the most appropriate
character set, and the page at the current URL would be replaced with
the index the language-specific pages.

I'd like one volunteer to help coordinate the effort and make the
actual changes to the site.  This person would have write-access to
the CVS repository which contains the python.org pages.

[I proposed something similar a couple of years ago, but the matter
 was somewhat less pressing at the time, and I was better able to
 manage the current list of translations myself.  There are now more
 pressures on my time and it has become easier to support volunteers
 to help maintain python.org.]

If you're interested in volunteering, please send email to
python-docs@python.org.  Suggestions for alternative approaches or
additional ways to help should be sent to the Doc-SIG mailing list.

Please feel free to forward this message to people you feel may be
interested in helping out who are not on the Doc-SIG mailing list!

Thanks!


  -Fred

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


From fdrake@acm.org  Fri Feb  8 18:26:12 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 8 Feb 2002 13:26:12 -0500
Subject: [Doc-SIG] Support for translators
Message-ID: <15460.6212.333553.240306@grendel.zope.com>

There have been a number of attempts to create mailing lists for
translators, and organize translation efforts.  At least some lists
have disappeared as people change jobs and their old employers drop
support for the mailing lists run on their servers.  Knowing what
efforts are active can also be difficult.

I'd like to hear if translators think having a stable list hosted on
python.org would help.  We can set up either a single list for
organizing translation efforts or lists for languages with many
translators, if needed.  (Large, organized efforts may be better
served by SourceForge projects.)

I'd also like to find a volunteer interested in maintaining an
up-to-date list of translation efforts, whether the efforts are
individual or organized group efforts.

If you're interested in volunteering, please send email to
python-docs@python.org.  Suggestions for alternative approaches or
additional ways to help should be sent to the Doc-SIG mailing list.

Please feel free to forward this message to people you feel may be
interested in helping out who are not on the Doc-SIG mailing list!

Thanks!


  -Fred

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


From goodger@users.sourceforge.net  Wed Feb 27 03:57:22 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Tue, 26 Feb 2002 22:57:22 -0500
Subject: [Doc-SIG] Field lists for directive attributes?
Message-ID: <B8A1C350.1F38E%goodger@users.sourceforge.net>

reStructuredText's image and figure directives currently use a
specialized "[name=value]" attribute specification syntax::

    .. image:: picture.png
       [height=100 width=200 scale=50 alt="alternate text"]

There's a mini-parser called "dps.utils.parseattributes". It does a
decent job, but it can't handle complex stuff like::

       [alt="Joe \"Bulldog\" O'Roarke"]

I'm thinking of replacing the "[name=value]" syntax with field lists
for attributes::

    .. image:: picture.png
       :height: 100
       :width: 200
       :scale: 50
       :alt: alternate text

Advantages: standard syntax (less to remember), easier implementation,
more straightforward, more robust, more flexible, emphasizes role of
field lists as "extension/specialized syntax" (as currently used in
bibliographic field lists and the "meta" directive).

Disadvantage: more verbose.

It seems useful to standardize on a single syntax, which may be used
in other directives in the future. Throwing away the current system
and reusing field lists appeals to me on minimalistic principles.

Any objections or alternate ideas?

-- 
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  Wed Feb 27 07:51:07 2002
From: garth@deadlybloodyserious.com (Garth Kidd)
Date: Wed, 27 Feb 2002 18:51:07 +1100
Subject: [Doc-SIG] Field lists for directive attributes?
In-Reply-To: <B8A1C350.1F38E%goodger@users.sourceforge.net>
Message-ID: <000001c1bf63$867b4e60$8501010a@gkiddlap>

>        [alt="Joe \"Bulldog\" O'Roarke"]
... 
>     .. image:: picture.png
>        :height: 100
>        :width: 200
>        :scale: 50
>        :alt: alternate text

How does someone specify \n in a field? 

<grins, ducks, runs>

Regards,
Garth.



From goodger@users.sourceforge.net  Thu Feb 28 01:57:52 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 27 Feb 2002 20:57:52 -0500
Subject: [Doc-SIG] Field lists for directive attributes?
In-Reply-To: <000001c1bf63$867b4e60$8501010a@gkiddlap>
Message-ID: <B8A2F8D0.1F397%goodger@users.sourceforge.net>

Garth Kidd wrote:
> How does someone specify \n in a field?

::

    :name: field
           body

There's a newline between "field" and "body".

So let me anticipate the next question: "How does someone specify
*only* \n in a field?" Can't. Not without some directive/substitution
trickery, anyhow.

Hmm. Maybe this? ::

    :name: \

I don't know what the parser as written would do with it.

> <grins, ducks, runs>

You cheeky devil.

-- 
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 Feb 28 04:24:56 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 27 Feb 2002 23:24:56 -0500
Subject: [Doc-SIG] docutils teaser
Message-ID: <B8A31B46.1F46C%goodger@users.sourceforge.net>

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)
- http://structuredtext.sourceforge.net/spec/reStructuredText.html
  (published from source at
  http://structuredtext.sourceforge.net/spec/reStructuredText.txt)

They're temporary, so don't bother linking to them. There will be permanent
versions soon.

-- 
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 Feb 28 05:07:00 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 28 Feb 2002 00:07:00 -0500
Subject: [Doc-SIG] some ideas for reStructuredText & document model
Message-ID: <B8A32523.1F470%goodger@users.sourceforge.net>

Looking at the recent HTML output, I've had some ideas regarding changes to
the reStructuredText syntax and the Docutils document model. Please comment
on any or all. Thanks.

- Change footnote syntax from ``.. [1]`` to ``_[1]``? Has this been
  discussed before?
  
  Rationale: The footnote is the only explicit markup construct that
  directly translates to a visible body element. I've always been a
  little bit uncomfortable with the ``.. `` marker for footnotes
  because of this (we once said that ``.. `` implied "hidden"; it
  would be nice if that were uniformly true). And the leading
  underscore syntax (dropped because ``.. _[1]`` was verbose) is a
  useful reminder that it's a kind of hyperlink target. Time for
  another break from StructuredText?
  
  Example, current syntax::

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

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

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

- Differentiate author-date "citations" (``[GVR2002]``) from numbered
  footnotes? Create a new set of DTD elements: "citation" and
  "citation_reference"?
  
  Citations could be treated differently from footnotes. Footnotes
  could be rendered something like this::
  
      | 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. If
      | converted to endnotes (by a directive/transform),
      | a horizontal half-line might be used instead.
      | Page-oriented output formats would retain the
      | horizontal line.
  
  And citations would look like this::
  
      [GVR2001] Python Documentation; van Rossum, Drake, et al.;
       http://www.python.org/doc/

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

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

- Directive ideas: TOC (GNU-style two-way), endnotes *here*,
  citations *here*.
  
- 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.

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

- Add character processing? For example:

  - "--" -> em-dash (or "--" -> en-dash, and "---" -> em-dash)
  - convert quotes to curly quote entities
  - various forms of ":-)" to smily icons
  - others?
  
  How to represent entities in the text though? Unicode?

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



From tony@lsl.co.uk  Thu Feb 28 10:37:40 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 28 Feb 2002 10:37:40 -0000
Subject: [Doc-SIG] some ideas for reStructuredText & document model
In-Reply-To: <B8A32523.1F470%goodger@users.sourceforge.net>
Message-ID: <000101c1c043$f21838a0$545aa8c0@lslp862.int.lsl.co.uk>

David Goodger started to play with ideas after producing HTML output
(neat stuff, by the way, although see [1]_ at the bottom):
> - Change footnote syntax from ``.. [1]`` to ``_[1]``? Has this been
>   discussed before?

I've an idea it has, but can't remember details.

Hmm. Colour me ambivalent on this one - 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.

>   Example, current syntax::
>
>       .. [GVR2001] Python Documentation; van Rossum, Drake, et al.;
>          http://www.python.org/doc/
>
>   Proposed new syntax::
>
>       _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
>       http://www.python.org/doc/
>
>   Note that the body of the footnote need not be indented.

I'd suggest producing an example with mixed footnotes and reference
targets (sorry, forget the correct terminology) - I've certainly found
it useful to have a group of these together at the end of a section of
text, and the common left hand margin style makes that look visually
neater.

The ultimate test is surely how well the plain text reads when cast in
either manner - as I say, I suspect the footnote targets will still be
easier to find, in plaintext, with the ".." notation.

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

Presentation is an issue for the output phase, not the parser (and
*will* differ according to the abilities of the target format).

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

This is definitely a Writer issue - 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. In a [La]TeX
Writer, though, this would be more appropriate.

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

Again, this is a Writer issue. In HTML, for linkages that are singular
in both directions, having the back link can be very convenient. What to
do about linkages that are multiple in the reverse direction is, of
course, up to the person writing the Writer...

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

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

> - 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 (keep thinking of plain text, LaTeX and PDF as alternatives to
HTML!)

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

>   - 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(!).

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

Can we all say "ick"?

>   - others?

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

>   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. Also, bear in mind that over the next few years Unicode
support in filesystems is presumably going to start to happen (cf. the
PEP on the Python list for Unicode Python files!), so "someone else" may
lead us to this.

Tibs

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

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

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