Re: [PATCH 05/14] scripts: add an script to parse the ABI files

[Jani Nikula <jani.nikula@linux.intel.com>]

On Fri, 14 Jun 2019, Greg Kroah-Hartman <gregkh@linuxfoundation.org> wrote:
> On Fri, Jun 14, 2019 at 04:31:56PM +0300, Jani Nikula wrote:
>> On Thu, 13 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>> > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> >
>> > Add a script to parse the Documentation/ABI files and produce
>> > an output with all entries inside an ABI (sub)directory.
>> >
>> > Right now, it outputs its contents on ReST format. It shouldn't
>> > be hard to make it produce other kind of outputs, since the ABI
>> > file parser is implemented in separate than the output generator.
>> 
>> Hum, or just convert the ABI files to rst directly.
>
> And what would that look like?

That pretty much depends on the requirements we want to set on both the
ABI source files and the generated output. Obviously the requirements
can be conflicting; might be hard to produce fancy output if the input
is very limited.

At the bare minimum, you could convert the files to contain
reStructuredText field lists [1]. Add a colon at the start of the field
name, and make sure field bodies (values) are not empty.

Conversion of a file selected at random; I've only added ":" and "N/A".

diff --git a/Documentation/ABI/stable/sysfs-devices-system-cpu b/Documentation/ABI/stable/sysfs-devices-system-cpu
index 33c133e2a631..34c218b344fb 100644
--- a/Documentation/ABI/stable/sysfs-devices-system-cpu
+++ b/Documentation/ABI/stable/sysfs-devices-system-cpu
@@ -1,19 +1,20 @@
-What: 		/sys/devices/system/cpu/dscr_default
-Date:		13-May-2014
-KernelVersion:	v3.15.0
-Contact:
-Description:	Writes are equivalent to writing to
+:What: 		/sys/devices/system/cpu/dscr_default
+:Date:		13-May-2014
+:KernelVersion:	v3.15.0
+:Contact:	N/A
+:Description:	Writes are equivalent to writing to
 		/sys/devices/system/cpu/cpuN/dscr on all CPUs.
 		Reads return the last written value or 0.
 		This value is not a global default: it is a way to set
 		all per-CPU defaults at the same time.
-Values:		64 bit unsigned integer (bit field)
+:Values:	64 bit unsigned integer (bit field)
 
-What: 		/sys/devices/system/cpu/cpu[0-9]+/dscr
-Date:		13-May-2014
-KernelVersion:	v3.15.0
-Contact:
-Description:	Default value for the Data Stream Control Register (DSCR) on
+
+:What: 		/sys/devices/system/cpu/cpu[0-9]+/dscr
+:Date:		13-May-2014
+:KernelVersion:	v3.15.0
+:Contact:	N/A
+:Description:	Default value for the Data Stream Control Register (DSCR) on
 		a CPU.
 		This default value is used when the kernel is executing and
 		for any process that has not set the DSCR itself.
@@ -22,4 +23,4 @@ Description:	Default value for the Data Stream Control Register (DSCR) on
 		on any CPU where it executes (overriding the value described
 		here).
 		If set by a process it will be inherited by child processes.
-Values:		64 bit unsigned integer (bit field)
+:Values:		64 bit unsigned integer (bit field)

---

Of course, you'd still need to add higher level files to include the ABI
files.

At the other end, you could add structure and syntax to your heart's
content, and make the output fancier too.

BR,
Jani.

[1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists


-- 
Jani Nikula, Intel Open Source Graphics Center