docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] XEmacs tips wanted (and vim)

[Bruce A. <mx...@wa...>]

> I'm starting a very large writing project using reST and XEmacs and I'm 


I was actually looking for some vim syntax files for reST.   If no one
here knows of any existing, I'll make (and distribute) some of my own -
law of conservation of effort you know ;-)

Cheers,

-- 
Bruce Alderson <mx...@wa...>

[Docutils-users] XEmacs tips wanted

[Patrick K. O'B. <po...@or...>]

I'm starting a very large writing project using reST and XEmacs and I'm 
looking for any tips that will help me be more productive. Right now I'm 
using the default Text mode that ships with XEmacs 21.4 and it is not 
necessarily ideal for editing reST documents. I Googled a bit and didn't 
find much, so I thought I'd ask here. If I get good responses I'll write up 
an XEmacs Tips document and submit it back to the project.

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-users] Adding Math to reStructuredText

[David G. <go...@py...>]

Mukund Deshpande wrote:
> Thanks for a detailed response. Let met give some examples, I am mainly
> using math in two ways  (i) inline math and (ii) math displayed on its own.

I didn't realize that "itex" was a separate dialect of TeX.  I found a
description of itex at
<http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html>.  For math displayed
on its own I would suggest calling the directive "itex", and implementing it
like this::

    .. itex:: \alpha_t(i) = P(O_1, O_2, \dots O_t, q_t = S_i \lambda)

Since the directive knows its context, the \[ and \] delimiters wouldn't be
necessary.  They could be added on by the directive code before it calls the
itex2MML program, if required.

For inline math, an interpreted text role would be appropriate::

    Given the HMM model (`\lambda`:itex: = (A, B, `\pi`:itex:)) and a
    sequence of symbols `O = <O_1, O_2, \dots ,O_T>`:itex:, ...

Again, the delimting $'s should be left off.  If the default interpreted
text role was set to "itex", the ":itex:" role tags could be left off too.
Eventually there will be a directive and/or command-line option to set the
default role at runtime.

Note though that since Docutils can handle all the text encodings Python
can, you don't really need the "\lambda" and "\pi" markup.  You could simply
use UTF-8 and insert those characters directly.

> MathML is very verbose format so I don't think I will be directly typing
> mathml in any of my documents. I will stick with
> Tex math notation as it is widely used and easy to understand.

Compared to MathML and other math notations, itex does seem easy to
understand, but it's much less readable than the rest of the text and
markup.  But I suppose there's no way around it in this case.

> Let me see if I can implement the tex-math:: directive and tie
> it with itex2mml. I will keep you posted...

Please do, and let us know if you need any help.  The
doc...@li... mailing list would be the best place for it.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

Re: [Docutils-users] Adding Math to reStructuredText

[Mukund D. <muk...@ho...>]

Hi,

Thanks for a detailed response. Let met give some examples, I am mainly 
using math in two ways  (i) inline math and (ii) math displayed on its own.

The inline math is enclosed in '$' and here is an example of it,

Given the HMM model ($\lambda$ = (A, B, $\pi$)) and a    sequence of symbols 
$O = <O_1, O_2, \dots ,O_T>$, what is the probability that this sequence was 
generated by the model ?

If I want to write equations that won't fit on a line then I
go with the display math option for example,

\[\alpha_t(i) = P(O_1, O_2, \dots O_t, q_t = S_i \lambda)\]


Here the  math is enclosed in \[ and \]. Both these options are currently 
supported by itex2mml. So if you give itex2MML an html
document with these tags it will convert them to mathML.

About your suggestion I think I will use the tex-math:: directive for 
displaying equations that won't fit in a line, but using it for inline might 
be a bit cumbersome.

MathML is very verbose format so I don't think I will be directly typing 
mathml in any of my documents. I will stick with
Tex math notation as it is widely used and easy to understand.

Let me see if I can implement the tex-math:: directive and tie
it with itex2mml. I will keep you posted...

Thanks,

Mukund




