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 >
