linux-kernel - Re: [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20190617074829.70cbaa48@lwn.net>
Date:   Mon, 17 Jun 2019 07:48:29 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Greg Kroah-Hartman <gregkh@...uxfoundation.org>
Cc:     Jani Nikula <jani.nikula@...ux.intel.com>,
        Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide
 book

On Mon, 17 Jun 2019 14:54:38 +0200
Greg Kroah-Hartman <gregkh@...uxfoundation.org> wrote:

> > 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.

That was indeed one of the goals.  Another was to replace the incredible
pile of fragile duct tape that the docs build system had become with
something more robust, understandable, and maintainable.  We did that, to
an extent at least, and life is better.

Jani worries that we have been regressing toward duct-tape mode, and I
suspect he may be right.  I'm certainly as guilty as anybody of tossing
stuff in because it's expedient right now.  It is right to ask whether we
should continue in that direction.

Can we slow down just a bit on the ABI files?  It may be that Mauro's
solution is the best one, but I would really like to think a bit about
how all this stuff fits together, and life isn't really even giving me
time to tie my shoes these days.  I don't think that this is screamingly
urgent right now.

Thanks,

jon