>From: David Goodger <go...@py...>
>To: Mukund Deshpande 
><muk...@ho...>,<doc...@li...>
>Subject: Re: [Docutils-users] Adding Math to reStructuredText
>Date: Wed, 22 Jan 2003 16:10:47 -0500
>
>Mukund Deshpande wrote:
> > Is there any way I can add math symbols/equations in reStructured  text 
>?
> > I could not find any mention of math  in the reST specs.
>
>No direct math support exists yet (but see below).
>
> > I mainly interested in obtaining HTML (math via mathML) and this
> > what I tried. I typed math equations using the TeX markup, by enclosing 
>the
> > equations in '$' symbol. After that I used a tool called itex2mml that
> > converts anything between $ symbols to mathML.
>
>Please provide a self-contained sample, along with the commands necessary
>for the processing steps.
>
> > Unfortunately, that did not work because reST parser substituted all the 
>'\'
> > in the tex equations, is there way to tell the parser to not touch the 
>text
> > between two $ signs ?
>
>No direct way, no.  I can think of one indirect way and several direct ways
>to do what you want.
>
>The best, direct way would be to create a new directive.
>
>If you want TeX notation in your source text files, there could be a
>"tex-math" directive.  For TeX output, the TeX code would be passed through
>untouched.  For output formats supporting MathML, the TeX code would call
>itex2mml and insert the resulting MathML markup into the document.  For
>output formats that don't support MathML, perhaps a MathML-to-bitmap
>rendering tool could be used, and the resulting image inserted into the
>document.  For example::
>
>     .. tex-math::
>
>        (raw TeX math code here)
>
>If you want to use MathML directly, you could use the "raw" directive to
>pass the markup through to the HTML writer (and only the HTML writer), like
>this::
>
>     .. raw:: html
>
>        <math xmlns="..."> raw HTML/MathML here </math>
>
>You could use this approach right now.
>
>A new "mathml" directive would be even better.  It would be able to take
>care of the bookkeeping details details (like the <math> tags, namespaces,
>and output format compatibility issues)::
>
>     .. mathml::
>
>        (raw MathML here)
>
>Finally, there's a quick & dirty indirect way to use TeX code, without any
>programming.  Use the "raw" directive with the TeX code between "$", and
>preprocess the file with itex2mml.  (I assume itex2mml removes the "$"
>characters?  If not, this won't work without another step to remove them.)
>::
>
>     .. raw:: html
>
>        $(raw TeX math code here)$
>
>There may be other associated issues, like declaring a MathML namespace
>and/or a DTD declaration.  Please provide samples.
>
>-- David Goodger    http://starship.python.net/~goodger
>
>Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv


_________________________________________________________________
Add photos to your e-mail with MSN 8. Get 2 months FREE*.  
http://join.msn.com/?page=features/featuredemail

Re: [Docutils-users] Adding Math to reStructuredText

[David G. <go...@py...>]

Mukund Deshpande wrote:
> Is there any way I can add math symbols/equations in reStructured  text ?
> I could not find any mention of math  in the reST specs.

No direct math support exists yet (but see below).

> I mainly interested in obtaining HTML (math via mathML) and this
> what I tried. I typed math equations using the TeX markup, by enclosing the
> equations in '$' symbol. After that I used a tool called itex2mml that
> converts anything between $ symbols to mathML.

Please provide a self-contained sample, along with the commands necessary
for the processing steps.

> Unfortunately, that did not work because reST parser substituted all the '\'
> in the tex equations, is there way to tell the parser to not touch the text
> between two $ signs ?

No direct way, no.  I can think of one indirect way and several direct ways
to do what you want.

The best, direct way would be to create a new directive.

If you want TeX notation in your source text files, there could be a
"tex-math" directive.  For TeX output, the TeX code would be passed through
untouched.  For output formats supporting MathML, the TeX code would call
itex2mml and insert the resulting MathML markup into the document.  For
output formats that don't support MathML, perhaps a MathML-to-bitmap
rendering tool could be used, and the resulting image inserted into the
document.  For example::

    .. tex-math::

       (raw TeX math code here)

If you want to use MathML directly, you could use the "raw" directive to
pass the markup through to the HTML writer (and only the HTML writer), like
this::

    .. raw:: html

       <math xmlns="..."> raw HTML/MathML here </math>

You could use this approach right now.

A new "mathml" directive would be even better.  It would be able to take
care of the bookkeeping details details (like the <math> tags, namespaces,
and output format compatibility issues)::

    .. mathml::

       (raw MathML here)

Finally, there's a quick & dirty indirect way to use TeX code, without any
programming.  Use the "raw" directive with the TeX code between "$", and
preprocess the file with itex2mml.  (I assume itex2mml removes the "$"
characters?  If not, this won't work without another step to remove them.)
::

    .. raw:: html

       $(raw TeX math code here)$

There may be other associated issues, like declaring a MathML namespace
and/or a DTD declaration.  Please provide samples.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

[Docutils-users] Adding Math to reStructuredText

[Mukund D. <muk...@ho...>]

Hi,

Is there any way I can add math symbols/equations in reStructured  text ? I 
could not find any mention of math  in the reST specs.

I mainly interested in obtaining HTML (math via mathML) and this
what I tried. I typed math equations using the TeX markup, by enclosing the 
equations in '$' symbol. After that I used a tool called itex2mml that 
converts anything between $ symbols to mathML. Unfortunately, that did not 
work because reST parser substituted all the '\' in the tex equations, is 
there way to
tell the parser to not touch the text between two $ signs ?

Thanks,

Mukund




_________________________________________________________________
STOP MORE SPAM with the new MSN 8 and get 2 months FREE*  
http://join.msn.com/?page=features/junkmail

Re: [Docutils-users] Re: Editors wars, again

[Beni C. <cb...@te...>]

On 2003-01-21, Michael Hudson wrote:

> Is anyone working on a rest emacs mode?  text-mode is pretty close, but
> things to keep titles in sync and help with tables would be nice, not to
> mention jumping between links and references...
>
One of these is already solved: for "full" tables, there is an excellent
``table.el`` floating somewhere that can edit contents of a cell by
creating a temporay buffer), resize cells, etc.  Actually the the spec for
full tables refers to it as a justification of the syntax...

-- 
Beni Cherniavsky <cb...@tx...>

Re: [Docutils-users] Subtitle issue

[Patrick K. O'B. <po...@or...>]

On Tuesday 21 January 2003 12:59 pm, David Goodger wrote:
>
> Done: <http://docutils.sf.net/FAQ.html>, section 2.5.
>
> Done: <http://docutils.sf.net/docs/rst/quickstart.html#sections>.

That's much better.

> I have also modified the markup spec:
> <http://docutils.sf.net/spec/rst/reStructuredText#sections>.

Typo in url fixed below:

<http://docutils.sf.net/spec/rst/reStructuredText.html#sections>

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-users] Subtitle issue

[David G. <go...@py...>]

Patrick K. O'Brien wrote:
> Okay, I understand now. Two things might help others in the future. First,
> this entry in FAQ.txt could be a bit more explicit about this requirement:

Done: <http://docutils.sf.net/FAQ.html>, section 2.5.

> Second, even having read all the docs several times (but not all the specs)
> I wasn't aware that adding an overline changed how the section title was
> interpreted. If anything, I had the impression it was a completely optional
> adornment with no semantic significance. Is that not correct? If not, I
> suggest making that clear in this section of quickstart.txt, especially the
> last sentence:

Done: <http://docutils.sf.net/docs/rst/quickstart.html#sections>.

I have also modified the markup spec:
<http://docutils.sf.net/spec/rst/reStructuredText#sections>.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

[Docutils-users] Re: Editors wars, again

[Michael H. <mw...@py...>]

Aahz <aa...@py...> writes:

> Why did you switch to emacs?

Becuase he saw the light :)
                         /\
                         ||
                ,--------'`---------.
                | NOTE THIS, PLEASE |
                `-------------------'

Is anyone working on a rest emacs mode?  text-mode is pretty close,
but things to keep titles in sync and help with tables would be nice,
not to mention jumping between links and references...

Cheers,
M.

-- 
    FORD:  Just pust the fish in your ear, come on, it's only a
           little one.
  ARTHUR:  Uuuuuuuuggh!
                    -- The Hitch-Hikers Guide to the Galaxy, Episode 1

Re: [Docutils-users] Editors wars, again

[Patrick K. O'B. <po...@or...>]

On Tuesday 21 January 2003 11:18 am, Aahz wrote:
> Why did you switch to emacs?  (I loathe emacs, and can't imagine anyone
> familiar with vi switching.)

Resistance was futile. ;-)

With all the writing I'm doing--both code and text--I decided to give in and 
live in an editor that did everything. Simple as that. I gave Vim a try and 
it just never clicked for me. Emacs doesn't exactly click either, but I've 
run out of options.

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

[Docutils-users] Editors wars, again

[Aahz <aa...@py...>]

On Tue, Jan 21, 2003, Patrick K. O'Brien wrote:
>
> Right now it is just something I'm playing with as I figure out how to use 
> ReST. If it turns into something decent I will try to get it published. At 
> this point I've actually got more demand for articles than time to write 
> them. I'm hoping ReST and Emacs increase my productivity. (I just switched 
> to Emacs from Vim and the transition is a bit painful, even though I never 
> got very comfortable with Vim either. I swear this is the last time I 
> change text editors!)

Why did you switch to emacs?  (I loathe emacs, and can't imagine anyone
familiar with vi switching.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"I used to have a .sig but I found it impossible to please everyone..."  --SFJ

Re: [Docutils-users] Subtitle issue

[Patrick K. O'B. <po...@or...>]

On Tuesday 21 January 2003 08:53 am, David Goodger wrote:
> BTW, the first two sections, "Introduction" and "reStructuredText", are
> an excellent introduction to the markup.  It's good to see a fresh
> approach -- I'm too close to the project to write objectively.  

Thanks, glad you liked it.

> I take it
> that this is the article you mentioned last month.  Is it intended for
> publication somewhere?  Either way, can we use it in the Docutils project
> once you're done?  It would make a great "techie summary" if not an
> "executive summary".

Right now it is just something I'm playing with as I figure out how to use 
ReST. If it turns into something decent I will try to get it published. At 
this point I've actually got more demand for articles than time to write 
them. I'm hoping ReST and Emacs increase my productivity. (I just switched 
to Emacs from Vim and the transition is a bit painful, even though I never 
got very comfortable with Vim either. I swear this is the last time I 
change text editors!)

I'll definitely figure out a way to make the content available for you to 
include in the Docutils project.

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-users] Subtitle issue

[Patrick K. O'B. <po...@or...>]

On Tuesday 21 January 2003 08:53 am, David Goodger wrote:
> One nit: it's spelled "Docutils", not "DocUtils" (no StudlyCaps).

Doh! I'm usually pretty good about these things, and I was fully aware that 
the proper spelling was mentioned in the FAQ, and, yet, I still messed it 
up. Ugh! :-(

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-users] Subtitle issue

[Patrick K. O'B. <po...@or...>]

On Tuesday 21 January 2003 08:53 am, David Goodger wrote:
> I tried the full file just now, and I see the problem.  It's very simple.
> The table of contents gives a clue (note the nesting):
>
>     * Using Python As An Authoring Tool
>
>       * Introduction
>       * reStructuredText
>
>     * Creating a custom writer for dW tutorials
>
> Here's the document subtitle::
>
>     Using Python As An Authoring Tool
>     ---------------------------------
>
> And here's the last section title::
>
>     Creating a custom writer for dW tutorials
>     -----------------------------------------
>
> They both use the same title adornment style -- dash underlines. 
> Therefore the parser places them at the same section level, as evidenced
> by the TOC above.  The solution is to use a different -- and unique --
> adornment style for the document subtitle.  You could add a dash
> overline::
>
>     -----------------------------------
>      Using Python As An Authoring Tool
>     -----------------------------------

Okay, I understand now. Two things might help others in the future. First, 
this entry in FAQ.txt could be a bit more explicit about this requirement:

<quote>
How can I indicate the document title?  Subtitle?
-------------------------------------------------

If there's only one highest-level section title at the beginning of a
document, it is treated specially, as the document title.  Similarly,
a lone second-highest-level section title may become the document
subtitle if it immediately follows the document title.

For example::

    This is the Document Title
    ==========================

    This is the Document Subtitle
    -----------------------------

    Here's an ordinary paragraph.

Counterexample::

    Here's an ordinary paragraph.

    This is *not* a Document Title
    ==============================

    The "ordinary paragraph" above the section title
    prevents it from becoming the document title.
</quote>

Second, even having read all the docs several times (but not all the specs) 
I wasn't aware that adding an overline changed how the section title was 
interpreted. If anything, I had the impression it was a completely optional 
adornment with no semantic significance. Is that not correct? If not, I 
suggest making that clear in this section of quickstart.txt, especially the 
last sentence:

<quote>
To break longer text up into sections, you use **section headers**.
These are a single line of text (one or more words) with an underline
(and optionally an overline) in dashes "``-----``", equals
"``======``", tildes "``~~~~~~``" or any of the non-alphanumeric
characters ``= - ` : ' " ~ ^ _ * + # < >`` that you feel comfortable
with.  The underline/overline must be at least as long as the title
text.  Be consistent though, since all sections marked with the same
underline style are deemed to be at the same level::
</quote>

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-users] Subtitle issue

