Messages in this thread | | | Subject | Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) | From | Markus Heiser <> | Date | Tue, 7 Jun 2016 08:02:06 +0200 |
| |
Am 03.06.2016 um 22:47 schrieb Jonathan Corbet <corbet@lwn.net>:
> On Mon, 30 May 2016 23:05:34 +0300 > Jani Nikula <jani.nikula@intel.com> wrote: > >>> I can't recommend to use rst2pdf (it is less maintained), use default >>> sphinx LaTeX toolchain. >> >> I think we'll use whatever works, rst2pdf seemed to work for now, but we >> can change if needed. > > I really like the idea of using rst2pdf and keeping the huge latex > dependency out of the mix. I am a bit concerned, though; I've been able > to crash it in my experiments here. We may want to have the ability to > support either chain eventually; otherwise, we might just end up picking > up maintenance of rst2pdf at some point so that it works properly for us. > > jon
I looked closer to rst2pdf, it supports only the docutils reST, but not the sphinx superset ...
<SNIP rst2pdf>------------- $ rst2pdf index.rst index.rst:15: (ERROR/3) Unknown interpreted text role "ref". index.rst:15: (ERROR/3) Unknown interpreted text role "ref". index.rst:27: (ERROR/3) Unknown directive type "toctree".
.. toctree:: :maxdepth: 1
kernel-doc-intro kernel-doc-syntax <SNAP>-------------
rules like ":ref:", domains like ":c:type:" and directives like ".. toctree:" are a part of the (extended) reST syntax from sphinx, thats why standard docutils (like rst2*) will not work ...
> Am 18.04.2016 um 10:10 schrieb Markus Heiser <markus.heiser@darmarIT.de>: > Re: Kernel docs: muddying the waters a bit > > BTW a few words about differences between DockBook and reST (Sphinx). > > With DocBook you write *books*, the protocol (the DocBook application) has > no facility to *chunk* and interconnect several documents. The external ENTITY > is a workaround on the SGML layer, not on XML nor on the DB-application layer. > Thats the reason, why so many XML-tools don't handle this entities and > many DocBook to (e.g.) reST tools are fail. > > With **standard** reST it is nearly the same, except there is a "include" > directive on the application layer. But this directive is very simple, > comparable to the C preprocessor "#include" directive. > > With the **superset** reST-markup of Sphinx-doc you get a the "toctree" directive, > which lets you control how a document-tree should be build. > > http://www.sphinx-doc.org/en/stable/markup/toctree.html > > @Mauro: you mentioned a docutils (rst2*) experience in your mail > http://marc.info/?l=linux-doc&m=145735316012094&w=2 > > Because the "toctree" directive -- and other directives > we use -- are a part of a superset of the **standard** > reST, the standard docutils (like rst2*) will not work.
-- Markus --
| |