Re: [PATCH v4 00/11] Transform documentation into POD

[Akira Yokosawa]

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@xxxxxxxxxxxxx>
>> Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
>>
>> 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@xxxxxxxxx>
> 
> 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
>