David Goodger <goodger@...> writes:
Thank you for very helpfull feedback :-)
> [Rune Froysa]
> > To accomplish this with html it is pretty straight-forward with a
> > controller-script that runs rst2html on the various rst files. For
> > paper, things get a bit trickier. We're looking at using
> > rst2docbook and a static book.xml file looking something like this
> > (our framework convert the admin/install.rst to xml):
> >
> > <?xml version="1.0" encoding="ISO-8859-1"?>
> > <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
> > [<!ENTITY admin-install-chapter SYSTEM "admin/install.rst">]>
>
> Shouldn't that be "admin/install.xml" or ".docbook"?
Sorry, I was a bit unclear. Our build.py framework uses the .rst
extension to know what xml files to generate, and then generates a new
book.xml file (pointing to install.xml etc.) which is used for the
final build.
> > There are a few problems, however (using 23-Jul-2004 version of
> > docbook.py):
> >
> > - there is no way to control the type of docbook generated. We'd
> > like to get <chapter> rather than <article> as the outer tag in
> > the included files, and strip the xml-header. Our controller
> > script handles this, but it would be nice with a rst2docbook
> > option to handle it.
>
> There is an option to the DocBook writer, --doctype=chapter. Do
> "rst2docbook.py --help" to see all the options.
Oops, how could I have missed that :-(
> > Sometimes (when document has only one chapter) rst2docbook does
> > not have a <title> tag in the generated files, resulting in
> > illegal xml when <article> has been replaced with <chapter>.
>
> Does the source reST have a title? Could you provide us with a
> minimal example?
See the example below, and remove the chapter named "Appendix". The
resulting document will have no title/section tags.
> > - The document title is ignored by docbook. With rst2html it
> > correctly ends up in <head><title>. It would be nice if it was
> > used as the main chapter or similar, preferably controllable with
> > options to rst2docbook.
>
> I don't follow. Please provide examples.
The example below has "Test document" as title. As you can see, this
is not included in the generated XML.
> > - If using "``foo``\n bar" to indicate a definition list,
> > rst2docbook produces dtd-violating xml (<term><varname><literal>).
>
> I don't see that:
>
> $ python rst2docbook.py <<EOF
> > ``foo``
> > bar
> > EOF
What version are you using? I don't get the same result using
sandbox/oliverr/docbook/rst2docbook.py and
sandbox/oliverr/docbook/writer/docbook.py from current CVS and the
following file (2-space indenting added for readability):
==============
Test document
==============
Introduction
============
``foo``
bar
Appendix
=========
If this chapter is removed, the generated document has no chapters
Now, running rst2docbook.py on this file produces:
~/usit/new-doc/testbed@... >python rst2docbook.py <sample2.rst
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"&gt;
<article>
<section id="introduction">
<title>Introduction</title>
<variablelist>
<varlistentry>
<term>
<varname><literal>foo</literal></varname></term>
<listitem>
<para>bar</para></listitem>
</varlistentry>
</variablelist>
</section>
<section id="appendix">
<title>Appendix</title>
<para>If this chapter is removed, the generated document has no chapters</para></section>
</article>
If using the same rst file with --doctype=chapter, jade produces the
following errors:
jade:/home/runefro/usit/new-doc/testbed/sample2.xml:6:26:E: document type does not allow element "section" here
jade:/home/runefro/usit/new-doc/testbed/sample2.xml:11:17:E: document type does not allow element "literal" here
jade:/home/runefro/usit/new-doc/testbed/sample2.xml:17:22:E: document type does not allow element "section" here
jade:/home/runefro/usit/new-doc/testbed/sample2.xml:20:9:E: end tag for "chapter" which is not finished
> > - The automatic setting of id from the chapters title using the
> > title as name (docutils/nodes.py:document.set_id) results in
> > duplicate identical ids when creating one book as indicated above
> > (if the chapter 'introduction' accours in multiple files). A
> > trivial work-around is below, but it would be nice if the docbook
> > framework provided some support to avoid the issue:
>
> Yes, that is a well-known limitation. A relevant entry in the to-do
> list is <http://docutils.sf.net/docs/dev/todo.html#large-documents&gt;.
>
> The workaround you present is problematic because IDs would be
> different each time document is processed. This may be acceptable to
> you, however, in which case you're welcome to make a custom local
> wrapper.
>
> The solution I'm thinking of (a persistent ID database) wouldn't work
> in your case, however, because Docutils wouldn't know about all the
> files. I don't know when a solution will be implemented.
I would prefer if the id-mapping could be encoded in each rst file so
that I would know what name to use when refering to the file from
another document. Something like this at the top of the document:
.. id_mappings:
introduction=some_text_that_I_specify
Where 'introduction' is the ID that docutils normally would use, and
some_text_that_I_specify is what document.set_id ends up using.
> You'd prefer not to generate section numbers at all, or just suppress
> the non-breaking spaces? If the former, there's already an option to
> do that: --no-section-numbering.
--no-section-numbering does exactly what I want :-)
It would be preferable if a --no-Contents switch also was available,
but I'll let our framework handle that. We already pre-process the
rst files anyway to insert docstrings from modules/classes/methods at
spesific locations in the rst file.
The reason that we want to have the section-numbering/contents
directive in the rst file, while at the same time being able to turn
it off is that there are differences in how one wants the printed
"book" to look like, compared to the generated set of html files. A
table of contents at the beginning of each chapter in a book may look
silly, while it will be useful on the html pages. (We also expect
that we'll have to write some files that are only available in the
html or pdf version, but not both.)
Speaking of pdf/html; it would be great if the figure/image directive
could be tweaked to use a png or ps image depending on the type of
output generated.
--
Rune Frøysa

