From nobody Sat Oct 4 00:28:07 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E12DC3126CD; Fri, 22 Aug 2025 14:19:48 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755872389; cv=none; b=Idi4tgqZ7Y3F/9hSiR/eJBUJPZb35fB/5p+B3Fj+Auf2hzCeVVrKiDUTIKDGeYIAn8YKP8FclGxqlbj9JtjLD4jl+yZj2dp/T25VPSrhD3Ggny35qLM/VJYqol1YjdRKo5Tyi5H/0uQcwvwjt3YrUVPzpjRhslIU5/HEHJrElkQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755872389; c=relaxed/simple; bh=uYEK1a2ZG5UzKHVraa8W5O9cCQbPaE3FbRWgQy8mxrI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=rCaj+iN0QfPMhZ4849L+ww/iw6pn3b02uFqvTFWWwew1OtStAEa9iqNn/+tPCmJbaB9h1PdJ66QS2HAh/sfCVTrfsTKZnlzEy//aXNtOpy6KFLIHoJ2h3SiGYWproRI2zcqDqAVU8fLVGRn1PrVw4fswEmGR3Gq8EukxCgplC5k= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=qGZs/DgR; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="qGZs/DgR" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 78C2DC2BD04; Fri, 22 Aug 2025 14:19:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1755872388; bh=uYEK1a2ZG5UzKHVraa8W5O9cCQbPaE3FbRWgQy8mxrI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=qGZs/DgRijv4sIpLfNua2KZwa1zOMTA7P3w+cQVGGajf4ePoCF30BlJh1vhH8eIPR G3EyOqQNqNhqQ6e721FeC0TmBJ7Ak5fVk7VM6MAP389PMiBDDU4bMjGtbhWvw/Y/bO XFARAthbCttu1p0FXd6W9aY3hktqnrJn67ZhNu9tCv20uVosxZmtHNcDyaKfdbtZff Zi+z+5Sh5UhoO/4JN1BykDUX1KyAighzDEkoDK9Zws19AcsbGhFIF4tjY4L4nUc76z T1eqOEehoua09rO56k+Z7Ipz/bBmP4jTXlFUcyYqjnruEzSw3zIXRVdBhztcVmNyQw zdkxEmsnCteDg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1upScM-0000000CCsS-36wv; Fri, 22 Aug 2025 16:19:46 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v2 24/24] docs: sphinx: drop parse-headers.pl Date: Fri, 22 Aug 2025 16:19:36 +0200 Message-ID: X-Mailer: git-send-email 2.50.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that we have a replacement in place, drop the old version. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/parse-headers.pl | 419 -------------------------- 1 file changed, 419 deletions(-) delete mode 100755 Documentation/sphinx/parse-headers.pl diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/p= arse-headers.pl deleted file mode 100755 index 560685926cdb..000000000000 --- a/Documentation/sphinx/parse-headers.pl +++ /dev/null @@ -1,419 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0 -# Copyright (c) 2016 by Mauro Carvalho Chehab . - -use strict; -use Text::Tabs; -use Getopt::Long; -use Pod::Usage; - -my $debug; -my $help; -my $man; - -GetOptions( - "debug" =3D> \$debug, - 'usage|?' =3D> \$help, - 'help' =3D> \$man -) or pod2usage(2); - -pod2usage(1) if $help; -pod2usage(-exitstatus =3D> 0, -verbose =3D> 2) if $man; -pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3); - -my ($file_in, $file_out, $file_exceptions) =3D @ARGV; - -my $data; -my %ioctls; -my %defines; -my %typedefs; -my %enums; -my %enum_symbols; -my %structs; - -# -# read the file and get identifiers -# - -my $is_enum =3D 0; -my $is_comment =3D 0; -open IN, $file_in or die "Can't open $file_in"; -while () { - $data .=3D $_; - - my $ln =3D $_; - if (!$is_comment) { - $ln =3D~ s,/\*.*(\*/),,g; - - $is_comment =3D 1 if ($ln =3D~ s,/\*.*,,); - } else { - if ($ln =3D~ s,^(.*\*/),,) { - $is_comment =3D 0; - } else { - next; - } - } - - if ($is_enum && $ln =3D~ m/^\s*([_\w][\w\d_]+)\s*[\,=3D]?/) { - my $s =3D $1; - my $n =3D $1; - $n =3D~ tr/A-Z/a-z/; - $n =3D~ tr/_/-/; - - $enum_symbols{$s} =3D "\\ :ref:`$s <$n>`\\ "; - - $is_enum =3D 0 if ($is_enum && m/\}/); - next; - } - $is_enum =3D 0 if ($is_enum && m/\}/); - - if ($ln =3D~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+_IO/) { - my $s =3D $1; - my $n =3D $1; - $n =3D~ tr/A-Z/a-z/; - - $ioctls{$s} =3D "\\ :ref:`$s <$n>`\\ "; - next; - } - - if ($ln =3D~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+/) { - my $s =3D $1; - my $n =3D $1; - $n =3D~ tr/A-Z/a-z/; - $n =3D~ tr/_/-/; - - $defines{$s} =3D "\\ :ref:`$s <$n>`\\ "; - next; - } - - if ($ln =3D~ m/^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);/) { - my $s =3D $2; - my $n =3D $3; - - $typedefs{$n} =3D "\\ :c:type:`$n <$s>`\\ "; - next; - } - if ($ln =3D~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/ - || $ln =3D~ m/^\s*enum\s+([_\w][\w\d_]+)$/ - || $ln =3D~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/ - || $ln =3D~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) { - my $s =3D $1; - - $enums{$s} =3D "enum :c:type:`$s`\\ "; - - $is_enum =3D $1; - next; - } - if ($ln =3D~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/ - || $ln =3D~ m/^\s*struct\s+([[_\w][\w\d_]+)$/ - || $ln =3D~ m/^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s+\{/ - || $ln =3D~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/ - ) { - my $s =3D $1; - - $structs{$s} =3D "struct $s\\ "; - next; - } -} -close IN; - -# -# Handle multi-line typedefs -# - -my @matches =3D ($data =3D~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)= \s*\;/g, - $data =3D~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,); -foreach my $m (@matches) { - my $s =3D $m; - - $typedefs{$s} =3D "\\ :c:type:`$s`\\ "; - next; -} - -# -# Handle exceptions, if any -# - -my %def_reftype =3D ( - "ioctl" =3D> ":ref", - "define" =3D> ":ref", - "symbol" =3D> ":ref", - "typedef" =3D> ":c:type", - "enum" =3D> ":c:type", - "struct" =3D> ":c:type", -); - -if ($file_exceptions) { - open IN, $file_exceptions or die "Can't read $file_exceptions"; - while () { - next if (m/^\s*$/ || m/^\s*#/); - - # Parsers to ignore a symbol - - if (m/^ignore\s+ioctl\s+(\S+)/) { - delete $ioctls{$1} if (exists($ioctls{$1})); - next; - } - if (m/^ignore\s+define\s+(\S+)/) { - delete $defines{$1} if (exists($defines{$1})); - next; - } - if (m/^ignore\s+typedef\s+(\S+)/) { - delete $typedefs{$1} if (exists($typedefs{$1})); - next; - } - if (m/^ignore\s+enum\s+(\S+)/) { - delete $enums{$1} if (exists($enums{$1})); - next; - } - if (m/^ignore\s+struct\s+(\S+)/) { - delete $structs{$1} if (exists($structs{$1})); - next; - } - if (m/^ignore\s+symbol\s+(\S+)/) { - delete $enum_symbols{$1} if (exists($enum_symbols{$1})); - next; - } - - # Parsers to replace a symbol - my ($type, $old, $new, $reftype); - - if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) { - $type =3D $1; - $old =3D $2; - $new =3D $3; - } else { - die "Can't parse $file_exceptions: $_"; - } - - if ($new =3D~ m/^\:c\:(data|func|macro|type)\:\`(.+)\`/) { - $reftype =3D ":c:$1"; - $new =3D $2; - } elsif ($new =3D~ m/\:ref\:\`(.+)\`/) { - $reftype =3D ":ref"; - $new =3D $1; - } else { - $reftype =3D $def_reftype{$type}; - } - if (!$reftype) { - print STDERR "Warning: can't find ref type for $type"; - } - $new =3D "$reftype:`$old <$new>`"; - - if ($type eq "ioctl") { - $ioctls{$old} =3D $new if (exists($ioctls{$old})); - next; - } - if ($type eq "define") { - $defines{$old} =3D $new if (exists($defines{$old})); - next; - } - if ($type eq "symbol") { - $enum_symbols{$old} =3D $new if (exists($enum_symbols{$old})); - next; - } - if ($type eq "typedef") { - $typedefs{$old} =3D $new if (exists($typedefs{$old})); - next; - } - if ($type eq "enum") { - $enums{$old} =3D $new if (exists($enums{$old})); - next; - } - if ($type eq "struct") { - $structs{$old} =3D $new if (exists($structs{$old})); - next; - } - - die "Can't parse $file_exceptions: $_"; - } -} - -if ($debug) { - my @all_hashes =3D ( - {ioctl =3D> \%ioctls}, - {typedef =3D> \%typedefs}, - {enum =3D> \%enums}, - {struct =3D> \%structs}, - {define =3D> \%defines}, - {symbol =3D> \%enum_symbols} - ); - - foreach my $hash (@all_hashes) { - while (my ($name, $hash_ref) =3D each %$hash) { - next unless %$hash_ref; # Skip empty hashes - - print "$name:\n"; - for my $key (sort keys %$hash_ref) { - print " $key -> $hash_ref->{$key}\n"; - } - print "\n"; - } - } -} - -# -# Align block -# -$data =3D expand($data); -$data =3D " " . $data; -$data =3D~ s/\n/\n /g; -$data =3D~ s/\n\s+$/\n/g; -$data =3D~ s/\n\s+\n/\n\n/g; - -# -# Add escape codes for special characters -# -$data =3D~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g; - -$data =3D~ s,DEPRECATED,**DEPRECATED**,g; - -# -# Add references -# - -my $start_delim =3D "[ \n\t\(\=3D\*\@]"; -my $end_delim =3D "(\\s|,|\\\\=3D|\\\\:|\\;|\\\)|\\}|\\{)"; - -foreach my $r (keys %ioctls) { - my $s =3D $ioctls{$r}; - - $r =3D~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =3D~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %defines) { - my $s =3D $defines{$r}; - - $r =3D~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =3D~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %enum_symbols) { - my $s =3D $enum_symbols{$r}; - - $r =3D~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =3D~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %enums) { - my $s =3D $enums{$r}; - - $r =3D~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =3D~ s/enum\s+($r)$end_delim/$s$2/g; -} - -foreach my $r (keys %structs) { - my $s =3D $structs{$r}; - - $r =3D~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =3D~ s/struct\s+($r)$end_delim/$s$2/g; -} - -foreach my $r (keys %typedefs) { - my $s =3D $typedefs{$r}; - - $r =3D~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - $data =3D~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -$data =3D~ s/\\ ([\n\s])/\1/g; - -# -# Generate output file -# - -my $title =3D $file_in; -$title =3D~ s,.*/,,; - -open OUT, "> $file_out" or die "Can't open $file_out"; -print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n"; -print OUT "$title\n"; -print OUT "=3D" x length($title); -print OUT "\n\n.. parsed-literal::\n\n"; -print OUT $data; -close OUT; - -__END__ - -=3Dhead1 NAME - -parse_headers.pl - parse a C file, in order to identify functions, structs, -enums and defines and create cross-references to a Sphinx book. - -=3Dhead1 SYNOPSIS - -B [] [] - -Where can be: --debug, --help or --usage. - -=3Dhead1 OPTIONS - -=3Dover 8 - -=3Ditem B<--debug> - -Put the script in verbose mode, useful for debugging. - -=3Ditem B<--usage> - -Prints a brief help message and exits. - -=3Ditem B<--help> - -Prints a more detailed help message and exits. - -=3Dback - -=3Dhead1 DESCRIPTION - -Convert a C header or source file (C_FILE), into a ReStructured Text -included via ..parsed-literal block with cross-references for the -documentation files that describe the API. It accepts an optional -EXCEPTIONS_FILE with describes what elements will be either ignored or -be pointed to a non-default reference. - -The output is written at the (OUT_FILE). - -It is capable of identifying defines, functions, structs, typedefs, -enums and enum symbols and create cross-references for all of them. -It is also capable of distinguish #define used for specifying a Linux -ioctl. - -The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or -to replace the default references by a custom one. - -Please read Documentation/doc-guide/parse-headers.rst at the Kernel's -tree for more details. - -=3Dhead1 BUGS - -Report bugs to Mauro Carvalho Chehab - -=3Dhead1 COPYRIGHT - -Copyright (c) 2016 by Mauro Carvalho Chehab . - -License GPLv2: GNU GPL version 2 . - -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -=3Dcut --=20 2.50.1