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  PHC 
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Date:   Thu, 13 Apr 2017 07:08:43 -0300
From:   Mauro Carvalho Chehab <>
To:     Linux Doc Mailing List <>,
        Jonathan Corbet <>
Cc:     Markus Heiser <>,
        Mauro Carvalho Chehab <>,
        Mauro Carvalho Chehab <>,
        LKML <>,
        Greg Kroah-Hartman <>,
        Kees Cook <>,
        Anton Vorontsov <>,
        Colin Cross <>,
        Tony Luck <>
Subject: [PATCH v2 00/11] Documentation: Add ABI to the admin guide

That's the third attempt to add support for the Kernel ABI
at the Documentation's admin guide.

The first approach was based on a generic extension that
calls a random script. This one is based on a new Sphinx
extension with adds a symbol specific for parsing ABI

It adds a new script (scripts/ with can either
search for ABI symbols that match a regular expression or
outputs the entire documentation found inside a directory
as a ReST book.

Adding the ABI description to the Linux documentation is
as easy as adding a tab like:

	.. kernel-abi:: $srctree/Documentation/ABI/obsolete

On version 3, I improved the script to better parse the
ABI descriptions. On this version, it will identify if the
description can be handled as a normal text. If so, it will
escape characters that has special meaning on Sphinx.
If it detects that the description syntax is too complex,
it outputs inside a literal block.

Also on version 3, I opted to use 4 separate sections, one
for each type of symbol. It also add an entry with the name
of each ABI file, with has cross-references to the symbols
defined on each file.

The parser was also improved to handle any content at the
files that are before the ABI tags.

The first 3 patches on this series fix some syntax errors
on some ABI description.

The next one makes sure that, when a table is present on
the description, the preceding line will end with a colon
(with is one of the ways the script uses to identify
complex layouts).


IMHO, we should add another ABI tag to allow using an
enriched text description, e. g. instead of:

Description:  foo

One could use, instead, something like:

ReST-description: foo

On such case, the script wouldn't need to escape the
description contents, as they can be just sent directly to
the ABI ReST output.

Markus Heiser (1):
  doc-rst: customize RTD theme; literal-block

Mauro Carvalho Chehab (10):
  ABI: fix some syntax issues at the ABI database
  ABI: sysfs-driver-hid: the "What" field doesn't parse fine
  ABI: sysfs-class-uwb_rc: remove a duplicated incomplete entry
  ABI: better identificate tables
  scripts: add an script to parse the ABI files
  scripts/ parse files with text at beginning
  scripts/ avoid use literal blocks when not needed
  scripts/ split label naming from xref logic
  scripts/ add support for searching for ABI symbols
  doc-rst: add ABI documentation to the admin-guide book

 .../ABI/obsolete/sysfs-driver-hid-roccat-pyra      |   2 +-
 Documentation/ABI/testing/pstore                   |   2 +-
 .../testing/sysfs-bus-event_source-devices-format  |   2 +-
 .../ABI/testing/sysfs-bus-i2c-devices-hm6352       |   6 +-
 .../ABI/testing/sysfs-bus-iio-distance-srf08       |   4 +-
 .../ABI/testing/sysfs-bus-iio-proximity-as3935     |   4 +-
 .../ABI/testing/sysfs-bus-pci-devices-cciss        |  22 +-
 .../ABI/testing/sysfs-bus-usb-devices-usbsevseg    |  12 +-
 .../testing/sysfs-class-backlight-driver-lm3533    |   6 +-
 Documentation/ABI/testing/sysfs-class-cxl          |   6 +-
 Documentation/ABI/testing/sysfs-class-devfreq      |   2 +-
 .../ABI/testing/sysfs-class-led-driver-lm3533      |   8 +-
 Documentation/ABI/testing/sysfs-class-leds-gt683r  |   4 +-
 Documentation/ABI/testing/sysfs-class-powercap     |   2 +-
 Documentation/ABI/testing/sysfs-class-uwb_rc       |   6 -
 Documentation/ABI/testing/sysfs-driver-hid         |  12 +-
 .../ABI/testing/sysfs-driver-hid-roccat-kone       |   2 +-
 Documentation/ABI/testing/sysfs-kernel-fscaps      |   2 +-
 Documentation/ABI/testing/sysfs-kernel-vmcoreinfo  |   2 +-
 Documentation/admin-guide/abi-obsolete.rst         |  10 +
 Documentation/admin-guide/abi-removed.rst          |   4 +
 Documentation/admin-guide/abi-stable.rst           |  13 +
 Documentation/admin-guide/abi-testing.rst          |  19 +
 Documentation/admin-guide/abi.rst                  |  11 +
 Documentation/admin-guide/index.rst                |   1 +
 Documentation/                              |   3 +-
 Documentation/sphinx-static/theme_overrides.css    |   7 +
 Documentation/sphinx/                 | 155 ++++++++
 scripts/                                 | 419 +++++++++++++++++++++
 29 files changed, 691 insertions(+), 57 deletions(-)
 create mode 100644 Documentation/admin-guide/abi-obsolete.rst
 create mode 100644 Documentation/admin-guide/abi-removed.rst
 create mode 100644 Documentation/admin-guide/abi-stable.rst
 create mode 100644 Documentation/admin-guide/abi-testing.rst
 create mode 100644 Documentation/admin-guide/abi.rst
 create mode 100644 Documentation/sphinx/
 create mode 100755 scripts/


Powered by blists - more mailing lists