lkml.org 
[lkml]   [2019]   [Jun]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book
    On Mon, Jun 17, 2019 at 03:36:17PM +0300, Jani Nikula wrote:
    > On Fri, 14 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
    > > Em Fri, 14 Jun 2019 16:06:03 +0200
    > > Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
    > >
    > >> On Fri, Jun 14, 2019 at 04:42:20PM +0300, Jani Nikula wrote:
    > >> > 2) Have the python extension read the ABI files directly, without an
    > >> > extra pipeline.
    > >>
    > >> He who writes the script, get's to dictate the language of the script :)
    >
    > The point is, it's an extension to a python based tool, written in perl,
    > using pipes for communication, and losing any advantages of integrating
    > with the tool it's extending.
    >
    > I doubt you'd want to see system() to be used to subsequently extend the
    > perl tool.
    >
    > I think it's just sad to see the documentation system slowly drift
    > further away from the ideals we had, and towards the old ways we worked
    > so hard to fix.

    What are those ideals?

    I thought the goal was to be able to write documentation in a as much
    as a normal text file as possible and have automation turn those files
    into "pretty" documentation that we can all use.

    And I think that fits with the way this patch set goes, right? We are
    not on a quest for purity of scripts to generate the documentation at
    the expense of having to force hundreds, or thousands, of developers to
    change their ways, or to force a "flag day" conversion of existing
    documentation resulting in a huge merge mess.

    So, we are stuck with the current structure that I totally made up for
    Documentation/ABI/. Turns out it is almost parsable, as Mauro's tool
    shows. His tool also validates the existing text, which is great, and
    has caused fixes for it.

    If someone wants to write that tool in some other language, like python,
    wonderful, I have no objection, but as it is, this is a useful tool
    already, allowing us to validate, and search, existing documentation
    entries that we have never been able to do before. It also provides an
    output that can be turned into pretty html/pdf/whatever files by other
    tools in the pipeline, a totally bonus benefit.

    So what is going backwards here?

    Maybe the processing pipeline isn't as nice as you would like, but
    remember to view this from a normal developer's point of view, not a
    documentation pipeline developer's point of view please.

    So, in short, my requirements are:
    - keep Documentation/ABI/ file formats as close as possible to
    what we have today, preventing any flag-day issues or merge
    problems
    - be able to query and validate Documentation/ABI/
    - be able to turn Documentation/ABI into pretty documentation.

    If you object to the mechanics of the last requirement here, I don't
    object either, provide something else that works better. But don't
    throw away the whole thing just because you don't like how things are
    hooked up here.

    I'm going to go apply most of the rest of these patches to my
    driver-core tree, stopping at the "hook it up to the kernel
    documentation" point. Is that ok?

    thanks,

    greg k-h

    \
     
     \ /
      Last update: 2019-06-17 14:55    [W:4.076 / U:0.180 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site