[David G. <go...@py...>]

Patrick K. O'Brien wrote:
>>> I noticed that including a subtitle changes how the TOC is determined
>>> using the html writer.
...
> It turned out that the sample did work fine, so I sent David the full file.

I tried the full file just now, and I see the problem.  It's very simple.
The table of contents gives a clue (note the nesting):

    * Using Python As An Authoring Tool

      * Introduction
      * reStructuredText

    * Creating a custom writer for dW tutorials

Here's the document subtitle::

    Using Python As An Authoring Tool
    ---------------------------------

And here's the last section title::

    Creating a custom writer for dW tutorials
    -----------------------------------------

They both use the same title adornment style -- dash underlines.  Therefore
the parser places them at the same section level, as evidenced by the TOC
above.  The solution is to use a different -- and unique -- adornment style
for the document subtitle.  You could add a dash overline::

    -----------------------------------
     Using Python As An Authoring Tool
    -----------------------------------

One nit: it's spelled "Docutils", not "DocUtils" (no StudlyCaps).

BTW, the first two sections, "Introduction" and "reStructuredText", are an
excellent introduction to the markup.  It's good to see a fresh approach --
I'm too close to the project to write objectively.  I take it that this is
the article you mentioned last month.  Is it intended for publication
somewhere?  Either way, can we use it in the Docutils project once you're
done?  It would make a great "techie summary" if not an "executive summary".

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

