Step 6) Translate the "Output format selection modifier" subsection
of OPTIONS
This section is renamed to "Output format modifiers" to make it simple.
To make it even more simple, a subsection is added:
"reStructuredText only".
Other notes:
- paragraphing correction
- article correction
See step 1 for the series details.
Signed-off-by: Tomasz Warniełło <[email protected]>
---
scripts/kernel-doc | 22 +++++++++++++++-------
1 file changed, 15 insertions(+), 7 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 896c4775102d..d1a4d98726b3 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,13 +83,6 @@ sub usage {
my $message = <<"EOF";
Usage: $0 [OPTION ...] FILE ...
-Output format selection modifier (affects only ReST output):
-
- -sphinx-version Use the ReST C domain dialect compatible with an
- specific Sphinx Version.
- If not specified, kernel-doc will auto-detect using
- the sphinx-build version found on PATH.
-
Output selection (mutually exclusive):
-export Only output documentation for symbols that have been
exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
@@ -2583,4 +2576,19 @@ Do not output documentation, only warnings.
=back
+=head2 Output format modifiers
+
+=head3 reStructuredText only
+
+=over 8
+
+=item -sphinx-version VERSION
+
+Use the ReST C domain dialect compatible with a specific Sphinx Version.
+
+If not specified, kernel-doc will auto-detect using the sphinx-build version
+found on PATH.
+
+=back
+
=cut
--
2.30.2
Step 7) Translate the "Output selection" subsection of OPTIONS
The plurals in -function and -nosymbol are corrected to singulars.
That's how the script works now. I think this describes the syntax better.
The plurar suggests multiple FILE arguments might be possible. So this
seems more coherent.
Other notes:
- paragraphing correction
- article correction
See step 1 for the series details.
Signed-off-by: Tomasz Warniełło <[email protected]>
---
scripts/kernel-doc | 42 +++++++++++++++++++++++++++++-------------
1 file changed, 29 insertions(+), 13 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d1a4d98726b3..7d95213c11b8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,19 +83,6 @@ sub usage {
my $message = <<"EOF";
Usage: $0 [OPTION ...] FILE ...
-Output selection (mutually exclusive):
- -export Only output documentation for symbols that have been
- exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
- in any input FILE or -export-file FILE.
- -internal Only output documentation for symbols that have NOT been
- exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
- in any input FILE or -export-file FILE.
- -function NAME Only output documentation for the given function(s)
- or DOC: section title(s). All other functions and DOC:
- sections are ignored. May be specified multiple times.
- -nosymbol NAME Exclude the specified symbols from the output
- documentation. May be specified multiple times.
-
Output selection modifiers:
-no-doc-sections Do not output DOC: sections.
-enable-lineno Enable output of #define LINENO lines. Only works with
@@ -2591,4 +2578,33 @@ found on PATH.
=back
+=head2 Output selection (mutually exclusive):
+
+=over 8
+
+=item -export
+
+Only output documentation for the symbols that have been exported using
+EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
+
+=item -internal
+
+Only output documentation for the symbols that have NOT been exported using
+EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
+
+=item -function NAME
+
+Only output documentation for the given function or DOC: section title.
+All other functions and DOC: sections are ignored.
+
+May be specified multiple times.
+
+=item -nosymbol NAME
+
+Exclude the specified symbol from the output documentation.
+
+May be specified multiple times.
+
+=back
+
=cut
--
2.30.2
Step 9) Translate the "Other parameters" subsection of OPTIONS
Notes:
- The -help token is added.
- The entries are sorted alphbetically.
See step 1 for the series details.
Signed-off-by: Tomasz Warniełło <[email protected]>
---
scripts/kernel-doc | 23 ++++++++++++++++++-----
1 file changed, 18 insertions(+), 5 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fa1270272b3c..76018ca81594 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,11 +83,6 @@ sub usage {
my $message = <<"EOF";
Usage: $0 [OPTION ...] FILE ...
-Other parameters:
- -v Verbose output, more warnings and other information.
- -h Print this help.
- -Werror Treat warnings as errors.
-
EOF
print $message;
exit 1;
@@ -2628,4 +2623,22 @@ Enable output of #define LINENO lines.
=back
+=head2 Other parameters:
+
+=over 8
+
+=item -h, -help
+
+Print this help.
+
+=item -v
+
+Verbose output, more warnings and other information.
+
+=item -Werror
+
+Treat warnings as errors.
+
+=back
+
=cut
--
2.30.2
Step 8) Translate the "Output selection modifiers" subsection of OPTIONS
A subsection "reStructuredText only" is added for -enable-lineno.
Other notes:
- paragraphing correction
See step 1 for the series details.
Signed-off-by: Tomasz Warniełło <[email protected]>
---
scripts/kernel-doc | 37 +++++++++++++++++++++++++++++--------
1 file changed, 29 insertions(+), 8 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 7d95213c11b8..fa1270272b3c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,14 +83,6 @@ sub usage {
my $message = <<"EOF";
Usage: $0 [OPTION ...] FILE ...
-Output selection modifiers:
- -no-doc-sections Do not output DOC: sections.
- -enable-lineno Enable output of #define LINENO lines. Only works with
- reStructuredText format.
- -export-file FILE Specify an additional FILE in which to look for
- EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
- -export or -internal. May be specified multiple times.
-
Other parameters:
-v Verbose output, more warnings and other information.
-h Print this help.
@@ -2607,4 +2599,33 @@ May be specified multiple times.
=back
+=head2 Output selection modifiers:
+
+=over 8
+
+=item -no-doc-sections
+
+Do not output DOC: sections.
+
+=item -export-file FILE
+
+Specify an additional FILE in which to look for EXPORT_SYMBOL() and
+EXPORT_SYMBOL_GPL().
+
+To be used with -export or -internal.
+
+May be specified multiple times.
+
+=back
+
+=head3 reStructuredText only
+
+=over 8
+
+=item -enable-lineno
+
+Enable output of #define LINENO lines.
+
+=back
+
=cut
--
2.30.2
Step 10) Replace the usage function
This ends the fundamental POD transformation.
You can see the results with:
$ scripts/kernel-doc -help
See step 1 for the series details.
Signed-off-by: Tomasz Warniełło <[email protected]>
---
scripts/kernel-doc | 11 +----------
1 file changed, 1 insertion(+), 10 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 76018ca81594..bf0c5bb7b026 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -79,15 +79,6 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
# 25/07/2012 - Added support for HTML5
# -- Dan Luedtke <[email protected]>
-sub usage {
- my $message = <<"EOF";
-Usage: $0 [OPTION ...] FILE ...
-
-EOF
- print $message;
- exit 1;
-}
-
#
# format of comments.
# In the following table, (...)? signifies optional structure.
@@ -468,7 +459,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
} elsif ($cmd eq "Werror") {
$Werror = 1;
} elsif (($cmd eq "h") || ($cmd eq "help")) {
- usage();
+ pod2usage(-exitval => 0, -verbose => 2);
} elsif ($cmd eq 'no-doc-sections') {
$no_doc_sections = 1;
} elsif ($cmd eq 'enable-lineno') {
--
2.30.2