lkml.org 
[lkml]   [2022]   [Feb]   [22]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
SubjectRe: [PATCH v4 00/11] Transform documentation into POD
From
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
>

\
 
 \ /
  Last update: 2022-02-23 04:19    [W:0.054 / U:3.380 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site