[Docutils-users] reStructuredText on external files

[Pierre-Yves D. <py....@li...>]

Bonjour,

what is the shortest way to duisplay a Zrest document template stored in =
an
'External file' ?

Thank you


___________________________________________________
P-Y Delens

Resp. "Technologies de l'Information et de la Communication"
pour la FAB - F=E9d=E9ration des Architectes de Belgique
pour la SAF - Soci=E9t=E9 des Architectes Francophones
www.saf-arch.be
mail : web...@sa...

c/o LIENTERFACES -  PY Delens, sprl

Avenue Dolez, 243  -  1180   Bruxelles
phone : 32 2 375 55 62
fax :      32 2 374 75 74
mail :   py....@li...
web : www.lienterfaces.be
___________________________________________________

Re: [Docutils-users] Subtitle issue

[Patrick K. O'B. <po...@or...>]

On Monday 20 January 2003 06:34 pm, David Goodger wrote:
> Patrick K. O'Brien wrote:
> > I noticed that including a subtitle changes how the TOC is determined
> > using the html writer.
>
> ...
>
> > When "Using Python As An Authoring Tool" is tagged as a subtitle it
> > appears in the TOC. That seems like a mistake to me. Just thought I'd
> > mention it.
>
> I don't get those results.  In both cases, I get the exact same table of
> contents, as follows (pseudo-XML)::
>
>     <topic class="contents" id="contents" name="contents">
>         <title>
>             Contents
>         <bullet_list>
>             <list_item>
>                 <paragraph>
>                     <reference id="id1" refid="introduction">
>                         Introduction
>
> This was actually taken from the first test data, *with* a subtitle.  I
> checked html.py also -- no anomalies.

It turned out that the sample did work fine, so I sent David the full file. 
Just for the record, here is what happens with the full file:

        <topic class="contents" id="contents" name="contents">
            <title>
                Contents
            <bullet_list>
                <list_item>
                    <paragraph>
                        <reference id="id1" 
refid="using-python-as-an-authoring-tool">
                            Using Python As An Authoring Tool
                    <bullet_list>
                        <list_item>
                            <paragraph>
                                <reference id="id2" refid="introduction">
                                    Introduction

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-users] Subtitle issue

[David G. <go...@py...>]

Patrick K. O'Brien wrote:
> I noticed that including a subtitle changes how the TOC is determined using
> the html writer.
...
> When "Using Python As An Authoring Tool" is tagged as a subtitle it appears
> in the TOC. That seems like a mistake to me. Just thought I'd mention it.

I don't get those results.  In both cases, I get the exact same table of
contents, as follows (pseudo-XML)::

    <topic class="contents" id="contents" name="contents">
        <title>
            Contents
        <bullet_list>
            <list_item>
                <paragraph>
                    <reference id="id1" refid="introduction">
                        Introduction

This was actually taken from the first test data, *with* a subtitle.  I
checked html.py also -- no anomalies.

Please supply the usual: Python, Docutils, & OS versions, and the exact
command-line you used.  Check for multiple installed versions.  Do you have
any modified code?  Try a clean install of the latest CVS snapshot.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

[Docutils-users] Subtitle issue

