Re: Proposal: move forward to Sphinx
Hideki Yamane <henrich@debian.or.jp> writes:
> 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
That looks pretty good! Certainly no worse than what we have now.
>> 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.
The approach that Guillem took with the DocBook conversion is to tune a
script that did all the conversions until it could handle all of the
documents, and then we were able to do that conversion all at once in one
release. That's ideal, but certainly understood if you want to merge some
partial results first.
>> 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.
I was looking at:
http://www.ma-aya.to/~henrich/debian/policy/ch-maintainerscripts.html#summary-of-ways-maintainer-scripts-are-called
but that was a disaster in various formats in DocBook as well. I'm
curious to see if it will be any better now since I significantly changed
the representation in DocBook to try to get better text output (and
somewhat better HTML output).
>> 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
Oh, beautiful. Yup, that's what I meant!
> 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
I think only the debconf specification uses that, but if that's supported,
that's great.
> Sphinx supports some directives like "tip", "warning", "note", etc.
> See http://docutils.sourceforge.net/docs/ref/rst/directives.html#tip
Oh, excellent! No current examples, but the existence of this definitely
puts my mind at ease.
> 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.
Yeah, I think reStructured Text is such a huge usability win and will make
it so much easier for people to propose language that we should just go
for it.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: