linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jonathan Corbet <corbet@lwn.net>
To: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>,
	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Mauro Carvalho Chehab <mchehab@s-opensource.com>,
	Mauro Carvalho Chehab <mchehab@infradead.org>,
	linux-kernel@vger.kernel.org
Subject: Re: [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book
Date: Mon, 17 Jun 2019 07:48:29 -0600	[thread overview]
Message-ID: <20190617074829.70cbaa48@lwn.net> (raw)
In-Reply-To: <20190617125438.GA18554@kroah.com>

On Mon, 17 Jun 2019 14:54:38 +0200
Greg Kroah-Hartman <gregkh@linuxfoundation.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

  reply	other threads:[~2019-06-17 13:48 UTC|newest]

Thread overview: 63+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-06-14  2:04 [PATCH 00/14] Add support to generate ABI documentation at admin-guide Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 01/14] ABI: fix some syntax issues at the ABI database Mauro Carvalho Chehab
2019-06-14  7:20   ` Andrew Donnellan
2019-06-14 16:16     ` Greg Kroah-Hartman
2019-06-14  8:30   ` Rafael J. Wysocki
2019-06-14  2:04 ` [PATCH 02/14] ABI: sysfs-driver-hid: the "What" field doesn't parse fine Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 03/14] ABI: sysfs-class-uwb_rc: remove a duplicated incomplete entry Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 04/14] ABI: better identificate tables Mauro Carvalho Chehab
2019-06-19 12:51   ` Johan Hovold
2019-06-19 13:56     ` Mauro Carvalho Chehab
2019-06-19 15:02       ` Greg Kroah-Hartman
2019-06-19 16:14         ` Mauro Carvalho Chehab
2019-06-20 14:27           ` Mauro Carvalho Chehab
2019-06-21  7:21             ` Greg Kroah-Hartman
2019-06-21  9:49               ` Mauro Carvalho Chehab
2019-06-20 12:01         ` Johan Hovold
2019-06-20 12:54           ` Greg Kroah-Hartman
2019-06-20 14:20             ` Mauro Carvalho Chehab
2019-06-20 16:29               ` Greg Kroah-Hartman
2019-06-20 17:16                 ` Mauro Carvalho Chehab
2019-06-20 17:55                   ` Greg Kroah-Hartman
2019-06-14  2:04 ` [PATCH 05/14] scripts: add an script to parse the ABI files Mauro Carvalho Chehab
2019-06-14 13:31   ` Jani Nikula
2019-06-14 13:39     ` Greg Kroah-Hartman
2019-06-14 13:58       ` Mauro Carvalho Chehab
2019-06-14 14:00       ` Jani Nikula
2019-06-14 14:14         ` Jonathan Corbet
2019-06-14 16:24         ` Greg Kroah-Hartman
2019-06-14  2:04 ` [PATCH 06/14] scripts/get_abi.pl: parse files with text at beginning Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 07/14] scripts/get_abi.pl: avoid use literal blocks when not needed Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 08/14] scripts/get_abi.pl: split label naming from xref logic Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 09/14] scripts/get_abi.pl: add support for searching for ABI symbols Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 10/14] scripts/get_abi.pl: represent what in tables Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 11/14] scripts/get_abi.pl: fix parse issues with some files Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book Mauro Carvalho Chehab
2019-06-14 13:42   ` Jani Nikula
2019-06-14 14:06     ` Greg Kroah-Hartman
2019-06-14 15:27       ` Mauro Carvalho Chehab
2019-06-17 12:36         ` Jani Nikula
2019-06-17 12:54           ` Greg Kroah-Hartman
2019-06-17 13:48             ` Jonathan Corbet [this message]
2019-06-17 13:50             ` Jani Nikula
2019-06-17 13:51           ` Mauro Carvalho Chehab
2019-06-18  8:47             ` Jani Nikula
2019-06-19 16:37               ` Mauro Carvalho Chehab
2019-06-21 14:27                 ` Mauro Carvalho Chehab
2019-06-27  9:48                   ` Jani Nikula
2019-06-27 10:52                     ` Mauro Carvalho Chehab
2019-06-14 14:10     ` Markus Heiser
2019-06-14 14:15       ` Jonathan Corbet
2019-06-16 16:04         ` Markus Heiser
2019-06-17  9:11           ` Mauro Carvalho Chehab
2019-06-17 16:31             ` Markus Heiser
2019-06-14  2:04 ` [PATCH 13/14] sphinx/kernel_abi.py: make it compatible with Sphinx 1.7+ Mauro Carvalho Chehab
2019-06-14  2:04 ` [PATCH 14/14] docs: sphinx/kernel_abi.py: fix UTF-8 support Mauro Carvalho Chehab
2019-06-14 16:18   ` Greg Kroah-Hartman
2019-06-14 16:25     ` Mauro Carvalho Chehab
2019-06-15  6:16       ` Greg Kroah-Hartman
2019-06-16 15:43       ` Markus Heiser
2019-06-17  9:16         ` Mauro Carvalho Chehab
2019-06-17 13:56           ` Jonathan Corbet
2019-06-17 15:55             ` Mauro Carvalho Chehab
2019-06-14 16:20 ` [PATCH 00/14] Add support to generate ABI documentation at admin-guide Greg Kroah-Hartman

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190617074829.70cbaa48@lwn.net \
    --to=corbet@lwn.net \
    --cc=gregkh@linuxfoundation.org \
    --cc=jani.nikula@linux.intel.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mchehab+samsung@kernel.org \
    --cc=mchehab@infradead.org \
    --cc=mchehab@s-opensource.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).