headers
David Goodger | 1 Sep 2004 22:12
Favicon

Re: Generating LaTeX for Python manual

[Greg Ward]
 > Hi all -- I've been having a bit of fun with docutils lately, trying
 > to turn my reStructuredText docs for Optik into LaTeX for the Python
 > Library Reference.

Some work has been done on this.  Check in the sandbox
(http://docutils.sf.net/sandbox) there are files under edloper/docpy/
and dkuhlman/.

 > The good news is that I can do almost everything by subclassing
 > docutils.writers.latex2e.LaTeXTranslator; I'll include my subclass
 > below for posterity and critiquing.

Cool; thanks!

 > There are a few annoyances:
 >
 >   * the Python doc markup has many ways of saying "literal":
 >     \method{}, \func{}, \var{}, \class{}, \module{}, \code{}, etc.
...
 >     Given reST's syntax, though, I can't think of a fundamentally
 >     better way, but I'm open to ideas for improving my
 >     implementation.

That would be the :role:`interpreted text` syntax:

     :method:`add_option()`
     `set_defaults()`:method:
     :class:`OptionParser`
     `Option`:class:
(Continue reading)

Permalink | Reply | 2 comments |
headers
David Goodger | 1 Sep 2004 22:27
Favicon

Re: Re: Getting a node's indentation

So you'd like to automatically edit the source.  What will you do with
it?  If you plan to just process the modified source, automatically
editing the source is not the right approach.  If you plan to save the
modified source, I don't know.

Instead, I'd recommend that you write a transform that inserts nodes
into the document tree, post-parsing.  IOW, don't deal with reST, deal
directly with the parsed document.

[Mohsen Moeeni]
 > I can express the problem with this statement: I attach
 > an Id to each node.

How?  (Automatically?  Manually?)  When?

 > Having a node's Id, In some function,
 > I need to put a directive just after that node.

Instead, insert a new node into the document tree.  It's much easier.

If this doesn't apply to your problem, please describe it more fully.

To answer your original question, Docutils doesn't keep track of the
indentation of nodes' source text, because it doesn't need to.

--

-- 
David Goodger <http://python.net/~goodger>
Permalink | Reply | 0 comments |
headers
Felix Wiemann | 1 Sep 2004 23:48
Picon

Re: Generating LaTeX for Python manual

David Goodger wrote:

> You can also implement them as custom roles by adding this to your
> documents:
>
>      .. role:: method(literal)
>      .. role:: class(literal)
>      .. role:: func(literal)
>      .. role:: var(literal)
>      .. role:: module(literal)
>      .. role:: code(literal)

I just tried that, and it causes Docutils to crash (error with
NestedStateMachine).

--------------------------------
.. role:: method(literal)
.. role:: class(literal)
.. role:: func(literal)
.. role:: var(literal)
.. role:: module(literal)
.. role:: code(literal)
--------------------------------

It works when putting some text between the role definitions:

--------------------------------
.. role:: method(literal)

test
(Continue reading)

Permalink | Reply | 1 comment |
headers
David Goodger | 2 Sep 2004 00:00
Favicon

Re: Re: Generating LaTeX for Python manual

> David Goodger wrote:
>> You can also implement them as custom roles by adding this to your
>> documents:
>>
>>     .. role:: method(literal)
>>     .. role:: class(literal)
>>     .. role:: func(literal)
>>     .. role:: var(literal)
>>     .. role:: module(literal)
>>     .. role:: code(literal)

[Felix Wiemann]
> I just tried that, and it causes Docutils to crash (error with
> NestedStateMachine).

That must be a bug.

> BTW, am I right that using such roles for LaTeX output would need
> support by the writer class?

Yes, correct.  But it's better than using text-based
mappings.  Eventually, it would be nice if the LaTeX writer and/or
DocPy/LaTeX writer had generic support for custom roles.

--

-- 
David Goodger <http://python.net/~goodger>
Permalink | Reply | 0 comments |
headers
Greg Ward | 2 Sep 2004 14:29
Favicon

Re: Re: Generating LaTeX for Python manual


[me]
>   * reST/docutils metadata doesn't map too well to the requirements
>     for Python module docs,

[Felix Wiemann]
> What do you mean with 'metadata'?  The bibliographic data at the top of
> a document?  Or the meta directive?

I was referring to the bibliographic data.  For a Python module, this
looks something like:

  \section{\module{optparse} ---
          Powerful parser for command line options.}

  \declaremodule{standard}{optparse}
  \moduleauthor{Greg Ward}{gward <at> python.net}
  \sectionauthor{Johannes Gijsbers}{jlgijsbers <at> users.sf.net}
  \sectionauthor{Greg Ward}{gward <at> python.net}

  \modulesynopsis{Powerful, flexible, extensible, easy-to-use command-line
                  parsing library.}

  \versionadded{2.3}

(from Doc/lib/liboptparse.tex in the current Python CVS).  So the
metadata values here are:

  * module name
  * module summary
(Continue reading)

Permalink | Reply | 1 comment |
headers
David Goodger | 2 Sep 2004 15:51
Favicon

Re: Re: Generating LaTeX for Python manual

[Greg Ward]
 > I was referring to the bibliographic data.
...
 > Of these, only author/authors clearly map to metadata needed for a
 > Python module.  So I could do this in my reST doc:
 >
 >   :ModuleName: optparse
 >   :Author: Greg Ward <gward <at> python.net>
 >   :VersionAdded: 2.3
 >   [...etc...]
 >
 > but that would mean processing :Author: in the "docinfo" node, and
 > everything else in "field" nodes.   Blecch.

Note that all bibliographic fields, even unregistered fields, are
contained within the "docinfo" node.  See
<http://docutils.sf.net/docs/ref/rst/restructuredtext.html#bibliographic-fields>.

 > I suppose I could do this:
 >
 >   :ModuleName: optparse
 >   :ModuleAuthor: Greg Ward <gward <at> python.net>
 >   :VersionAdded: 2.3
 >   [...etc...]
 >
 > but that means I can't use the handy "docinfo" stuff, which really
 > felt much easier and more convenient than the general "field" model.

A DocPy Reader component may register a DocPy-specific set of
bibliographic fields.  Along with other DocPy-specific stuff, like the
(Continue reading)

Permalink | Reply | 0 comments |
headers
Michael Krishtopa | 4 Sep 2004 13:57
Picon

(no subject)

Здравствуйте, docutils-users <at> lists.sf.net.

Docutils version (0.3.5),
Python version (2.3.3)
Win2000

Converting this file with rst2html.py invoke error.

--
Best regards, Theo
np: Дельфин - Дилеp [paused]
Баннер без ссылки - траффик на ветер.
Attachment (ch7.rst): application/octet-stream, 71 KiB
Permalink | Reply | 2 comments |
headers
David Goodger | 4 Sep 2004 16:01
Favicon

Re: (no subject)

[Michael Krishtopa]
 > Docutils version (0.3.5),
 > Python version (2.3.3)
 > Win2000
 >
 > Converting this file with rst2html.py invoke error.

It works for me, with the latest Docutils from CVS.
Please try reinstalling from
<http://docutils.sf.net/docutils-snapshot.tgz>.

If there's still a problem, please supply a literal
transcript of the *exact* command you ran, and the
*exact* output.  Use the "--traceback" option to get
a complete picture.  See <http://docutils.sf.net/BUGS.html>.

--

-- 
David Goodger <http://python.net/~goodger>
Permalink | Reply | 0 comments |
headers
Marc 'BlackJack' Rintsch | 4 Sep 2004 19:32
Picon

Re: (no subject)

On Saturday 04 September 2004 13:57, Michael Krishtopa wrote:

> Docutils version (0.3.5),
> Python version (2.3.3)
> Win2000

Docutils 0.3.5 + Python 2.3.3 + Linux

``rst2html.py ch7.rst > ch7.html`` works without errors for me.

Ciao,
 Marc 'BlackJack' Rintsch
--

-- 
>>> wie kann ich in ms-office oder in staroffice am einfachsten falt-
>>> und lochmarken einfügen?
>>In eine Software Faltmarken einfügen geht grundsätzlich nicht x-)
>Dennoch kann man die eine oder andere Software knicken! ;-)
Permalink | Reply | 0 comments |
headers
David Goodger | 6 Sep 2004 01:16
Favicon

Re: Newbie to DocUtils

[Colin J. Williams]
 > I am slowly fighting my way through DocFactory, which is a great
 > tool as far as it goes.
 >
 > 1. It would really help if there were an index to the various docs,
 >    as with Python.chm

Patches are welcome!

 > 2. Tables are a real problem.

How so?

 >    There is a CSV directive which might be helpful, but I haven't
 >    yet sorted out how to specify line breaks, as with a chunk of
 >    Python code.

The CSV-table directive is meant for copy & paste (or file inclusion)
from CSV sources.  It's not really meant for original data entry.

 > 3. It would be nice if the editor incorporated ^W for window closing
 >    and a re based Find and Replace, so that one can Find "^" to
 >    replace with ".. ".  To comment out code.

You can comment out an entire block with a single ".." and
indentation:

..
    Put the ".." on the first line by itself,
    then indent everything you'd like to
(Continue reading)

Permalink | Reply | 5 comments |

Gmane