Re: Converting dev-ref to use rST

[Osamu Aoki <osamu@debian.org>]

Hi,

On Mon, Apr 08, 2019 at 02:45:29PM -0700, Sean Whitton wrote:
> Hello,
> 
> I am considering to working to convert dev-ref to rST+Sphinx this
> summer.  I would like to start a discussion about doing that.  The
> main things that I need to learn from this discussion are:
> 
> - who else is interested in working on this;
> 
> - whether I should use the scripts that were used to convert
>   debian-policy Debian-SGML->docbook->rST+Sphinx, or instead write a
>   new Debian-SGML->rST+Sphinx converter; and

I recommend to do:

 Debian-SGML->docbook xml (This is must.  This is one line command)

 optional
 docbook xml -> xml with any tweak if needed
                with simple xmlt tricks
                (Of course, pandoc converter may be tweaked too)
   xml -> rST+Sphinx with pandoc -- my choice
          --- Q: How good is this?

   xml -> rST+Sphinx with custom xslt scripts 
          -- if someone care to do...?

Also, we need to pick PO system for rST+Sphinx?
Can anyone point me to it.

 * If it is po4a, making PO from matched rST+Sphinx
   is no-brainer.
 * If it is any other script framework, we can still do it
   easily.  (via mo file etc.)
   I have done some work along this line so we can use that
   scripts.  https://github.com/osamuaoki/poutils

> - whether there is some reason that this should not be worked on at
>   the present time, and whether any of the dev-ref uploaders object to
>   the prospect of my unilaterally committing and uploading this
>   change.

> With regard to the second item, the question is whether it would be
> significantly more efficient to try to reuse the old scripts.

Yes, as long as we have a matching snapshot of Debian-SGML, it saves a
lot of time.  Usually, it is easier to work on XML than SGML if you want
to apply automated script.

> While I worked on the docbook->rST+Sphinx stage of converting
> debian-policy, I was not involved in the Debian-SGML->docbook stage,
> so I need others' input on that.

Hold on a bit.  Let me check few things.

> If I end up writing a new conversion script, I don't expect to be able
> to produce a program that will every single bit of markup right, but
> one that would get most of the way there.  This approach worked well
> for Policy when we converted that to rST+Sphinx in 2017.

Yes and no.  You didn't have translation.

Now that we have nice build script from reST, we should think to
automate as much.

Osamu