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

[Akira Yokosawa <akiyks@gmail.com>]

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