[Patrick K. O'B. <po...@or...>]

I noticed that including a subtitle changes how the TOC is determined using 
the html writer. For example, run this content through html.py (the <quote> 
tags are for this email only and don't appear in the text file):

<quote>
=================
 Structured Text
=================

Using Python As An Authoring Tool
---------------------------------

:Author: Patrick K. O'Brien
:Contact: po...@or...
:Date: $Date$
:Web site: http://www.orbtech.com/web/pobrien/

.. contents::


Introduction
============

Imagine, if you will, the following situation. You are a writer. You
are a technical writer, actually, who writes books, articles and
tutorials about your favorite programming language. To satisfy the
needs of your publishers, you must deliver your writing in a variety
of formats, such as plaintext, HTML, and XML. And while most other
writers use a tool like Microsoft Word, that's just not your style.
</quote>

Then run the following content:

<quote>
=================
 Structured Text
=================

Using Python As An Authoring Tool

:Author: Patrick K. O'Brien
:Contact: po...@or...
:Date: $Date$
:Web site: http://www.orbtech.com/web/pobrien/

.. contents::


Introduction
============

Imagine, if you will, the following situation. You are a writer. You
are a technical writer, actually, who writes books, articles and
tutorials about your favorite programming language. To satisfy the
needs of your publishers, you must deliver your writing in a variety
of formats, such as plaintext, HTML, and XML. And while most other
writers use a tool like Microsoft Word, that's just not your style.
</quote>

When "Using Python As An Authoring Tool" is tagged as a subtitle it appears 
in the TOC. That seems like a mistake to me. Just thought I'd mention it.

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-develop] Re: [Docutils-users] Programming reference documentation

[Ian B. <ia...@co...>]

On Sun, 2003-01-19 at 06:00, Beni Cherniavsky wrote:
> Forgot to announce it; since the source reader is not ready for use (is
> it?),

It seems to work okay for me -- I think David might have some features
he'd like, but what's there seems sufficient to me.

>  I think somebody might benefit from my solution.  I've written code
> that was documented with rST docstrings but couldn't use them (pydoc
> ignores the rST, docutils barfs at the python code).  So I took the
> plain-text formatter of pydoc and hacked it until the result was a
> document with chapters instead of the "| " nesting, etc., so that it could
> be processed by the plain rST reader of docutils.

Ack... sounds like a mess.

> > Ian Bicking wrote:
> > > One thing I *don't* like is reference documentation in the style of
> > > pydoc.To me it's too automatic, and generally too hard to follow.
> > > I find reference documentation with some framework of text (lead-in
> > > paragraphs, categorization, etc) to be much better.
> >
> Like GNU info files tend to be?  libc, elisp, make, they have the best
> hierarchically organised documentation that I've ever read.  Puts
> everything in the right place in your head after first reading but also
> allows you to quickly read just what you need.
> 
> I'm now writing a library that I'd like to document very well, and info
> files are my standard of excellence ;-).  So I want to figure out a way
> for creating such documentation with docutils, too.

Documenting a library is different then a program, in my mind.  Or at
least there should be some entirely thorough but not necessarily
intuitively structured documentation.  In Webware I'm also making
documents that are task and instruction oriented.  But they don't make
up for the reference documentation that you want when you're already
familiar with the library, or at least the concept behind the library,
and you just want to know how to spell the method name or something.

This is how I use the Python reference documentation -- which on the
whole is quite good -- and is how I'd expect to use a docstring
extractor.  I just write the other documents in a separate file.

> Now that I think of it, is anyone else interested in a GNU info writer
> for docutils?  If yes, I'll append it to my task queue (i.e. don't hold
> your breath).

Info documents are often well organized, but the actual reader I've
never been impressed with.  I get lost too easily.  But web pages
certainly aren't ideal either.

> >
> >   """
> >   A general description of the highlights of the module, with
> >   references (interpreted text) to the details.  We don't need
> >   a "Module" title because it will be derived automatically.
> >
> >   This module does X, Y, Z.  Most work will be done through the
> >   `MainClass` class.
> >
> >   In certain cases you may wish to access the functionality
> >   separately, yada yada yada, and may wish to use `some_function`
> >   or `some_other_function`
> >   """
> >
> >   class MainClass:
> >       """
> >       Description of this class, with references to specific
> >       methods like `some_method`.  We don't need to fully qualify
> >       (no "MainClass." prefix) because "some_method" is in the
> >       local namespace.
> >       """
> >
> This are closest to what I was doing.  The module & class docstrings will
> contain overview information, perhaphs even in many chapters, that would
> link to relevant places in the low-level per-method documentation.
> 
> The problem with this approach is that it relies too much on hyperlinks
> for a good order of reading.  The great thing about GNU info files is that
> they are also organised in an order that is almost optimal for one-pass
> front-to-back reading.  Ian Bicking's idea is better because it allows you
> to specify the order of the documentation entries differently from the
> order of the code.

I'm realizing that reordering the methods might be best anyway --
usually they don't match up with the description because they were just
written in a certain order.

The whole hyperlinking thing I'm still unsure about.  I don't even know
if there's a way to indicate that `references` should be turned into
some sort of link.

> >       ##
> >       # My idea from JavaDoc is to allow document comments
> >       # interspersed in the code in some way, which will
> >       # interleave with the code objects and docstrings.
> >       # These would include section titles, allowing a
> >       # subdivision of methods by category.  For example:
> >
> >       ##
> >       # Magic Methods
> >       # =============
> >
> >       def __str__(self):
> >           """String representation of this object (pseudo-XML)."""
> >           ...
> >
> I think I see your idea.  But in many some cases this is short of what's
> needed.  Consider (invented example) an application where many classes
> contain special `gui_repr` methods that defines the user interface for
> this object.  They are completely irrelevant to the algorithms described
> in other methods, so a good manual will probably separate the
> documentation of all GUI methods into a separate chapter discussing them
> all at once.

When you start getting into that level or organization you have to have
an application-wide view for the document.  I'm just thinking of modules
now -- but there certainly are many modules that aren't well contained.

> So I think there should be (optional) ways to specify reordering /
> reorganisation of nodes.  I'm not sure how to do it in a convenient yet
> flexible way.  In the above gui case, for example, I would want to grab
> all these methods without listing each one and risking omission.
> Probably Python scripting to generate the reorganisation info would do the
> trick but would not be equally applicable to non-python-source uses of
> rST.

