On Mon, 17 Jun 2019, Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx> wrote: > On Mon, Jun 17, 2019 at 03:36:17PM +0300, Jani Nikula wrote: >> On Fri, 14 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote: >> > Em Fri, 14 Jun 2019 16:06:03 +0200 >> > Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx> 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? For example, have a single coherent system, instead of a fragile pipe with each stage written in a different language, each having its own idiosynchracies, each step losing something in translation. Have a system that a normal developer can actually look at and understand. It didn't use to be that way. > 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. Fair enough, let's dismiss the thought of changing the ABI files. But I never meant that would somehow be for the "purity of scripts", or that those two would somehow be at odds here. > 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? I'll leave it all up to Jon's discretion; I trust he'll understand my concerns. I have no authority beyond the opinion I've voiced here anyway. BR, Jani. -- Jani Nikula, Intel Open Source Graphics Center
