Re: Proposal: move forward to Sphinx
Hideki Yamane <henrich@debian.or.jp> writes:
> Russ Allbery <rra@debian.org> wrote:
>> 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.
> Almost done (and probably will finish in this weekend).
> I'll show you PoC later.
> During conversion, some notes:
> - Some tables should be fixed hy hand.
> (e.g. license list in copyright-format-1.0)
> - footnote should be placed manually.
> - Should we split each chapter on small document?
> menu-policy has just 2 chapters... and debconf-specification and
> perl-policy are not so huge, it's better to put it into one html
> file, IMHO.
Yeah, I was planning on turning menu-policy into a single HTML document in
the next release even with DocBook. I wasn't sure about perl-policy and
debconf-specification, but maybe it would be more convenient for everyone
to just have them as single HTML files as well. They're both less than
40KB, so yeah, let's just do that.
I got a chance to write some stuff in reStructuredText, and yup, I am a
total convert. This is great. There's a really good Emacs mode, it's
actually a fully-featured markup language (unlike Markdown), and it's
still very easy to write and quite readable as plain text. I'm 100% on
board with converting things. I think this will help immensely in making
the documents more maintainable.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: