Em Fri, 28 Oct 2016 08:31:57 -0400
Greg Kroah-Hartman <gre...@linuxfoundation.org> escreveu:
> On Fri, Oct 28, 2016 at 10:19:47AM -0200, Mauro Carvalho Chehab wrote:
> > Use a script to parse the Documenation/ABI directory and output
> > it at the admin-guide.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
> > ---
> > Documentation/admin-guide/abi.rst | 5 +
> > Documentation/admin-guide/index.rst | 1 +
> > Documentation/sphinx/abi_book.pl | 208
> > ++++++++++++++++++++++++++++++++++++
> > 3 files changed, 214 insertions(+)
> > create mode 100644 Documentation/admin-guide/abi.rst
> > create mode 100755 Documentation/sphinx/abi_book.pl
>
> Any hint as to what the output of this actually looks like?
The current output is:
=====================
Linux ABI description
=====================
/config/acpi (testing)
- defined on file configfs-acpi (type: testing)
::
This represents the ACPI subsystem entry point directory. It
contains sub-groups corresponding to ACPI configurable options.
/config/acpi/table (testing)
- defined on file configfs-acpi (type: testing)
::
This group contains the configuration for user defined ACPI
tables. The attributes of a user define table are:
aml - a binary attribute that the user can use to
fill in the ACPI aml definitions. Once the aml
data is written to this file and the file is
closed the table will be loaded and ACPI devices
will be enumerated. To check if the operation is
successful the user must check the error code
for close(). If the operation is successful,
subsequent writes to this attribute will fail.
The rest of the attributes are read-only and are valid only
after the table has been loaded by filling the aml entry:
signature - ASCII table signature
length - length of table in bytes, including the header
revision - ACPI Specification minor version number
oem_id - ASCII OEM identification
oem_table_id - ASCII OEM table identification
oem_revision - OEM revision number
asl_compiler_id - ASCII ASL compiler vendor ID
asl_compiler_revision - ASL compiler version
...
You can see it formatted in HTML at:
https://mchehab.fedorapeople.org/kernel_docs/admin-guide/abi.html
(please notice that it takes some time to load such page, at least on
Firefox).
We could, in the future, replace the code blocks (e. g. unparsed chunks of
string, starting with ::) by ReST, but this will require touching on a lot
of files, as things like:
signature - ASCII table signature
length - length of table in bytes, including the header
revision - ACPI Specification minor version number
oem_id - ASCII OEM identification
oem_table_id - ASCII OEM table identification
oem_revision - OEM revision number
asl_compiler_id - ASCII ASL compiler vendor ID
asl_compiler_revision - ASL compiler version
would require conversion, as otherwise, it would be displayed as:
This group contains the configuration for user defined ACPI tables. The
attributes of a user define table are: aml - a binary attribute that the user
can use to fill in the ACPI aml definitions. Once the aml data is written to
this file and the file is closed the table will be loaded and ACPI devices will
be enumerated. To check if the operation is successful the user must check the
error code for close(). If the operation is successful, subsequent writes to
this attribute will fail. The rest of the attributes are read-only and are
valid only after the table has been loaded by filling the aml entry: signature
- ASCII table signature length - length of table in bytes, including the header
revision - ACPI Specification minor version number oem_id - ASCII OEM
identification oem_table_id - ASCII OEM table identification oem_revision - OEM
revision number asl_compiler_id - ASCII ASL compiler vendor ID
asl_compiler_revision - ASL compiler version
Maybe, instead of "Description", we could use "Description-rst" (or
something similar in the future) for enriched-text descriptions.
>
> No matter, I like this, thanks for doing this, it should be really
> helpful.
Thanks!
> Acked-by: Greg Kroah-Hartman <gre...@linuxfoundation.org>
Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
