Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1337265

Re: V4L docs and docbook

Show all headers | View raw

On 02/18/16 11:19, Jani Nikula wrote:
> On Thu, 18 Feb 2016, Hans Verkuil <hverkuil@xs4all.nl> 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.

Just to be clear: I really don't like DocBook at all, so something better and
easier would be very much appreciated.

But good table handling is a prerequisite for us since we rely heavily on that.

Regards,

	Hans

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

V4L docs and docbook Jonathan Corbet <corbet@lwn.net> - 2016-02-17 23:00 +0100
  Re: V4L docs and docbook Mauro Carvalho Chehab <mchehab@infradead.org> - 2016-02-18 01:00 +0100
    Re: V4L docs and docbook Russel Winder <russel@winder.org.uk> - 2016-02-18 09:30 +0100
      Re: V4L docs and docbook Mauro Carvalho Chehab <mchehab@infradead.org> - 2016-02-18 09:40 +0100
        Re: V4L docs and docbook Mauro Carvalho Chehab <mchehab@infradead.org> - 2016-02-18 10:20 +0100
          Re: V4L docs and docbook Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-02-18 10:30 +0100
            Re: V4L docs and docbook Russel Winder <russel@winder.org.uk> - 2016-02-19 09:30 +0100
              Re: V4L docs and docbook Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-02-19 13:40 +0100
        Re: V4L docs and docbook Jani Nikula <jani.nikula@intel.com> - 2016-02-18 10:40 +0100
          Re: V4L docs and docbook Mauro Carvalho Chehab <mchehab@infradead.org> - 2016-02-18 11:10 +0100
      Re: V4L docs and docbook Jani Nikula <jani.nikula@intel.com> - 2016-02-18 10:40 +0100
  Re: V4L docs and docbook Hans Verkuil <hverkuil@xs4all.nl> - 2016-02-18 08:00 +0100
    Re: V4L docs and docbook Jani Nikula <jani.nikula@intel.com> - 2016-02-18 11:30 +0100
      Re: V4L docs and docbook Hans Verkuil <hverkuil@xs4all.nl> - 2016-02-18 12:00 +0100
        Re: V4L docs and docbook Keith Packard <keithp@keithp.com> - 2016-02-20 08:00 +0100

csiph-web