I know... I've already thought of several packages I have that I'd like
to autogenerate the documentation, but the format needs to be structured
different from how it generally would be.  For instance, in one library
I have error strings that can be overridden -- these could be extracted,
but only by a program that understood how my specific code was
structured.

> Also, for big documentation, it would make sense to hold the user-only
> parts in separate files, leaving only what's relevant to the source's
> design in the source.  The current include directive might solve this task
> too, if the reorganisation is applied later.

I'm not sure what you mean here...?   

-- 
Ian Bicking           Colorstudy Web Development
ia...@co...   http://www.colorstudy.com
PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7
4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241

Re: [Docutils-users] Programming reference documentation

[Beni C. <cb...@te...>]

On 2003-01-18, David Goodger wrote:

> I have begun work on a Python Source Reader component which will
> accomplish this.
>
Forgot to announce it; since the source reader is not ready for use (is
it?), I think somebody might benefit from my solution.  I've written code
that was documented with rST docstrings but couldn't use them (pydoc
ignores the rST, docutils barfs at the python code).  So I took the
plain-text formatter of pydoc and hacked it until the result was a
document with chapters instead of the "| " nesting, etc., so that it could
be processed by the plain rST reader of docutils.

It wasn't ideal, most notably interpretted text was just ignored instead
of becoming references (that could be quick-fixed, I think, for 80%
percent of the cases). In fact only references in the class hierarchy
(converted to a nested list) were explicitly turned into links and classes
were prepended with link targets.  There were lots of empty lines and the
text looked much less readable than the original pydoc's output.  After
processing with docutils this was hidden but the result didn't look much
better (if at all) than pydoc's html.  The most important benefit was that
I was able to validate my docstrings with docutils for being correct rST
(actually sometimes it was wrong because of the dumb conversion and I had
to change my docs to work around).

If somebody wants my code, I'll upload it later today.  Please don't read
it ;-), it was very quick and dirty - I just mutated the text formatter
instead of copying as a new formatter, I changed it only until it worked
on my docstrings so it could break on yours, etc.

> Ian Bicking wrote:
> > One thing I *don't* like is reference documentation in the style of
> > pydoc.To me it's too automatic, and generally too hard to follow.
> > I find reference documentation with some framework of text (lead-in
> > paragraphs, categorization, etc) to be much better.
>
Like GNU info files tend to be?  libc, elisp, make, they have the best
hierarchically organised documentation that I've ever read.  Puts
everything in the right place in your head after first reading but also
allows you to quickly read just what you need.

I'm now writing a library that I'd like to document very well, and info
files are my standard of excellence ;-).  So I want to figure out a way
for creating such documentation with docutils, too.

Now that I think of it, is anyone else interested in a GNU info writer
for docutils?  If yes, I'll append it to my task queue (i.e. don't hold
your breath).

> That can be tricky.One idea I had (documented in the spec/notes
> file) is to recognize JavaDoc-style documentation comments almost
> anywhere in the code.This would allow a more "literate programming"
> approach than what pydoc provides.
>
I'm not sure comments/strings in the code have anything to do with this.
It's about writing extra overview/design documentation tat doesn't
necessarily follow the code structure (and would be of higher quality if
the programmer is not tempted to bind them together for saving a few lines
of typing).

> > My vision for a docstring-based reference documentation would
> > probably look like:
> >
> > """
> > Module
> > ======
> >
> > This module does X, Y, Z.Most work will be done through the class:
> >
> > .. docstring:: MainClass
> >
> > In certain cases you may wish to access the functionality
> > separately, yada yada yada, and may wish to use:
> >
> > .. docstring:: some_function
> > .. docstring:: some_other_function
> > """
> >
> > class MainClass:
> >   """
> >   Recursively we continue, now with methods:
> >
> >   .. docstring:: MainClass.some_method
> >   """
>
Hmm, consider Leo outlines - I've never used it but it seems to be able to
do this kind of thing...

> Ienvision something more along the lines of this::
>
>   """
>   A general description of the highlights of the module, with
>   references (interpreted text) to the details.  We don't need
>   a "Module" title because it will be derived automatically.
>
>   This module does X, Y, Z.  Most work will be done through the
>   `MainClass` class.
>
>   In certain cases you may wish to access the functionality
>   separately, yada yada yada, and may wish to use `some_function`
>   or `some_other_function`
>   """
>
>   class MainClass:
>       """
>       Description of this class, with references to specific
>       methods like `some_method`.  We don't need to fully qualify
>       (no "MainClass." prefix) because "some_method" is in the
>       local namespace.
>       """
>
This are closest to what I was doing.  The module & class docstrings will
contain overview information, perhaphs even in many chapters, that would
link to relevant places in the low-level per-method documentation.

The problem with this approach is that it relies too much on hyperlinks
for a good order of reading.  The great thing about GNU info files is that
they are also organised in an order that is almost optimal for one-pass
front-to-back reading.  Ian Bicking's idea is better because it allows you
to specify the order of the documentation entries differently from the
order of the code.

>       ##
>       # My idea from JavaDoc is to allow document comments
>       # interspersed in the code in some way, which will
>       # interleave with the code objects and docstrings.
>       # These would include section titles, allowing a
>       # subdivision of methods by category.  For example:
>
>       ##
>       # Magic Methods
>       # =============
>
>       def __str__(self):
>           """String representation of this object (pseudo-XML)."""
>           ...
>
I think I see your idea.  But in many some cases this is short of what's
needed.  Consider (invented example) an application where many classes
contain special `gui_repr` methods that defines the user interface for
this object.  They are completely irrelevant to the algorithms described
in other methods, so a good manual will probably separate the
documentation of all GUI methods into a separate chapter discussing them
all at once.

