scripts/kernel-doc | 347 +++++++++++++++++++++------------------------ 1 file changed, 159 insertions(+), 188 deletions(-)
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
Tomasz Warniełło <tomasz.warniello@gmail.com> 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 <corbet@lwn.net> wrote: > I have applied the series, thanks. > > jon Thanks Jon, T. W.
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
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 <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> 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 <rdunlap@infradead.org>
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
>
> 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 <akiyks@gmail.com>
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
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 <rdunlap@infradead.org> >> Acked-by: Randy Dunlap <rdunlap@infradead.org> >> >> 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 <akiyks@gmail.com> > > 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 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
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
On Wed, 23 Feb 2022 22:16:30 +0900 Akira Yokosawa <akiyks@gmail.com> 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
© 2016 - 2026 Red Hat, Inc.