docs-rst: parse-headers.pl: cleanup the documentation

Keeping both rst and in-file documentation in sync can be harsh.

So, simplify the script's internal documntation to a bare minimum,
and add a mention to the ReST file with its full documentation.

This way, a quick help is still available at the command line,
while the complete one is maintained at the ReST format.

As we won't be using pad2rst anymore, do a cleanup at the ReST
file.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

Documentation/doc-guide/parse-headers.rst

@@ -18,13 +18,6 @@ about how to use it inside the Kernel tree.
 parse_headers.pl
 ^^^^^^^^^^^^^^^^
 
-.. NOTE: the man pages below were generated using pod2rst tool:
-.. http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst
-.. If you need to change anything below this point, please do the changes
-.. at parse-headers.pl directly, re-run the script and paste the output of
-.. the script here.
-
-****
 NAME
 ****
 
@@ -33,7 +26,6 @@ parse_headers.pl - parse a C file, in order to identify functions, structs,
 enums and defines and create cross-references to a Sphinx book.
 
 
-********
 SYNOPSIS
 ********
 
@@ -43,7 +35,6 @@ SYNOPSIS
 Where <options> can be: --debug, --help or --man.
 
 
-*******
 OPTIONS
 *******
 
@@ -55,20 +46,17 @@ OPTIONS
 
 
 
-\ **--help**\
+\ **--usage**\
 
  Prints a brief help message and exits.
 
 
 
-\ **--man**\
-
- Prints the manual page and exits.
-
+\ **--help**\
 
+ Prints a more detailed help message and exits.
 
 
-***********
 DESCRIPTION
 ***********
 
@@ -155,8 +143,6 @@ For both statements, \ **type**\  can be either one of the following:
 
 
 
-
-********
 EXAMPLES
 ********
 
@@ -187,15 +173,13 @@ It will make the BAR1 and BAR2 enum symbols to cross reference the foo
 symbol at the C domain.
 
 
-****
 BUGS
 ****
 
 
 Report bugs to Mauro Carvalho Chehab <[email protected]>
 
 
-*********
 COPYRIGHT
 *********
 

Documentation/sphinx/parse-headers.pl

@@ -10,8 +10,8 @@
 
 GetOptions(
 	"debug" => \$debug,
-	'help|?' => \$help,
-	man => \$man
+	'usage|?' => \$help,
+	'help' => \$man
 ) or pod2usage(2);
 
 pod2usage(1) if $help;
@@ -354,13 +354,13 @@ =head1 OPTIONS
 
 Put the script in verbose mode, useful for debugging.
 
-=item B<--help>
+=item B<--usage>
 
 Prints a brief help message and exits.
 
-=item B<--man>
+=item B<--help>
 
-Prints the manual page and exits.
+Prints a more detailed help message and exits.
 
 =back
 
@@ -379,109 +379,11 @@ =head1 DESCRIPTION
 It is also capable of distinguish #define used for specifying a Linux
 ioctl.
 
-The EXCEPTIONS_FILE contain two types of statements: B<ignore> or B<replace>.
-
-The syntax for the ignore tag is:
-
-=over 8
-
-ignore B<type> B<name>
-
-=back
-
-The B<ignore> means that it won't generate cross references for a
-B<name> symbol of type B<type>.
-
-The syntax for the replace tag is:
-
-=over 8
-
-replace B<type> B<name> B<new_value>
-
-=back
-
-The B<replace> means that it will generate cross references for a
-B<name> symbol of type B<type>, but, instead of using the default
-replacement rule, it will use B<new_value>.
-
-For both statements, B<type> can be either one of the following:
-
-=over 8
-
-=item B<ioctl>
-
-The ignore or replace statement will apply to ioctl definitions like:
-
-#define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)
-
-=item B<define>
-
-The ignore or replace statement will apply to any other #define found
-at C_FILE.
-
-=item B<typedef>
-
-The ignore or replace statement will apply to typedef statements at C_FILE.
-
-=item B<struct>
-
-The ignore or replace statement will apply to the name of struct statements
-at C_FILE.
-
-=item B<enum>
-
-The ignore or replace statement will apply to the name of enum statements
-at C_FILE.
+The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or
+to replace the default references by a custom one.
 
-=item B<symbol>
-
-The ignore or replace statement will apply to the name of enum statements
-at C_FILE.
-
-
-For replace statements, B<new_value> will automatically use :c:type:
-references for B<typedef>, B<enum> and B<struct> types. It will use :ref:
-for B<ioctl>, B<define> and B<symbol> types. The type of reference can
-also be explicitly defined at the replace statement.
-
-=back
-
-=head1 EXAMPLES
-
-ignore define _VIDEODEV2_H
-
-=over 8
-
-
-Ignore a #define _VIDEODEV2_H at the C_FILE.
-
-=back
-
-ignore symbol PRIVATE
-
-=over 8
-
-On a struct like:
-
-enum foo { BAR1, BAR2, PRIVATE };
-
-It won't generate cross-references for B<PRIVATE>.
-
-=back
-
-replace symbol BAR1 :c:type:`foo`
-replace symbol BAR2 :c:type:`foo`
-
-=over 8
-
-On a struct like:
-
-enum foo { BAR1, BAR2, PRIVATE };
-
-It will make the BAR1 and BAR2 enum symbols to cross reference the foo
-symbol at the C domain.
-
-=back
+Please read Documentation/doc-guide/parse-headers.rst at the Kernel's
+tree for more details.
 
 =head1 BUGS