So I think there should be (optional) ways to specify reordering /
reorganisation of nodes.  I'm not sure how to do it in a convenient yet
flexible way.  In the above gui case, for example, I would want to grab
all these methods without listing each one and risking omission.
Probably Python scripting to generate the reorganisation info would do the
trick but would not be equally applicable to non-python-source uses of
rST.

Also, for big documentation, it would make sense to hold the user-only
parts in separate files, leaving only what's relevant to the source's
design in the source.  The current include directive might solve this task
too, if the reorganisation is applied later.

See `(standards) GNU Manuals`__ for more thougths in this direction and
`(findutils) Top`__ for an example of a good manual that doesn't follow
the code and even describes several different programs together.

__ http://www.delorie.com/gnu/docs/GNU/standards_28.html
__ http://www.delorie.com/gnu/docs/findutils/find_toc.html

-- 
Beni Cherniavsky <cb...@tx...>

There is an Excel spreadsheet here.  Do you want to open it? y
There was a grid bug in the spreadsheet.  The grid bug bites.

Re: [Docutils-users] Programming reference documentation

[Ian B. <ia...@co...>]

On Sat, 2003-01-18 at 10:34, David Goodger wrote:
> > I'm working with the Webware project (webware.sf.net), and we really
> > need some cohesive reference documentation, aimed particularly at
> > the public interfaces.  I'm wondering if anyone is using docutils
> > for this now... if so, I'd like to see how it's working.  It's not
> > entirely clear to me what docutils status is (I've used reST a lot,
> > but not much else).
> 
> Are you referring to "auto-documentation" (extracting documentation
> from source code)?  I have begun work on a Python Source Reader
> component which will accomplish this.  The code so far is in
> docutils/readers/python/moduleparser.py.  The plan is described in PEP
> 258 (<http://docutils.sf.net/spec/pep-0258.html>),
> <http://docutils.sf.net/spec/pysource.html>, and
> <http://docutils.sf.net/spec/notes.html#python-source-reader>.

Yes, I'm thinking of auto-documentation, or at least documentation with
an automated step.

> The Python Reader package doesn't extract docstrings yet.  I'm
> currently concentrating on finding a new job [#]_, which means I don't
> know how much time I'll be able to devote to this.
> 
> .. [#] Check out my resume at
>    <http://starship.python.net/~dgoodger/cv/>!  Please tell your
>    friends, relatives, neighbors, managers, and HR people!  Let me
>    know if you have any leads.  Thanks!

You're in Canada, right?  My scant connections don't go as far as
Canada, but who knows...

> > * Using internal references in those docstrings, so I could
> >   effectively include the docstrings from other portions of code
> >   (classes, methods, etc).
> 
> I hadn't thought of that approach.  From your description, it seems to
> require a lot of bookkeeping and redundancy, which I wouldn't want to
> write or require others to write.  But I encourage you to explore it.

It's about the same amount of bookkeeping that you'd need to create a
high-quality reference document (like the Python module documentation,
for instance).  It should be about as difficult to write.  The advantage
would be entirely in the maintenance, by having code and documentation
next to each other.

Some of the bookkeeping might be possible to ease -- for instance,
keeping track of methods that aren't included and giving a warning (so
you don't forget to include documentation you wrote).  Or maybe have a
directive that would just include all the documentation of the class or
module -- either ordered like in the source, or ordered alphabetically. 

> > One thing I *don't* like is reference documentation in the style of
> > pydoc.  To me it's too automatic, and generally too hard to follow.
> 
> I hope that Docutils' auto-documentation will be more flexible than
> pydoc's, although it will have the same basis.  It will certainly have
> more flexible rendering, and I hope much more readable.
> 
> > I find reference documentation with some framework of text (lead-in
> > paragraphs, categorization, etc) to be much better.
> 
> That can be tricky.  One idea I had (documented in the spec/notes
> file) is to recognize JavaDoc-style documentation comments almost
> anywhere in the code.  This would allow a more "literate programming"
> approach than what pydoc provides.

If everything is ordered like in the source, perhaps a comment (or plain
string) could be parsed out as in-between text.  Like:

"""
These functions are all dangerous:
"""

def yadayada():
    "docs for this"

And so on... they could appear in class definitions as well.  That they
are strings implies they are different than mere comments -- most of the
comments I write are intended to be read by someone reading the code,
and I have no desire to separate them into documentation; I'd be willing
to make that distinction strict in the code I work with.

But that's harder to work with than inclusion, because your narrative is
split up all over the place with lots of code in between.  

> > There are also
> > methods which, while "public" aren't actually useful, and I don't
> > think those should be documented -- they are just distracting.
> 
> How could software tell the difference?  If we can come up with an
> unobtrusive way to tell the docstring processing system to disregard
> certain methods, it could be useful.  Maybe a class attribute
> equivalent of the "__all__" module attribute?  Or perhaps the
> opposite: a "__none__" class attribute ;).

Well, there could be a directive in the docstring like:

  .. public: no

Or I guess it would be more appropriate:

  :Public: no

"Public" probably isn't the right term, but something like that. 
":Obscure: yes" might be more correct ;)

-- 
Ian Bicking           Colorstudy Web Development
ia...@co...   http://www.colorstudy.com
PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7
4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241

[Docutils-users] my resume URL

[David G. <go...@py...>]

Sorry, mistyped the URL.  It should be
<http://starship.python.net/~goodger/cv/>.  Thanks again!

-- David Goodger    http://starship.python.net/~goodger

Re: [Docutils-users] Programming reference documentation

[David G. <go...@py...>]

I'm copying this to docutils-develop, a more appropriate venue for the
discussion IMO.  Subscribe at
<http://lists.sf.net/lists/listinfo/docutils-develop>.

Ian Bicking wrote (quoted in full):
> I'm working with the Webware project (webware.sf.net), and we really
> need some cohesive reference documentation, aimed particularly at
> the public interfaces.  I'm wondering if anyone is using docutils
> for this now... if so, I'd like to see how it's working.  It's not
> entirely clear to me what docutils status is (I've used reST a lot,
> but not much else).

Are you referring to "auto-documentation" (extracting documentation
from source code)?  I have begun work on a Python Source Reader
component which will accomplish this.  The code so far is in
docutils/readers/python/moduleparser.py.  The plan is described in PEP
258 (<http://docutils.sf.net/spec/pep-0258.html>),
<http://docutils.sf.net/spec/pysource.html>, and
<http://docutils.sf.net/spec/notes.html#python-source-reader>.

> Some options I've considered, in order of complexity:
> * Writing the whole thing in reST, separate from the code itself.
>   The writing wouldn't be so bad, but the maintenance would be more
>   difficult.

This can be done now of course.

> * Splitting it up into modules, and putting the entire reference
>   documentation in the module docstring.

The Python Reader package doesn't extract docstrings yet.  I'm
currently concentrating on finding a new job [#]_, which means I don't
know how much time I'll be able to devote to this.

.. [#] Check out my resume at
   <http://starship.python.net/~dgoodger/cv/>!  Please tell your
   friends, relatives, neighbors, managers, and HR people!  Let me
   know if you have any leads.  Thanks!

> * Using internal references in those docstrings, so I could
>   effectively include the docstrings from other portions of code
>   (classes, methods, etc).

I hadn't thought of that approach.  From your description, it seems to
require a lot of bookkeeping and redundancy, which I wouldn't want to
write or require others to write.  But I encourage you to explore it.

> One thing I *don't* like is reference documentation in the style of
> pydoc.  To me it's too automatic, and generally too hard to follow.

I hope that Docutils' auto-documentation will be more flexible than
pydoc's, although it will have the same basis.  It will certainly have
more flexible rendering, and I hope much more readable.

> I find reference documentation with some framework of text (lead-in
> paragraphs, categorization, etc) to be much better.

That can be tricky.  One idea I had (documented in the spec/notes
file) is to recognize JavaDoc-style documentation comments almost
anywhere in the code.  This would allow a more "literate programming"
approach than what pydoc provides.

> There are also
> methods which, while "public" aren't actually useful, and I don't
> think those should be documented -- they are just distracting.

How could software tell the difference?  If we can come up with an
unobtrusive way to tell the docstring processing system to disregard
certain methods, it could be useful.  Maybe a class attribute
equivalent of the "__all__" module attribute?  Or perhaps the
opposite: a "__none__" class attribute ;).

> So the last option is the one I like the most.  But I doubt it's in
> place.

Correct, it's not.

> I've already decided I'm not going to get the reference
> documentation done for the next release (there's other documentation
> that needs to be written, and documentation is tiring :), so I don't
> plan to use this in the short term and I could put some work into
> producing a system I like.

Glad for the help!

> My vision for a docstring-based reference documentation would
> probably look like:
> 
> """
> Module
> ======
> 
> This module does X, Y, Z.  Most work will be done through the class:
> 
> .. docstring:: MainClass
> 
> In certain cases you may wish to access the functionality
> separately, yada yada yada, and may wish to use:
> 
> .. docstring:: some_function
> .. docstring:: some_other_function
> """
> 
> class MainClass:
>     """
>     Recursively we continue, now with methods:
> 
>     .. docstring:: MainClass.some_method
>     """

I envision something more along the lines of this::

    """
    A general description of the highlights of the module, with
    references (interpreted text) to the details.  We don't need
    a "Module" title because it will be derived automatically.
    
    This module does X, Y, Z.  Most work will be done through the
    `MainClass` class.
    
    In certain cases you may wish to access the functionality
    separately, yada yada yada, and may wish to use `some_function`
    or `some_other_function`
    """
    
    class MainClass:
        """
        Description of this class, with references to specific
        methods like `some_method`.  We don't need to fully qualify
        (no "MainClass." prefix) because "some_method" is in the
        local namespace.
        """

        ##
        # My idea from JavaDoc is to allow document comments
        # interspersed in the code in some way, which will
        # interleave with the code objects and docstrings.
        # These would include section titles, allowing a
        # subdivision of methods by category.  For example:
        
        ##
        # Magic Methods
        # =============
        
        def __str__(self):
            """String representation of this object (pseudo-XML)."""
            ...

> How far away might this be?

A function of my spare time and volunteer contributions.  Hint hint.

> Are there better alternatives already in place, or planned on?

Alternative software packages?  There's HappyDoc, EpyDoc, effbot's
PythonDoc, and lots of older stuff too; see PEP 256.  None use
reStructuredText though.

> Does someone experienced in writing
> reference documentation think this is the wrong way to go about it?

ISTM that there's a built-in limit to the potential quality of
auto-documentation.  It may not lend itself to a more narrative or
free-form style.  However, I hope that Docutils will be a platform for
experimentation.  That's why I'm keeping the processing stages
separate and well-defined.  See
<http://article.gmane.org/gmane.text.docutils.devel/139> and the
thread starting with
<http://article.gmane.org/gmane.text.docutils.devel/118>.

-- 
David Goodger    http://starship.python.net/~goodger    Projects:
  * Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  * The Go Tools Project: http://gotools.sourceforge.net/