All of lore.kernel.org
 help / color / mirror / Atom feed
From: Jani Nikula <jani.nikula@linux.intel.com>
To: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
	Mauro Carvalho Chehab <mchehab@infradead.org>,
	linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Subject: Re: [PATCH 05/14] scripts: add an script to parse the ABI files
Date: Fri, 14 Jun 2019 16:31:56 +0300	[thread overview]
Message-ID: <87r27wuwc3.fsf@intel.com> (raw)
In-Reply-To: <196fb3c497546f923bf5d156c3fddbe74a4913bc.1560477540.git.mchehab+samsung@kernel.org>

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.

BR,
Jani.



>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  scripts/get_abi.pl | 212 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 212 insertions(+)
>  create mode 100755 scripts/get_abi.pl
>
> diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
> new file mode 100755
> index 000000000000..f7c9944a833c
> --- /dev/null
> +++ b/scripts/get_abi.pl
> @@ -0,0 +1,212 @@
> +#!/usr/bin/perl
> +
> +use strict;
> +use Pod::Usage;
> +use Getopt::Long;
> +use File::Find;
> +use Fcntl ':mode';
> +
> +my $help;
> +my $man;
> +my $debug;
> +
> +GetOptions(
> +	"debug|d+" => \$debug,
> +	'help|?' => \$help,
> +	man => \$man
> +) or pod2usage(2);
> +
> +pod2usage(1) if $help;
> +pod2usage(-exitstatus => 0, -verbose => 2) if $man;
> +
> +pod2usage(2) if (scalar @ARGV != 1);
> +
> +my ($prefix) = @ARGV;
> +
> +require Data::Dumper if ($debug);
> +
> +my %data;
> +
> +#
> +# Displays an error message, printing file name and line
> +#
> +sub parse_error($$$$) {
> +	my ($file, $ln, $msg, $data) = @_;
> +
> +	print STDERR "file $file#$ln: $msg at\n\t$data";
> +}
> +
> +#
> +# Parse an ABI file, storing its contents at %data
> +#
> +sub parse_abi {
> +	my $file = $File::Find::name;
> +
> +	my $mode = (stat($file))[2];
> +	return if ($mode & S_IFDIR);
> +	return if ($file =~ m,/README,);
> +
> +	my $name = $file;
> +	$name =~ s,.*/,,;
> +
> +	my $type = $file;
> +	$type =~ s,.*/(.*)/.*,$1,;
> +
> +	my $what;
> +	my $new_what;
> +	my $tag;
> +	my $ln;
> +
> +	print STDERR "Opening $file\n" if ($debug > 1);
> +	open IN, $file;
> +	while(<IN>) {
> +		$ln++;
> +		if (m/^(\S+):\s*(.*)/i) {
> +			my $new_tag = lc($1);
> +			my $content = $2;
> +
> +			if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) {
> +				if ($tag eq "description") {
> +					$data{$what}->{$tag} .= "\n$content";;
> +					$data{$what}->{$tag} =~ s/\n+$//;
> +					next;
> +				} else {
> +					parse_error($file, $ln, "tag '$tag' is invalid", $_);
> +				}
> +			}
> +
> +			if ($new_tag =~ m/what/) {
> +				if ($tag =~ m/what/) {
> +					$what .= ", " . $content;
> +				} else {
> +					$what = $content;
> +					$new_what = 1;
> +				}
> +				$tag = $new_tag;
> +				next;
> +			}
> +
> +			$tag = $new_tag;
> +
> +			if ($new_what) {
> +				$new_what = 0;
> +
> +				$data{$what}->{type} = $type;
> +				$data{$what}->{file} = $name;
> +				print STDERR "\twhat: $what\n" if ($debug > 1);
> +			}
> +
> +			if (!$what) {
> +				parse_error($file, $ln, "'What:' should come first:", $_);
> +				next;
> +			}
> +			$data{$what}->{$tag} = $content;
> +			next;
> +		}
> +
> +		# Silently ignore any headers before the database
> +		next if (!$tag);
> +
> +		if (m/^\s*(.*)/) {
> +			$data{$what}->{$tag} .= "\n$1";
> +			$data{$what}->{$tag} =~ s/\n+$//;
> +			next;
> +		}
> +
> +		# Everything else is error
> +		parse_error($file, $ln, "Unexpected line:", $_);
> +	}
> +	close IN;
> +}
> +
> +# Outputs the output on ReST format
> +sub output_rest {
> +	foreach my $what (sort keys %data) {
> +		my $type = $data{$what}->{type};
> +		my $file = $data{$what}->{file};
> +
> +		my $w = $what;
> +		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
> +
> +		print "$w\n\n";
> +		print "- defined on file $file (type: $type)\n\n::\n\n";
> +
> +		my $desc = $data{$what}->{description};
> +		$desc =~ s/^\s+//;
> +
> +		# Remove title markups from the description, as they won't work
> +		$desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;
> +
> +		# put everything inside a code block
> +		$desc =~ s/\n/\n /g;
> +
> +
> +		if (!($desc =~ /^\s*$/)) {
> +			print " $desc\n\n";
> +		} else {
> +			print " DESCRIPTION MISSING\n\n";
> +		}
> +	}
> +}
> +
> +#
> +# Parses all ABI files located at $prefix dir
> +#
> +find({wanted =>\&parse_abi, no_chdir => 1}, $prefix);
> +
> +print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
> +
> +#
> +# Outputs an ReST file with the ABI contents
> +#
> +output_rest
> +
> +
> +__END__
> +
> +=head1 NAME
> +
> +abi_book.pl - parse the Linux ABI files and produce a ReST book.
> +
> +=head1 SYNOPSIS
> +
> +B<abi_book.pl> [--debug] <ABI_DIR>]
> +
> +=head1 OPTIONS
> +
> +=over 8
> +
> +=item B<--debug>
> +
> +Put the script in verbose mode, useful for debugging. Can be called multiple
> +times, to increase verbosity.
> +
> +=item B<--help>
> +
> +Prints a brief help message and exits.
> +
> +=item B<--man>
> +
> +Prints the manual page and exits.
> +
> +=back
> +
> +=head1 DESCRIPTION
> +
> +Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI)
> +and produce a ReST book containing the Linux ABI.
> +
> +=head1 BUGS
> +
> +Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
> +
> +=head1 COPYRIGHT
> +
> +Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
> +
> +License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
> +
> +This is free software: you are free to change and redistribute it.
> +There is NO WARRANTY, to the extent permitted by law.
> +
> +=cut

-- 
Jani Nikula, Intel Open Source Graphics Center

  reply	other threads:[~2019-06-14 13:29 UTC|newest]

Thread overview: 69+ 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 ` 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  2:04   ` Mauro Carvalho Chehab
2019-06-14  7:20   ` Andrew Donnellan
2019-06-14  7:20     ` Andrew Donnellan
2019-06-14 16:16     ` Greg Kroah-Hartman
2019-06-14 16:16       ` Greg Kroah-Hartman
2019-06-14  8:30   ` Rafael J. Wysocki
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 [this message]
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
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
2019-06-14 16:20   ` 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=87r27wuwc3.fsf@intel.com \
    --to=jani.nikula@linux.intel.com \
    --cc=corbet@lwn.net \
    --cc=gregkh@linuxfoundation.org \
    --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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.