[Rune Froysa]
> We're working on documenting some software, and has settled on rst
> due to its ease of use.
Glad to hear it! You've come to the right place for support.
I assume you realize that the DocBook support in Docutils is not
complete yet. The code you're using came from the sandbox, developed
by Oliver Rutherfurd and Paul Tremblay, and needs completion and
testing. I hope you're willing to provide some of that.
> We want to produce html and paper documentation. The printed
> version is expected to be about 100 pages.
>
> To accomplish this with html it is pretty straight-forward with a
> controller-script that runs rst2html on the various rst files. For
> paper, things get a bit trickier. We're looking at using
> rst2docbook and a static book.xml file looking something like this
> (our framework convert the admin/install.rst to xml):
>
> <?xml version="1.0" encoding="ISO-8859-1"?>
> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
> [<!ENTITY admin-install-chapter SYSTEM "admin/install.rst">]>
Shouldn't that be "admin/install.xml" or ".docbook"?
> <book><title>bla bla</title>......
> &admin-install-chapter;
> &admin-bofh-chapter;
> </book>
>
> There are a few problems, however (using 23-Jul-2004 version of
> docbook.py):
>
> - there is no way to control the type of docbook generated. We'd
> like to get <chapter> rather than <article> as the outer tag in
> the included files, and strip the xml-header. Our controller
> script handles this, but it would be nice with a rst2docbook
> option to handle it.
There is an option to the DocBook writer, --doctype=chapter. Do
"rst2docbook.py --help" to see all the options. For more complete
descriptions, see <http://docutils.sf.net/docs/user/config.html&gt;.
> Sometimes (when document has only one chapter) rst2docbook does
> not have a <title> tag in the generated files, resulting in
> illegal xml when <article> has been replaced with <chapter>.
Does the source reST have a title? Could you provide us with a
minimal example?
> - The document title is ignored by docbook. With rst2html it
> correctly ends up in <head><title>. It would be nice if it was
> used as the main chapter or similar, preferably controllable with
> options to rst2docbook.
I don't follow. Please provide examples.
> - If using "``foo``\n bar" to indicate a definition list,
> rst2docbook produces dtd-violating xml (<term><varname><literal>).
I don't see that:
$ python rst2docbook.py <<EOF
> ``foo``
> bar
> EOF
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"&gt;
<article>
<variablelist>
<varlistentry>
<term>
<varname>foo</varname></term>
<listitem>
<para>bar</para></listitem>
</varlistentry>
</variablelist>
</article>
> - The automatic setting of id from the chapters title using the
> title as name (docutils/nodes.py:document.set_id) results in
> duplicate identical ids when creating one book as indicated above
> (if the chapter 'introduction' accours in multiple files). A
> trivial work-around is below, but it would be nice if the docbook
> framework provided some support to avoid the issue:
Yes, that is a well-known limitation. A relevant entry in the to-do
list is <http://docutils.sf.net/docs/dev/todo.html#large-documents&gt;.
The workaround you present is problematic because IDs would be
different each time document is processed. This may be acceptable to
you, however, in which case you're welcome to make a custom local
wrapper.
The solution I'm thinking of (a persistent ID database) wouldn't work
in your case, however, because Docutils wouldn't know about all the
files. I don't know when a solution will be implemented.
Ideas, discussion, and contributions are welcome!
> - When using ".. section-numbering::", one gets some extra
> characters after the number: "1Â Â Â Introduction".
Those characters are 3 non-breaking spaces, encoded with UTF-8 (the
default output encoding). See question 3.6 of the FAQ,
<http://docutils.sourceforge.net/FAQ.html&gt;.
> It would be preferable if one could choose to ignore this setting
> when generating docbook output.
You'd prefer not to generate section numbers at all, or just suppress
the non-breaking spaces? If the former, there's already an option to
do that: --no-section-numbering. You could add a "[docbook writer]"
section to your configuration file, containing "sectnum_xform: off".
--
David Goodger <http://python.net/~goodger&gt;

Community

Help

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

I agree to receive quotes, newsletters and other information from sourceforge.net and its partners regarding IT services and products. I understand that I can withdraw my consent at any time. Please refer to our Privacy Policy or Contact Us for more details