Re: [PATCH 0/3] RFC: The beginning of a proper driver-api book

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Mon, 22 Aug 2016 14:57:40 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> This short series convers device-drivers.tmpl into the RST format, splits
> it up, and sets up the result under Documentation/driver-api/.  For added
> fun, I've taken one top-level file (hsi.txt) and folded it into the
> document as a way of showing the direction I'm thinking I would like things
> to go.  There is plenty more of this sort of work that could be done, to
> say the least - this is just a beginning!
> 
> The formatted results can be seen at:
> 
>     http://static.lwn.net/kerneldoc/driver-api/index.html

Thanks for doing that! IMHO, the conversion of this book is indeed
one of the first things to be done.

> As part of the long-term task to turn Documentation/ into less of a horror
> movie, I'd like to collect documentation of the driver-specific API here.

> Arguably gpu/ and the media API stuff should eventually move here, though
> we can discuss the color of that particular shed some other day.

Yeah, let's finish converting everything to rst, and then see what would
be the best way to organize it.

I have a split feelings with regards to media kAPI and driver-specific
stuff if it is better to keep it at the device-drivers book, or at a
single media book (with currently has 1031 pages on PDF output),
but let's postpone such discussion.

I'm afraid that we'll end needing to split it more than what would be
desired, in order to fix some issues with the PDF output 
part/chapter/section numbering. Unfortunately, ReST markup is too poor
to describe multi-part books, and doesn't have anything to describe
multi-book projects.

> Meanwhile, I'd appreciate comments on the general idea.

I like the general idea of breaking device-drivers.tmpl into multiple
files. IMHO, that will make easier to maintain it long term.

After looking on all 3 patches, they all look good, as a concept.

Yet, IMHO, there are a few things to be fixed before merging it. See
my comments to patch 2/3.

Regards,
Mauro

> 
> Cc: Jani Nikula <jani.nikula@intel.com>
> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> 
> Jonathan Corbet (3):
>   Docs: sphinxify device-drivers.tmpl
>   docs: split up the driver book
>   docs: Pull HSI documentation together
> 
>  Documentation/DocBook/Makefile                 |   2 +-
>  Documentation/DocBook/device-drivers.tmpl      | 521 -------------------------
>  Documentation/driver-api/basics.rst            | 120 ++++++
>  Documentation/driver-api/frame-buffer.rst      |  62 +++
>  Documentation/driver-api/index.rst             |  24 ++
>  Documentation/driver-api/infrastructure.rst    | 169 ++++++++
>  Documentation/driver-api/input.rst             |  51 +++
>  Documentation/driver-api/message-based.rst     |  30 ++
>  Documentation/driver-api/miscellaneous.rst     |  50 +++
>  Documentation/driver-api/serial-interfaces.rst | 189 +++++++++
>  Documentation/driver-api/sound.rst             |  54 +++
>  Documentation/hsi.txt                          |  75 ----
>  Documentation/index.rst                        |   1 +
>  MAINTAINERS                                    |   2 +-
>  14 files changed, 752 insertions(+), 598 deletions(-)
>  delete mode 100644 Documentation/DocBook/device-drivers.tmpl
>  create mode 100644 Documentation/driver-api/basics.rst
>  create mode 100644 Documentation/driver-api/frame-buffer.rst
>  create mode 100644 Documentation/driver-api/index.rst
>  create mode 100644 Documentation/driver-api/infrastructure.rst
>  create mode 100644 Documentation/driver-api/input.rst
>  create mode 100644 Documentation/driver-api/message-based.rst
>  create mode 100644 Documentation/driver-api/miscellaneous.rst
>  create mode 100644 Documentation/driver-api/serial-interfaces.rst
>  create mode 100644 Documentation/driver-api/sound.rst
>  delete mode 100644 Documentation/hsi.txt
> 



Thanks,
Mauro