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 <mchehab@xxxxxxxxxxxxxxxx> --- Documentation/doc-guide/parse-headers.rst | 14 ---- Documentation/sphinx/parse-headers.pl | 106 ++---------------------------- 2 files changed, 4 insertions(+), 116 deletions(-) diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index 615e25ec64bb..98a0dcf9b19e 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/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 ******* @@ -68,7 +59,6 @@ OPTIONS -*********** DESCRIPTION *********** @@ -155,8 +145,6 @@ For both statements, \ **type**\ can be either one of the following: - -******** EXAMPLES ******** @@ -187,7 +175,6 @@ It will make the BAR1 and BAR2 enum symbols to cross reference the foo symbol at the C domain. -**** BUGS **** @@ -195,7 +182,6 @@ BUGS Report bugs to Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> -********* COPYRIGHT ********* diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index 20dbdf55c71e..8d7052424db8 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -379,109 +379,11 @@ 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 types of statements: B<ignore> or B<replace>. +The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or +to replace the default references by a custom one. -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. - -=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 -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
