Re: Proposal: move forward to Sphinx
On Sat, 24 Jun 2017 15:38:33 -0700
Russ Allbery <rra@debian.org> wrote:
> 1. We've always had reasonably good PDF output, and I want to maintain
> that. I'm not sure how good Sphinx's pipeline is for that, and as
> noted in the slides that would need to be tested. (ePub might be
> better than PDF at this point, though.)
Let's check it.
See http://www.ma-aya.to/~henrich/debian/policy/DebianPolicyManual.pdf
> 2. I don't think the Policy Editors probably have time to help a ton with
> the conversion, so it would need to be driven by someone else with time
> to rebase it repeatedly (probably by writing conversion scripts),
> similar to what was done with the DocBook conversion. We'd also want
> all documents in Policy to be moved to restructured text (except the
> pure text ones) so that we are on a single format as a result of this
> change.
I'll care it, of course :) But I'm not sure all conversions can be done
at once, it takes time and some effort.
> 3. Historically, text-like formats have struggled with multiply-nested
> lists with multi-paragraph blocks and embedded literal blocks. The
> output from Sphinx looks surprisingly good, so maybe its version of
> reStructured Text does address all of this. But we'd want to verify
> that we can get reasonable results from fairly complex structure.
> (There seems to be something weird going on with fonts in definition
> lists in your sample output, for instance.)
You mean http://www.ma-aya.to/~henrich/debian/policy/ch-controlfields.html#list-of-fields ?
Some weird looking can be adjust with modifying Sphinx theme, I guess.
> 4. We'd like to be able to divide documents into multiple source files for
> ease of editing (I kind of want to do that with Policy, and we're doing
> that now for the debconf specification). I'm not sure if Sphinx
> supports this?
I had splitted policydoc to restructuredtext on each chapter.
https://github.com/henrich/policydoc/tree/restructure/source
What does "multiple source" mean (Including other file)?
If so, "include" directive would help. I'll test it later.
http://docutils.sourceforge.net/docs/ref/rst/directives.html#include
> 5. I'd really like to move most of the comments into sidebars or some
> other form of embedded set-off text that we can clearly mark as
> non-normative, since reading footnotes is a kind of obnoxious
> experience in all of our output formats. DocBook has native support
> for this in multiple ways (<note>, <tip>, etc.), and I was looking
> forward to having that available (although the default formatting is
> perhaps a bit too aggressive and we'd need to find a more subtle way of
> rendering it). Would we lose that in reStructured Text?
Sphinx supports some directives like "tip", "warning", "note", etc.
See http://docutils.sourceforge.net/docs/ref/rst/directives.html#tip
And if you have good example for what you want, please share its URI.
> That said, the ease of editing improvement is *substantial*, and might be
> worth some regressions on the other points.
:)
> Probably the biggest competitor would be to move to Publican, which also
> has similar translation support (at least so I am told) and better
> rendering, but continues to use DocBook as the underlying source format.
> That said, Publican and the DocBook toolchain in general are fairly
> complicated, so if Sphinx is easier to use, that would be another nice
> advantage.
Yes, once I thought about Publican, it is also nice but little bit
tough to use, perhaps we need some people to maintain it with lots
effort. Sphinx is not so complicated and if other toolchain that can
deal with restructuredtext is better than Sphinx, we can move to it.
--
Regards,
Hideki Yamane henrich @ debian.or.jp/org
http://wiki.debian.org/HidekiYamane
Reply to: