Linux-Doc Archive on lore.kernel.org
 help / color / Atom feed
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
	"Jonathan Corbet" <corbet@lwn.net>,
	Jonathan Cameron <Jonathan.Cameron@huawei.com>,
	Oded Gabbay <oded.gabbay@gmail.com>, Tom Rix <trix@redhat.com>,
	Vaibhav Jain <vaibhav@linux.ibm.com>,
	linux-kernel@vger.kernel.org
Subject: [PATCH v2 05/39] scripts: get_abi.pl: cleanup ABI cross-reference logic
Date: Fri, 30 Oct 2020 08:40:24 +0100
Message-ID: <dbc97c8c2dfd877921f058134c35b2a8b1f8414b.1604042072.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1604042072.git.mchehab+huawei@kernel.org>

Right now, the cross-references are generated on a single
step, when doing ReST output.

While this is nice optimization, it prevents auto-creating
cross-references for ABI symbols.

So, split it into a separate logic.

While here, turn on Perl warnings, as it helps to debug
problems inside the script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 147 +++++++++++++++++++++++++--------------------
 1 file changed, 83 insertions(+), 64 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index bd018eb3815b..d134cc1692ee 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -2,15 +2,16 @@
 # SPDX-License-Identifier: GPL-2.0
 
 use strict;
+use warnings;
 use Pod::Usage;
 use Getopt::Long;
 use File::Find;
 use Fcntl ':mode';
 
-my $help;
-my $man;
-my $debug;
-my $enable_lineno;
+my $help = 0;
+my $man = 0;
+my $debug = 0;
+my $enable_lineno = 0;
 my $prefix="Documentation/ABI";
 
 #
@@ -40,6 +41,7 @@ pod2usage(2) if ($cmd eq "search" && !$arg);
 require Data::Dumper if ($debug);
 
 my %data;
+my %symbols;
 
 #
 # Displays an error message, printing file name and line
@@ -76,12 +78,12 @@ sub parse_abi {
 
 	my $what;
 	my $new_what;
-	my $tag;
+	my $tag = "";
 	my $ln;
 	my $xrefs;
 	my $space;
 	my @labels;
-	my $label;
+	my $label = "";
 
 	print STDERR "Opening $file\n" if ($debug > 1);
 	open IN, $file;
@@ -110,10 +112,18 @@ sub parse_abi {
 
 			if ($new_tag =~ m/what/) {
 				$space = "";
+				$content =~ s/[,.;]$//;
+
 				if ($tag =~ m/what/) {
 					$what .= ", " . $content;
 				} else {
-					parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description});
+					if ($what) {
+						parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
+
+						foreach my $w(split /, /, $what) {
+							$symbols{$w} = $what;
+						};
+					}
 
 					$what = $content;
 					$label = $content;
@@ -122,7 +132,7 @@ sub parse_abi {
 				push @labels, [($content, $label)];
 				$tag = $new_tag;
 
-				push @{$data{$nametag}->{xrefs}}, [($content, $label)] if ($data{$nametag}->{what});
+				push @{$data{$nametag}->{symbols}}, $content if ($data{$nametag}->{what});
 				next;
 			}
 
@@ -132,7 +142,7 @@ sub parse_abi {
 				$data{$what}->{line_no} = $ln;
 
 				if ($new_what) {
-					@{$data{$what}->{label}} = @labels if ($data{$nametag}->{what});
+					@{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what});
 					@labels = ();
 					$label = "";
 					$new_what = 0;
@@ -203,36 +213,24 @@ sub parse_abi {
 		# Everything else is error
 		parse_error($file, $ln, "Unexpected line:", $_);
 	}
-	$data{$nametag}->{description} =~ s/^\n+//;
+	$data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description});
+	if ($what) {
+		parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
+
+		foreach my $w(split /, /,$what) {
+			$symbols{$w} = $what;
+		};
+	}
 	close IN;
 }
 
-#
-# Outputs the book on ReST format
-#
+sub create_labels {
+	my %labels;
 
-my %labels;
+	foreach my $what (keys %data) {
+		next if ($data{$what}->{file} eq "File");
 
-sub output_rest {
-	foreach my $what (sort {
-				($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
-				$a cmp $b
-			       } keys %data) {
-		my $type = $data{$what}->{type};
-		my $file = $data{$what}->{file};
-		my $filepath = $data{$what}->{filepath};
-
-		if ($enable_lineno) {
-			printf "#define LINENO %s%s#%s\n\n",
-			       $prefix, $data{$what}->{file},
-			       $data{$what}->{line_no};
-		}
-
-		my $w = $what;
-		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
-
-
-		foreach my $p (@{$data{$what}->{label}}) {
+		foreach my $p (@{$data{$what}->{label_list}}) {
 			my ($content, $label) = @{$p};
 			$label = "abi_" . $label . " ";
 			$label =~ tr/A-Z/a-z/;
@@ -249,16 +247,39 @@ sub output_rest {
 			}
 			$labels{$label} = 1;
 
-			$data{$what}->{label} .= $label;
-
-			printf ".. _%s:\n\n", $label;
+			$data{$what}->{label} = $label;
 
 			# only one label is enough
 			last;
 		}
+	}
+}
 
+#
+# Outputs the book on ReST format
+#
 
-		$filepath =~ s,.*/(.*/.*),\1,;;
+sub output_rest {
+	create_labels();
+
+	foreach my $what (sort {
+				($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
+				$a cmp $b
+			       } keys %data) {
+		my $type = $data{$what}->{type};
+		my $file = $data{$what}->{file};
+		my $filepath = $data{$what}->{filepath};
+
+		if ($enable_lineno) {
+			printf "#define LINENO %s%s#%s\n\n",
+			       $prefix, $data{$what}->{file},
+			       $data{$what}->{line_no};
+		}
+
+		my $w = $what;
+		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+
+		$filepath =~ s,.*/(.*/.*),$1,;;
 		$filepath =~ s,[/\-],_,g;;
 		my $fileref = "abi_file_".$filepath;
 
@@ -269,8 +290,9 @@ sub output_rest {
 			print ".. _$fileref:\n\n";
 			print "$w\n$bar\n\n";
 		} else {
-			my @names = split /\s*,\s*/,$w;
+			printf ".. _%s:\n\n", $data{$what}->{label};
 
+			my @names = split /, /,$w;
 			my $len = 0;
 
 			foreach my $name (@names) {
@@ -284,12 +306,13 @@ sub output_rest {
 				printf "| %s", $name . " " x ($len - length($name)) . " |\n";
 				print "+-" . "-" x $len . "-+\n";
 			}
-			print "\n";
+
+			print "\nDefined on file :ref:`$file <$fileref>`\n\n";
 		}
 
-		print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File");
-
-		my $desc = $data{$what}->{description};
+		my $desc = "";
+		$desc = $data{$what}->{description} if (defined($data{$what}->{description}));
+		$desc =~ s/\s+$/\n/;
 
 		if (!($desc =~ /^\s*$/)) {
 			if ($description_is_rst) {
@@ -316,18 +339,11 @@ sub output_rest {
 			print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
 		}
 
-		if ($data{$what}->{xrefs}) {
+		if ($data{$what}->{symbols}) {
 			printf "Has the following ABI:\n\n";
 
-			foreach my $p(@{$data{$what}->{xrefs}}) {
-				my ($content, $label) = @{$p};
-				$label = "abi_" . $label . " ";
-				$label =~ tr/A-Z/a-z/;
-
-				# Convert special chars to "_"
-				$label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g;
-				$label =~ s,_+,_,g;
-				$label =~ s,_$,,;
+			foreach my $content(@{$data{$what}->{symbols}}) {
+				my $label = $data{$symbols{$content}}->{label};
 
 				# Escape special chars from content
 				$content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
@@ -355,17 +371,20 @@ sub search_symbols {
 
 		print "\n$what\n$bar\n\n";
 
-		my $kernelversion = $data{$what}->{kernelversion};
-		my $contact = $data{$what}->{contact};
-		my $users = $data{$what}->{users};
-		my $date = $data{$what}->{date};
-		my $desc = $data{$what}->{description};
-		$kernelversion =~ s/^\s+//;
-		$contact =~ s/^\s+//;
-		$users =~ s/^\s+//;
-		$users =~ s/\n//g;
-		$date =~ s/^\s+//;
-		$desc =~ s/^\s+//;
+		my $kernelversion = $data{$what}->{kernelversion} if (defined($data{$what}->{kernelversion}));
+		my $contact = $data{$what}->{contact} if (defined($data{$what}->{contact}));
+		my $users = $data{$what}->{users} if (defined($data{$what}->{users}));
+		my $date = $data{$what}->{date} if (defined($data{$what}->{date}));
+		my $desc = $data{$what}->{description} if (defined($data{$what}->{description}));
+
+		$kernelversion =~ s/^\s+// if ($kernelversion);
+		$contact =~ s/^\s+// if ($contact);
+		if ($users) {
+			$users =~ s/^\s+//;
+			$users =~ s/\n//g;
+		}
+		$date =~ s/^\s+// if ($date);
+		$desc =~ s/^\s+// if ($desc);
 
 		printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion);
 		printf "Date:\t\t\t%s\n", $date if ($date);
-- 
2.26.2


  parent reply index

Thread overview: 59+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-10-30  7:40 [PATCH v2 00/39] ABI: add it to the documentation build system Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 01/39] scripts: get_abi.pl: change script to allow parsing in ReST mode Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 02/39] scripts: get_abi.pl: fix parsing on " Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 03/39] scripts: get_abi.pl: Allow optionally record from where a line came from Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 04/39] scripts: get_abi.pl: improve its parser to better catch up indentation Mauro Carvalho Chehab
2020-10-30  7:40 ` Mauro Carvalho Chehab [this message]
2020-10-30  7:40 ` [PATCH v2 06/39] scripts: get_abi.pl: detect duplicated ABI definitions Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 07/39] scripts: get_abi.pl: output users in ReST format Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 08/39] scripts: get_abi.pl: prevent duplicated file names Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 09/39] scripts: get_abi.pl: use bold font for ABI definitions Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 10/39] scripts: get_abi.pl: auto-generate cross references Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 11/39] docs: kernellog.py: add support for info() Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 12/39] docs: kernel_abi.py: add a script to parse ABI documentation Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 13/39] docs: kernel_abi.py: fix UTF-8 support Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 14/39] docs: kernel_abi.py: make it compatible with Sphinx 1.7+ Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 15/39] docs: kernel_abi.py: use --enable-lineno for get_abi.pl Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 16/39] docs: kernel_abi.py: Handle with a lazy Sphinx parser Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 17/39] docs: add ABI documentation to the admin-guide book Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 18/39] docs: ABI: README: specify that files should be ReST compatible Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 19/39] docs: ABI: stable: make files " Mauro Carvalho Chehab
2020-10-30 10:04   ` Srinivas Kandagatla
2020-10-30  7:40 ` [PATCH v2 21/39] docs: ABI: sysfs-uevent: make it compatible with ReST output Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 22/39] docs: ABI: make it parse ABI/stable as ReST-compatible files Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 23/39] docs: ABI: create a 2-depth index for ABI Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 24/39] docs: ABI: don't escape ReST-incompatible chars from obsolete and removed Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 25/39] docs: abi-testing.rst: enable --rst-sources when building docs Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 26/39] docs: Kconfig/Makefile: add a check for broken ABI files Mauro Carvalho Chehab
2020-10-30 16:49   ` Randy Dunlap
2020-10-30  7:40 ` [PATCH v2 27/39] docs: ABI: convert testing/configfs-acpi to ReST Mauro Carvalho Chehab
2020-10-30 14:33   ` Rafael J. Wysocki
2020-10-30  7:40 ` [PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation Mauro Carvalho Chehab
2020-10-30 14:39   ` Rafael J. Wysocki
2020-11-02  5:50   ` Jinpu Wang
2020-11-02 18:39   ` Joseph, Jithu
2020-10-30  7:40 ` [PATCH v2 29/39] docs: ABI: vdso: use the right format for ABI Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 30/39] docs: ABI: sysfs-bus-nvdimm: " Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 32/39] docs: ABI: change read/write attributes Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 33/39] docs: ABI: stable: remove a duplicated documentation Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 34/39] docs: ABI: unify /sys/class/leds/<led>/brightness documentation Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 35/39] docs: ABI: sysfs-class-power: unify duplicated properties Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 36/39] docs: ABI: sysfs-c2port: remove a duplicated entry Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 37/39] docs: ABI: sysfs-class-backlight: unify ABI documentation Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 38/39] docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern duplication Mauro Carvalho Chehab
2020-10-30  7:40 ` [PATCH v2 39/39] scripts: get_abi.pl: assume ReST format by default Mauro Carvalho Chehab
     [not found] ` <58cf3c2d611e0197fb215652719ebd82ca2658db.1604042072.git.mchehab+huawei@kernel.org>
     [not found]   ` <5326488b-4185-9d67-fc09-79b911fbb3b8@st.com>
2020-10-30 10:09     ` [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output Mauro Carvalho Chehab
2020-11-02 11:04       ` Fabrice Gasnier
2020-11-02 12:46         ` Greg Kroah-Hartman
2020-11-02 14:42           ` Mauro Carvalho Chehab
2020-11-08 16:56             ` Jonathan Cameron
2020-11-10  7:26               ` Duplicated ABI entries - Was: " Mauro Carvalho Chehab
2020-11-10 18:18                 ` Randy Dunlap
2020-11-14 15:27                 ` Jonathan Cameron
2020-10-30 17:26   ` Frederic Barrat
     [not found] ` <5bc78e5b68ed1e9e39135173857cb2e753be868f.1604042072.git.mchehab+huawei@kernel.org>
2020-10-30  8:27   ` [PATCH v2 31/39] docs: ABI: cleanup several ABI documents Rojewski, Cezary
2020-10-30  9:49   ` Suzuki K Poulose
2020-10-30 11:11   ` Ilya Dryomov
2020-10-30 16:42   ` Mathieu Poirier
2020-10-30 23:23   ` Peter Chen
2020-11-01  3:43   ` Dmitry Torokhov

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=dbc97c8c2dfd877921f058134c35b2a8b1f8414b.1604042072.git.mchehab+huawei@kernel.org \
    --to=mchehab+huawei@kernel.org \
    --cc=Jonathan.Cameron@huawei.com \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=oded.gabbay@gmail.com \
    --cc=trix@redhat.com \
    --cc=vaibhav@linux.ibm.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

Linux-Doc Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-doc/0 linux-doc/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-doc linux-doc/ https://lore.kernel.org/linux-doc \
		linux-doc@vger.kernel.org
	public-inbox-index linux-doc

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-doc


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git