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

Groups > linux.kernel > #1337132

Re: V4L docs and docbook

Show all headers | View raw

[Multipart message — attachments visible in raw view] - view raw

On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote:
> […]
> 
> We have 2 types of documentation for the Kernel part of the
> subsystem,
> Both using DocBook:
> - The uAPI documentation:
> 	https://linuxtv.org/downloads/v4l-dvb-apis
> - The kAPI documentation:
> 	https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/
> mediadev.html
[…]

I may not be introducing new data here but…

Whilst ReStructuredText and Markdown are fairly popular text markup
languages, they are not related to the DocBook/XML toolchain.

Many people, especially authors of books etc. are not really willing to
write in DocBook/XML even though it is the re-purposable representation
of choice for most of the major publishers. This led to ASCIIDoc.

ASCIIDoc is a plain text markup language in the same way
ReStructuredText and Markdown are, but it's intention was always to be
a lightweight front end to DocBook/XML so as to allow authors to write
in a nice markup language but work with the DocBook/XML toolchain.

ASCIIDoc has gained quite a strong following. So much so that it now
has a life of its own separate from the DocBook/XML tool chain. There
is ASCIIDoctor which generates PDF, HTML,… from the source without
using DocBook/XML, yet the source can quite happily go through a
DocBook/XML toolchain as well.

Many of the open source projects I am involved with are now using
ASCIIDoctor as the documentation form. This has increased the number of
non-main-contributor contributions via pull requests. It is so much
easier to work with ASCIIDoc(tor) source than DocBook/XML source. 
 
-- 
Russel.
=============================================================================
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:russel.winder@ekiga.net
41 Buckmaster Road    m: +44 7770 465 077   xmpp: russel@winder.org.uk
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

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