Hideki Yamane <henr...@debian.or.jp> writes: > I want to discuss with you about making policy doc much modern > with Sphinx.
> Here's my opinion and PoC > > https://www.slideshare.net/henrich_d/challenge-convert-policy-doc-from-docbook-to-sphinx-77172587 > > and sample output with Sphinx > http://www.ma-aya.to/~henrich/debian/policy/ > Please tell me your impression/opinion/etc. > (I'm not on list, so please cc: me) I personally would be a huge fan of making this work, since I really dislike editing XML and completely agree with the barrier to entry argument. Sphinx is well-maintained and widely known and won't be going anywhere, which is good. And the example output is encouraging. That said, I think there are a few requirements we'd want in place before doing this change: 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.) 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. 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.) 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? 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? 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. Definitely happy to hear more opinions on this. -- Russ Allbery (r...@debian.org) <http://www.eyrie.org/~eagle/>
