This series transforms the free-form general comments - mainly the usage
instructions and the meta information - into the standard Perl
documentation format. Some of the original text is reduced out. And some
is simply dropped.
The transformation includes language, paragraphing and editorial
corrections.
The only change in the script execution flow is the replacement of the
'usage' function with the native standard Perl 'pod2usage'.
The to-do suggestion to write POD found in the script is ancient, thus
I can't address its author with a "Suggested-by" tag.
This version follows the advice received on v3, except I'm leaving
the old copyrights untouched.
The process consists of 14 steps.
Patches beginning with no 3 are disfunctional until no 9 has been
applied.
1) Add the basic POD sections
2) Relink argument parsing error handling to pod2usage
The following subseries is disfunctional before its last part.
3) Translate the DESCRIPTION section
4) Translate the "Output format selection" subsection of OPTIONS
5) Translate the "Output format selection modifier" subsection of OPTIONS
6) Translate the "Output selection" subsection of OPTIONS
7) Translate the "Output selection modifiers" subsection of OPTIONS
8) Translate the "Other parameters" subsection of OPTIONS
9) Replace the usage function
Here the DESCRIPTION and OPTIONS subseries is finished. The -h and -help
parameters are handled by POD now.
10) Drop obsolete comments
11) Refresh the copyright lines
Let's see what's wrong this time.
Tomasz Warniełło (11):
scripts: kernel-doc: Add the basic POD sections
scripts: kernel-doc: Relink argument parsing error handling to
pod2usage
scripts: kernel-doc: Translate the DESCRIPTION section
scripts: kernel-doc: Translate the "Output format selection"
subsection of OPTIONS
scripts: kernel-doc: Translate the "Output format selection modifier"
subsection of OPTIONS
scripts: kernel-doc: Translate the "Output selection" subsection of
OPTIONS
scripts: kernel-doc: Translate the "Output selection modifiers"
subsection of OPTIONS
scripts: kernel-doc: Translate the "Other parameters" subsection of
OPTIONS
scripts: kernel-doc: Replace the usage function
scripts: kernel-doc: Drop obsolete comments
scripts: kernel-doc: Refresh the copyright lines
scripts/kernel-doc | 347 +++++++++++++++++++++------------------------
1 file changed, 159 insertions(+), 188 deletions(-)
base-commit: 2a987e65025e2b79c6d453b78cb5985ac6e5eb26
--
2.30.2
The former usage function is substituted, although not as the -h and -help
parameter handler yet.
Purpose: Use Pod::Usage to handle documentation printing in an integrated
way.
Signed-off-by: Tomasz Warniełło <[email protected]>
---
If the indentation is still wrong, please state, what you expect exactly.
To me the style in the script is random or eclectic.
---
scripts/kernel-doc | 20 +++++++++++++++++---
1 file changed, 17 insertions(+), 3 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c8fbf1d3d5aa..e7f7251771bb 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -16,6 +16,8 @@ use strict;
## This software falls under the GNU General Public License. ##
## Please read the COPYING file for more information ##
+use Pod::Usage qw/pod2usage/;
+
=head1 NAME
kernel-doc - Print formatted kernel documentation to stdout
@@ -298,7 +300,13 @@ my $blankline_rst = "\n";
# read arguments
if ($#ARGV == -1) {
- usage();
+ pod2usage(
+ -message => "No arguments!\n",
+ -exitval => 1,
+ -verbose => 99,
+ -sections => 'SYNOPSIS',
+ -output => \*STDERR,
+ );
}
my $kernelversion;
@@ -518,8 +526,14 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
die "Sphinx version should either major.minor or major.minor.patch format\n";
}
} else {
- # Unknown argument
- usage();
+ # Unknown argument
+ pod2usage(
+ -message => "Argument unknown!\n",
+ -exitval => 1,
+ -verbose => 99,
+ -sections => 'SYNOPSIS',
+ -output => \*STDERR,
+ );
}
}
--
2.30.2
I wanted to clean up these lines, but in the end decided not to touch
the old ones and just add my own about POD. I'll leave the cleanup
for lawyers.
Signed-off-by: Tomasz Warniełło <[email protected]>
---
Still credits go to Jonathat Corbet for alerting me when I moved them to
POD in version 1.
---
scripts/kernel-doc | 2 ++
1 file changed, 2 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a5a397e22ea7..f06f68f3c3d9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -12,6 +12,8 @@ use strict;
## ##
## #define enhancements by Armin Kuster <[email protected]> ##
## Copyright (c) 2000 MontaVista Software, Inc. ##
+#
+# Copyright (C) 2022 Tomasz Warniełło (POD)
use Pod::Usage qw/pod2usage/;
--
2.30.2
Aim: unified POD, user more satisfied, script better structured
Notes:
- The -help token is added.
- The entries are sorted alphbetically.
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 210e7e3b501b..4a26a74318e6 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
The NAME section provides the doc title, while SYNOPSIS contains
the basic syntax and usage description, which will be printed
in the help document and in the error output produced on wrong script
usage.
The rationale is to give users simple and succinct enlightment,
at the same time structuring the script internally for the maintainers.
In the synopsis, Rst-only options are grouped around rst, and the rest is
arranged as in the OPTIONS subsections (yet to be translated into POD,
check at the end of the series).
The third of the basic sections, DESCRIPTION, is added separately.
Signed-off-by: Tomasz Warniełło <[email protected]>
---
scripts/kernel-doc | 25 +++++++++++++++++++++++++
1 file changed, 25 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3106b7536b89..c8fbf1d3d5aa 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -16,6 +16,31 @@ use strict;
## This software falls under the GNU General Public License. ##
## Please read the COPYING file for more information ##
+=head1 NAME
+
+kernel-doc - Print formatted kernel documentation to stdout
+
+=head1 SYNOPSIS
+
+ kernel-doc [-h] [-v] [-Werror]
+ [ -man |
+ -rst [-sphinx-version VERSION] [-enable-lineno] |
+ -none
+ ]
+ [
+ -export |
+ -internal |
+ [-function NAME] ... |
+ [-nosymbol NAME] ...
+ ]
+ [-no-doc-sections]
+ [-export-file FILE] ...
+ FILE ...
+
+Run `kernel-doc -h` for details.
+
+=cut
+
# 18/01/2001 - Cleanups
# Functions prototyped as foo(void) same as foo()
# Stop eval'ing where we don't need to.
--
2.30.2
Aim: unified POD, user more satisfied, script better structured
You can see the results with:
$ scripts/kernel-doc -help
Signed-off-by: Tomasz Warniełło <[email protected]>
---
This ends the fundamental POD transformation.
---
scripts/kernel-doc | 11 +----------
1 file changed, 1 insertion(+), 10 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 4a26a74318e6..d7ca4877eeda 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
Aim: unified POD, user more satisfied, script better structured
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
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 b926faa16b00..e49cdb307a35 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
Hi Tomasz,
On 2/18/22 10:16, Tomasz Warniełło wrote:
> This series transforms the free-form general comments - mainly the usage
> instructions and the meta information - into the standard Perl
> documentation format. Some of the original text is reduced out. And some
> is simply dropped.
>
> The transformation includes language, paragraphing and editorial
> corrections.
>
> The only change in the script execution flow is the replacement of the
> 'usage' function with the native standard Perl 'pod2usage'.
>
> The to-do suggestion to write POD found in the script is ancient, thus
> I can't address its author with a "Suggested-by" tag.
>
> This version follows the advice received on v3, except I'm leaving
> the old copyrights untouched.
>
> The process consists of 14 steps.
>
> Patches beginning with no 3 are disfunctional until no 9 has been
> applied.
>
> 1) Add the basic POD sections
> 2) Relink argument parsing error handling to pod2usage
>
> The following subseries is disfunctional before its last part.
>
> 3) Translate the DESCRIPTION section
> 4) Translate the "Output format selection" subsection of OPTIONS
> 5) Translate the "Output format selection modifier" subsection of OPTIONS
> 6) Translate the "Output selection" subsection of OPTIONS
> 7) Translate the "Output selection modifiers" subsection of OPTIONS
> 8) Translate the "Other parameters" subsection of OPTIONS
> 9) Replace the usage function
>
> Here the DESCRIPTION and OPTIONS subseries is finished. The -h and -help
> parameters are handled by POD now.
>
> 10) Drop obsolete comments
> 11) Refresh the copyright lines
>
> Let's see what's wrong this time.
This patch series looks good to me.
I'll do some testing with it now.
thanks.
> Tomasz Warniełło (11):
> scripts: kernel-doc: Add the basic POD sections
> scripts: kernel-doc: Relink argument parsing error handling to
> pod2usage
> scripts: kernel-doc: Translate the DESCRIPTION section
> scripts: kernel-doc: Translate the "Output format selection"
> subsection of OPTIONS
> scripts: kernel-doc: Translate the "Output format selection modifier"
> subsection of OPTIONS
> scripts: kernel-doc: Translate the "Output selection" subsection of
> OPTIONS
> scripts: kernel-doc: Translate the "Output selection modifiers"
> subsection of OPTIONS
> scripts: kernel-doc: Translate the "Other parameters" subsection of
> OPTIONS
> scripts: kernel-doc: Replace the usage function
> scripts: kernel-doc: Drop obsolete comments
> scripts: kernel-doc: Refresh the copyright lines
>
> scripts/kernel-doc | 347 +++++++++++++++++++++------------------------
> 1 file changed, 159 insertions(+), 188 deletions(-)
>
>
> base-commit: 2a987e65025e2b79c6d453b78cb5985ac6e5eb26
--
~Randy
On 2/18/22 10:16, Tomasz Warniełło wrote:
> The NAME section provides the doc title, while SYNOPSIS contains
> the basic syntax and usage description, which will be printed
> in the help document and in the error output produced on wrong script
> usage.
>
> The rationale is to give users simple and succinct enlightment,
> at the same time structuring the script internally for the maintainers.
>
> In the synopsis, Rst-only options are grouped around rst, and the rest is
> arranged as in the OPTIONS subsections (yet to be translated into POD,
> check at the end of the series).
>
> The third of the basic sections, DESCRIPTION, is added separately.
>
> Signed-off-by: Tomasz Warniełło <[email protected]>
> ---
> scripts/kernel-doc | 25 +++++++++++++++++++++++++
> 1 file changed, 25 insertions(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 3106b7536b89..c8fbf1d3d5aa 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -16,6 +16,31 @@ use strict;
> ## This software falls under the GNU General Public License. ##
> ## Please read the COPYING file for more information ##
>
> +=head1 NAME
> +
> +kernel-doc - Print formatted kernel documentation to stdout
> +
> +=head1 SYNOPSIS
> +
> + kernel-doc [-h] [-v] [-Werror]
> + [ -man |
> + -rst [-sphinx-version VERSION] [-enable-lineno] |
> + -none
> + ]
> + [
> + -export |
> + -internal |
> + [-function NAME] ... |
> + [-nosymbol NAME] ...
> + ]
> + [-no-doc-sections]
> + [-export-file FILE] ...
> + FILE ...
> +
> +Run `kernel-doc -h` for details.
Nit:
$ ./scripts/kernel-doc -h
says:
Run `kernel-doc -h` for details.
> +
> +=cut
> +
> # 18/01/2001 - Cleanups
> # Functions prototyped as foo(void) same as foo()
> # Stop eval'ing where we don't need to.
--
~Randy
On Mon, 21 Feb 2022 22:10:22 -0800
Randy Dunlap <[email protected]> wrote:
> Nit:
> $ ./scripts/kernel-doc -h
> says:
> Run `kernel-doc -h` for details.
Hi Randy,
The -h printout is complete and the synopsis section is only a doc section.
To me this is a very minor concern. I wouldn't even bother to correct this.
The phrasing is not very intelligent in the -h context, but I wouldn't
contextualise this sentence for simplicity. It might be toned down to fit
nicer in multiple contexts, but in the end someone running the -h mode
doesn't need this information at all. And the same applies to this parameter's
description in the "Other parameters" subsection. A user running -h will
know that. What counts to me is syntactical coherence and again - simplicity.
Thanks,
Tomasz
Well, I myself botched line feeds/carriage returns in copy/paste.
Please find a fixed version below:
On Wed, 23 Feb 2022 12:08:35 +0900,
Akira Yokosawa wrote:
> Hello Randy, Tomasz,
>
> On Tue, 22 Feb 2022 13:31:31 -0800,
> Randy Dunlap wrote:
>> Hi--
>>
>> On 2/21/22 21:39, Randy Dunlap wrote:
>>> Hi Tomasz,
>>>
>>> On 2/18/22 10:16, Tomasz Warniełło wrote:
>>>> This series transforms the free-form general comments - mainly the usage
>>>> instructions and the meta information - into the standard Perl
>>>> documentation format. Some of the original text is reduced out. And some
>>>> is simply dropped.
>>>>
>>>> The transformation includes language, paragraphing and editorial
>>>> corrections.
>>>>
>>>> The only change in the script execution flow is the replacement of the
>>>> 'usage' function with the native standard Perl 'pod2usage'.
>>>>
>>>> The to-do suggestion to write POD found in the script is ancient, thus
>>>> I can't address its author with a "Suggested-by" tag.
>>>>
>>>> This version follows the advice received on v3, except I'm leaving
>>>> the old copyrights untouched.
>>>>
>>>> The process consists of 14 steps.
>>>>
>>>> Patches beginning with no 3 are disfunctional until no 9 has been
>>>> applied.
>>>>
>>>> 1) Add the basic POD sections
>>>> 2) Relink argument parsing error handling to pod2usage
>>>>
>>>> The following subseries is disfunctional before its last part.
>>>>
>>>> 3) Translate the DESCRIPTION section
>>>> 4) Translate the "Output format selection" subsection of OPTIONS
>>>> 5) Translate the "Output format selection modifier" subsection of OPTIONS
>>>> 6) Translate the "Output selection" subsection of OPTIONS
>>>> 7) Translate the "Output selection modifiers" subsection of OPTIONS
>>>> 8) Translate the "Other parameters" subsection of OPTIONS
>>>> 9) Replace the usage function
>>>>
>>>> Here the DESCRIPTION and OPTIONS subseries is finished. The -h and -help
>>>> parameters are handled by POD now.
>>>>
>>>> 10) Drop obsolete comments
>>>> 11) Refresh the copyright lines
>>>>
>>>> Let's see what's wrong this time.
>>>
>>> This patch series looks good to me.
>>> I'll do some testing with it now.
>>
>> I did not encounter any problems in testing.
>>
>> Tested-by: Randy Dunlap <[email protected]>
>> Acked-by: Randy Dunlap <[email protected]>
>>
>> Thanks.
>
> Well, I half expected Randy would find a few issues in the series,
> but seeing Randy's Acked-by, let me express my concerns.
>
> I won't delve into the details of each patch, but just compare the
> end result to the current behavior.
>
> First of all, comparison of "./scripts/kernel-doc -h | wc -l":
>
> before: 46
> after: 93
>
> Such a bloat in line counts looks pretty alarming to me.
>
> Especially, added SYNOPSIS of
>
> kernel-doc [-h] [-v] [-Werror]
> [ -man |
> -rst [-sphinx-version VERSION] [-enable-lineno] |
> -none
> ]
> [
> -export |
> -internal |
> [-function NAME] ... |
> [-nosymbol NAME] ...
> ]
> [-no-doc-sections]
> [-export-file FILE] ...
> FILE ...
>
> is hard to parse for me.
> This might be an accurate representation of command arguments,
> but it would take some time for me to see which combination of
> argument works for my use case.
>
> Let's see what "perl --help | head -n10" says:
>
> Usage: perl [switches] [--] [programfile] [arguments]
> -0[octal] specify record separator (\0, if no argument)
> -a autosplit mode with -n or -p (splits $_ into @F)
> -C[number/list] enables the listed Unicode features
> -c check syntax only (runs BEGIN and CHECK blocks)
> -d[:debugger] run program under debugger
> -D[number/list] set debugging flags (argument is a bit mask or alphabets)
> -e program one line of program (several -e's allowed, omit programfile)
> -E program like -e, but enables all optional features
>
> The "Usage:" doesn't tell much about available switches, but as they are covered
> immediately after, this is good enough.
>
> "perl --help | wc -l" says: 33
>
> Let's see one of the few scripts with POD documents: ./scripts/get_feat.pl.
>
> "./scripts/get_feat.pl -h | head -n 5" says:
>
> Usage:
> get_feat.pl [--debug] [--man] [--help] [--dir=<dir>] [--arch=<arch>]
> [--feature=<feature>|--feat=<feature>] <COMAND> [<ARGUMENT>]
>
> Where <COMMAND> can be:
>
> , which I can parse easily.
>
> "./scripts/get_feat.pl -h | wc -l" says: 37
>
> So my preference is to keep current free-form help text for the brevity.
> Nowadays, ./scripts/kernel-doc is mostly invoked by
> Documentation/sphinx/kerneldoc.py.
> I don't see much point for such a non-user-facing script having nice-looking
> well-structured documentation in the first place.
>
> For the record, let me add a random tag to this whole series:
>
> Disliked-by: Akira Yokosawa <[email protected]>
>
> This is by all means a personal preference, so I don't mind if Jon applies
> this series as is.
>
> Thanks, Akira
Sorry for the noise.
Akira
>
>>
>>>> Tomasz Warniełło (11):
>>>> scripts: kernel-doc: Add the basic POD sections
>>>> scripts: kernel-doc: Relink argument parsing error handling to
>>>> pod2usage
>>>> scripts: kernel-doc: Translate the DESCRIPTION section
>>>> scripts: kernel-doc: Translate the "Output format selection"
>>>> subsection of OPTIONS
>>>> scripts: kernel-doc: Translate the "Output format selection modifier"
>>>> subsection of OPTIONS
>>>> scripts: kernel-doc: Translate the "Output selection" subsection of
>>>> OPTIONS
>>>> scripts: kernel-doc: Translate the "Output selection modifiers"
>>>> subsection of OPTIONS
>>>> scripts: kernel-doc: Translate the "Other parameters" subsection of
>>>> OPTIONS
>>>> scripts: kernel-doc: Replace the usage function
>>>> scripts: kernel-doc: Drop obsolete comments
>>>> scripts: kernel-doc: Refresh the copyright lines
>>>>
>>>> scripts/kernel-doc | 347 +++++++++++++++++++++------------------------
>>>> 1 file changed, 159 insertions(+), 188 deletions(-)
>>>>
>>>>
>>>> base-commit: 2a987e65025e2b79c6d453b78cb5985ac6e5eb26
>>>
>>
>> --
>> ~Randy
>
Hi--
On 2/21/22 21:39, Randy Dunlap wrote:
> Hi Tomasz,
>
> On 2/18/22 10:16, Tomasz Warniełło wrote:
>> This series transforms the free-form general comments - mainly the usage
>> instructions and the meta information - into the standard Perl
>> documentation format. Some of the original text is reduced out. And some
>> is simply dropped.
>>
>> The transformation includes language, paragraphing and editorial
>> corrections.
>>
>> The only change in the script execution flow is the replacement of the
>> 'usage' function with the native standard Perl 'pod2usage'.
>>
>> The to-do suggestion to write POD found in the script is ancient, thus
>> I can't address its author with a "Suggested-by" tag.
>>
>> This version follows the advice received on v3, except I'm leaving
>> the old copyrights untouched.
>>
>> The process consists of 14 steps.
>>
>> Patches beginning with no 3 are disfunctional until no 9 has been
>> applied.
>>
>> 1) Add the basic POD sections
>> 2) Relink argument parsing error handling to pod2usage
>>
>> The following subseries is disfunctional before its last part.
>>
>> 3) Translate the DESCRIPTION section
>> 4) Translate the "Output format selection" subsection of OPTIONS
>> 5) Translate the "Output format selection modifier" subsection of OPTIONS
>> 6) Translate the "Output selection" subsection of OPTIONS
>> 7) Translate the "Output selection modifiers" subsection of OPTIONS
>> 8) Translate the "Other parameters" subsection of OPTIONS
>> 9) Replace the usage function
>>
>> Here the DESCRIPTION and OPTIONS subseries is finished. The -h and -help
>> parameters are handled by POD now.
>>
>> 10) Drop obsolete comments
>> 11) Refresh the copyright lines
>>
>> Let's see what's wrong this time.
>
> This patch series looks good to me.
> I'll do some testing with it now.
I did not encounter any problems in testing.
Tested-by: Randy Dunlap <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Thanks.
>> Tomasz Warniełło (11):
>> scripts: kernel-doc: Add the basic POD sections
>> scripts: kernel-doc: Relink argument parsing error handling to
>> pod2usage
>> scripts: kernel-doc: Translate the DESCRIPTION section
>> scripts: kernel-doc: Translate the "Output format selection"
>> subsection of OPTIONS
>> scripts: kernel-doc: Translate the "Output format selection modifier"
>> subsection of OPTIONS
>> scripts: kernel-doc: Translate the "Output selection" subsection of
>> OPTIONS
>> scripts: kernel-doc: Translate the "Output selection modifiers"
>> subsection of OPTIONS
>> scripts: kernel-doc: Translate the "Other parameters" subsection of
>> OPTIONS
>> scripts: kernel-doc: Replace the usage function
>> scripts: kernel-doc: Drop obsolete comments
>> scripts: kernel-doc: Refresh the copyright lines
>>
>> scripts/kernel-doc | 347 +++++++++++++++++++++------------------------
>> 1 file changed, 159 insertions(+), 188 deletions(-)
>>
>>
>> base-commit: 2a987e65025e2b79c6d453b78cb5985ac6e5eb26
>
--
~Randy
Hello Randy, Tomasz,
On Tue, 22 Feb 2022 13:31:31 -0800,
Randy Dunlap wrote:
> Hi--
>
> On 2/21/22 21:39, Randy Dunlap wrote:
>> Hi Tomasz,
>>
>> On 2/18/22 10:16, Tomasz Warniełło wrote:
>>> This series transforms the free-form general comments - mainly the usage
>>> instructions and the meta information - into the standard Perl
>>> documentation format. Some of the original text is reduced out. And some
>>> is simply dropped.
>>>
>>> The transformation includes language, paragraphing and editorial
>>> corrections.
>>>
>>> The only change in the script execution flow is the replacement of the
>>> 'usage' function with the native standard Perl 'pod2usage'.
>>>
>>> The to-do suggestion to write POD found in the script is ancient, thus
>>> I can't address its author with a "Suggested-by" tag.
>>>
>>> This version follows the advice received on v3, except I'm leaving
>>> the old copyrights untouched.
>>>
>>> The process consists of 14 steps.
>>>
>>> Patches beginning with no 3 are disfunctional until no 9 has been
>>> applied.
>>>
>>> 1) Add the basic POD sections
>>> 2) Relink argument parsing error handling to pod2usage
>>>
>>> The following subseries is disfunctional before its last part.
>>>
>>> 3) Translate the DESCRIPTION section
>>> 4) Translate the "Output format selection" subsection of OPTIONS
>>> 5) Translate the "Output format selection modifier" subsection of OPTIONS
>>> 6) Translate the "Output selection" subsection of OPTIONS
>>> 7) Translate the "Output selection modifiers" subsection of OPTIONS
>>> 8) Translate the "Other parameters" subsection of OPTIONS
>>> 9) Replace the usage function
>>>
>>> Here the DESCRIPTION and OPTIONS subseries is finished. The -h and -help
>>> parameters are handled by POD now.
>>>
>>> 10) Drop obsolete comments
>>> 11) Refresh the copyright lines
>>>
>>> Let's see what's wrong this time.
>>
>> This patch series looks good to me.
>> I'll do some testing with it now.
>
> I did not encounter any problems in testing.
>
> Tested-by: Randy Dunlap <[email protected]>
> Acked-by: Randy Dunlap <[email protected]>
>
> Thanks.
Well, I half expected Randy would find a few issues in the series,
but seeing Randy's Acked-by, let me express my concerns.
I won't delve into the details of each patch, but just compare the
end result to the current behavior.
First of all, comparison of "./scripts/kernel-doc -h | wc -l":
before: 46
after: 93
Such a bloat in line counts looks pretty alarming to me.
Especially, added SYNOPSIS of
kernel-doc [-h] [-v] [-Werror]
[ -man |
-rst [-sphinx-version VERSION] [-enable-lineno] |
-none
]
[
-export |
-internal |
[-function NAME] ... |
[-nosymbol NAME] ...
]
[-no-doc-sections]
[-export-file FILE] ...
FILE ...
is hard to parse for me.
This might be an accurate representation of command arguments,
but it would take some time for me to see which combination of
argument works for my use case.
Let's see what "perl --help | head -n10" says:
Usage: perl [switches] [--] [programfile] [arguments]
-0[octal] specify record separator (\0, if no argument)
-a autosplit mode with -n or -p (splits $_ into @F)
-C[number/list] enables the listed Unicode features
-c check syntax only (runs BEGIN and CHECK blocks)
-d[:debugger] run program under debugger
-D[number/list] set debugging flags (argument is a bit mask or alphabets)
-e program one line of program (several -e's allowed, omit programfile)
-E program like -e, but enables all optional features
The "Usage:" doesn't tell much about available switches, but as they are covered
immediately after, this is good enough.
"perl --help | wc -l" says: 33
Let's see one of the few scripts with POD documents: ./scripts/get_feat.pl.
"./scripts/get_feat.pl -h | head -n 5" says:
Usage:
get_feat.pl [--debug] [--man] [--help] [--dir=<dir>] [--arch=<arch>]
[--feature=<feature>|--feat=<feature>] <COMAND> [<ARGUMENT>]
Where <COMMAND> can be:
, which I can parse easily.
"./scripts/get_feat.pl -h | wc -l" says: 37
So my preference is to keep current free-form help text for the brevity.
Nowadays, ./scripts/kernel-doc is mostly invoked by
Documentation/sphinx/kerneldoc.py.
I don't see much point for such a non-user-facing script having nice-looking
well-structured documentation in the first place.
For the record, let me add a random tag to this whole series:
Disliked-by: Akira Yokosawa <[email protected]>
This is by all means a personal preference, so I don't mind if Jon applies
this series as is.
Thanks, Akira
>
>>> Tomasz Warniełło (11):
>>> scripts: kernel-doc: Add the basic POD sections
>>> scripts: kernel-doc: Relink argument parsing error handling to
>>> pod2usage
>>> scripts: kernel-doc: Translate the DESCRIPTION section
>>> scripts: kernel-doc: Translate the "Output format selection"
>>> subsection of OPTIONS
>>> scripts: kernel-doc: Translate the "Output format selection modifier"
>>> subsection of OPTIONS
>>> scripts: kernel-doc: Translate the "Output selection" subsection of
>>> OPTIONS
>>> scripts: kernel-doc: Translate the "Output selection modifiers"
>>> subsection of OPTIONS
>>> scripts: kernel-doc: Translate the "Other parameters" subsection of
>>> OPTIONS
>>> scripts: kernel-doc: Replace the usage function
>>> scripts: kernel-doc: Drop obsolete comments
>>> scripts: kernel-doc: Refresh the copyright lines
>>>
>>> scripts/kernel-doc | 347 +++++++++++++++++++++------------------------
>>> 1 file changed, 159 insertions(+), 188 deletions(-)
>>>
>>>
>>> base-commit: 2a987e65025e2b79c6d453b78cb5985ac6e5eb26
>>
>
> --
> ~Randy
On Wed, 23 Feb 2022 22:16:30 +0900
Akira Yokosawa <[email protected]> wrote:
> When I do "man perl", I want to see a detailed explanation, and
> somewhat hard-to-parse synopsis is ok.
>
> I'm saying that I don't like to see such a thing when I type
> "./scripts/kerneldoc -h". I expect a hint to recall which option I
> should use. I don't want to scroll back the terminal.
>
> It would be nice if the verbose man page can be shown by
> "./scripts/kerneldoc -v -h" or "perldoc -F ./scripts/kerneldoc".
This is an option. But it makes things more complex. I'd rather reduce
the easy in favour of the difficult.
> >>> I don't see much point for such a non-user-facing script having nice-looking
> >>> well-structured documentation in the first place.
> >
> > You're touching the very essence of kernel-doc here. What and who is it for?
> > Not just the script - all of it.
>
> Sorry, I have no idea what I am being asked.
> Could you rephrase above for a non-native speaker of English, please?
Who is the "user"? Most of Linux users never even browse the source code.
Tomasz
On Wed, 23 Feb 2022 13:55:48 +0100,
Tomasz Warniełło wrote:
> Hi Akira,
>
> Take a look at `man perl` and you will find a synopsis also.
When I do "man perl", I want to see a detailed explanation, and
somewhat hard-to-parse synopsis is ok.
I'm saying that I don't like to see such a thing when I type
"./scripts/kerneldoc -h". I expect a hint to recall which option I
should use. I don't want to scroll back the terminal.
It would be nice if the verbose man page can be shown by
"./scripts/kerneldoc -v -h" or "perldoc -F ./scripts/kerneldoc".
> It's simply
> better in depicting grammar relations than a flat switch list. Especially
> when the grammar gets complex. I dislike it also. And I don't think it
> looks good. Rather creepy and overwhelming.
>
>>> I don't see much point for such a non-user-facing script having nice-looking
>>> well-structured documentation in the first place.
>
> You're touching the very essence of kernel-doc here. What and who is it for?
> Not just the script - all of it.
Sorry, I have no idea what I am being asked.
Could you rephrase above for a non-native speaker of English, please?
Thanks, Akira
>
> Regards,
>
> Tomasz
Hi Akira,
Take a look at `man perl` and you will find a synopsis also. It's simply
better in depicting grammar relations than a flat switch list. Especially
when the grammar gets complex. I dislike it also. And I don't think it
looks good. Rather creepy and overwhelming.
> > I don't see much point for such a non-user-facing script having nice-looking
> > well-structured documentation in the first place.
You're touching the very essence of kernel-doc here. What and who is it for?
Not just the script - all of it.
Regards,
Tomasz
Tomasz Warniełło <[email protected]> writes:
> This series transforms the free-form general comments - mainly the usage
> instructions and the meta information - into the standard Perl
> documentation format. Some of the original text is reduced out. And some
> is simply dropped.
>
> The transformation includes language, paragraphing and editorial
> corrections.
>
> The only change in the script execution flow is the replacement of the
> 'usage' function with the native standard Perl 'pod2usage'.
I have applied the series, thanks.
jon
On Thu, 24 Feb 2022 11:42:38 -0700
Jonathan Corbet <[email protected]> wrote:
> I have applied the series, thanks.
>
> jon
Thanks Jon,
T. W.