Re: V4L docs and docbook

[Jani Nikula]

On Thu, 18 Feb 2016, Hans Verkuil <hverkuil@xxxxxxxxx> wrote:
> I looked at ReStructuredText and it looks like it will be a pain to convert
> the media DocBook code to that, and the main reason is the poor table support.
> The syntax for that looks very painful and the media DocBook is full of tables.

The table support seems to be one point in favor of asciidoc over
reStructuredText [citation needed].

> BTW, my daily build scripts also rebuilds the media spec and it is available
> here: https://hverkuil.home.xs4all.nl/spec/media.html
>
> Also missing in ReStructuredText seems to be support for formulas (see for
> example the Colorspaces section in the spec), although to be fair standard
> DocBook doesn't do a great job at that either.

This may be true for vanilla rst as supported by Python docutils, but
the Sphinx tool we're considering does support a lot of things through
extensions. The builtin extensions include support for rendering math
via PNG or javascript [1]. There's also support for embedded graphviz
[2] which may be of interest.

> Now, I hate DocBook so going to something easier would certainly be nice,
> but I think it is going to be a difficult task.
>
> Someone would have to prove that going to another formatting tool will
> produce good results for our documentation. We can certainly give a few
> representative sections of our doc to someone to convert, and if that
> looks OK, then the full conversion can be done.

It would be great to have you actively on board doing this yourself,
seeking the solutions, as you're the ones doing your documentation in
the end.

Speaking only for myself, I'd rather prove we can produce beautiful
documentation from lightweight markup for ourselves, and let others make
their own conclusions about switching over or sticking with DocBook.

> We have (and still are) put a lot of effort into our documentation and
> we would like to keep the same level of quality.

We are doing this because we (at least in the graphics community) also
put a lot of effort into documentation, and we would like to make it
*better*!

I believe switching to some lightweight markup will be helpful in
attracting more contributions to documentation.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center