Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1413463 > unrolled thread
| Started by | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| First post | 2016-06-03 22:50 +0200 |
| Last post | 2016-06-10 19:10 +0200 |
| Articles | 4 — 3 participants |
Back to article view | Back to linux.kernel
This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by
below is the oldest one visible, not the original post.
Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) Jonathan Corbet <corbet@lwn.net> - 2016-06-03 22:50 +0200
Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) Markus Heiser <markus.heiser@darmarit.de> - 2016-06-07 08:10 +0200
Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) Jani Nikula <jani.nikula@intel.com> - 2016-06-07 08:50 +0200
Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) Markus Heiser <markus.heiser@darmarit.de> - 2016-06-10 19:10 +0200
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2016-06-03 22:50 +0200 |
| Subject | Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) |
| Message-ID | <rG4cy-7ZV-7@gated-at.bofh.it> |
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
[toc] | [next] | [standalone]
| From | Markus Heiser <markus.heiser@darmarit.de> |
|---|---|
| Date | 2016-06-07 08:10 +0200 |
| Message-ID | <rHin7-7mM-3@gated-at.bofh.it> |
| In reply to | #1413463 |
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 --
[toc] | [prev] | [next] | [standalone]
| From | Jani Nikula <jani.nikula@intel.com> |
|---|---|
| Date | 2016-06-07 08:50 +0200 |
| Message-ID | <rHiZP-7Do-9@gated-at.bofh.it> |
| In reply to | #1415723 |
On Tue, 07 Jun 2016, Markus Heiser <markus.heiser@darmarit.de> wrote: > 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". This doesn't actually happen if you run rst2pdf through Sphinx. > .. 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 ... You will get warnings like [WARNING] styles.py:548 Using undefined style 'function', aliased to style 'normal'. [WARNING] styles.py:548 Using undefined style 'type', aliased to style 'normal'. but it's a matter of defining a custom rst2pdf stylesheet. It's json with a sort of inheritance model, so it should be easy to just extend the existing stylesheet. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
[toc] | [prev] | [next] | [standalone]
| From | Markus Heiser <markus.heiser@darmarit.de> |
|---|---|
| Date | 2016-06-10 19:10 +0200 |
| Message-ID | <rIy6u-7n5-11@gated-at.bofh.it> |
| In reply to | #1415753 |
Am 07.06.2016 um 08:44 schrieb Jani Nikula <jani.nikula@intel.com>: > On Tue, 07 Jun 2016, Markus Heiser <markus.heiser@darmarit.de> wrote: >> 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". > > This doesn't actually happen if you run rst2pdf through Sphinx. > Aaah, thanks for hinting. With this in mind, I think rst2pdf is a good choice and the minor bugs in could be handled. In the long term a XeTeX builder as an alternative to produce layouts with higher quality would be nice. I (also) added rst2pdf: https://github.com/return42/linux/commit/d88c4981f86fed85e54ee4d4955b35eb9eaac063 -- M -- >> .. 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 ... > > You will get warnings like > > [WARNING] styles.py:548 Using undefined style 'function', aliased to style 'normal'. > [WARNING] styles.py:548 Using undefined style 'type', aliased to style 'normal'. > > but it's a matter of defining a custom rst2pdf stylesheet. It's json > with a sort of inheritance model, so it should be easy to just extend > the existing stylesheet. > > BR, > Jani. > > -- > Jani Nikula, Intel Open Source Technology Center
[toc] | [prev] | [standalone]
Back to top | Article view | linux.kernel
csiph-web