[PATCH v4 00/11] Transform documentation into POD

[PATCH v4 00/11] Transform documentation into POD

[Tomasz Warniełło]

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

[PATCH v4 01/11] scripts: kernel-doc: Add the basic POD sections

[Tomasz Warniełło]

The NAME section provides the doc title, while SYNOPSIS contains
the basic syntax and usage description, which will be printed
in the help document and in the error output produced on wrong script
usage.

The rationale is to give users simple and succinct enlightment,
at the same time structuring the script internally for the maintainers.

In the synopsis, Rst-only options are grouped around rst, and the rest is
arranged as in the OPTIONS subsections (yet to be translated into POD,
check at the end of the series).

The third of the basic sections, DESCRIPTION, is added separately.

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3106b7536b89..c8fbf1d3d5aa 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -16,6 +16,31 @@ use strict;
 ## This software falls under the GNU General Public License.     ##
 ## Please read the COPYING file for more information             ##
 
+=head1 NAME
+
+kernel-doc - Print formatted kernel documentation to stdout
+
+=head1 SYNOPSIS
+
+ 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 ...
+
+Run `kernel-doc -h` for details.
+
+=cut
+
 # 18/01/2001 - 	Cleanups
 # 		Functions prototyped as foo(void) same as foo()
 # 		Stop eval'ing where we don't need to.
-- 
2.30.2

[PATCH v4 02/11] scripts: kernel-doc: Relink argument parsing error handling to pod2usage

[Tomasz Warniełło]

The former usage function is substituted, although not as the -h and -help
parameter handler yet.

Purpose: Use Pod::Usage to handle documentation printing in an integrated
way.

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---

If the indentation is still wrong, please state, what you expect exactly.
To me the style in the script is random or eclectic.
---
 scripts/kernel-doc | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c8fbf1d3d5aa..e7f7251771bb 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -16,6 +16,8 @@ use strict;
 ## This software falls under the GNU General Public License.     ##
 ## Please read the COPYING file for more information             ##
 
+use Pod::Usage qw/pod2usage/;
+
 =head1 NAME
 
 kernel-doc - Print formatted kernel documentation to stdout
@@ -298,7 +300,13 @@ my $blankline_rst = "\n";
 
 # read arguments
 if ($#ARGV == -1) {
-    usage();
+	pod2usage(
+		-message => "No arguments!\n",
+		-exitval => 1,
+		-verbose => 99,
+		-sections => 'SYNOPSIS',
+		-output => \*STDERR,
+	);
 }
 
 my $kernelversion;
@@ -518,8 +526,14 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
 	    die "Sphinx version should either major.minor or major.minor.patch format\n";
 	}
     } else {
-	# Unknown argument
-        usage();
+		# Unknown argument
+		pod2usage(
+			-message => "Argument unknown!\n",
+			-exitval => 1,
+			-verbose => 99,
+			-sections => 'SYNOPSIS',
+			-output => \*STDERR,
+		);
     }
 }
 
-- 
2.30.2

[PATCH v4 03/11] scripts: kernel-doc: Translate the DESCRIPTION section

[Tomasz Warniełło]

Transition the description section into POD. This is one of the standard
documentation sections. This adjustment makes the section available for
POD and makes it look better.

Notes:
- an article addition
- paragraphing correction

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e7f7251771bb..e4203f13fa93 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -41,6 +41,15 @@ kernel-doc - Print formatted kernel documentation to stdout
 
 Run `kernel-doc -h` for details.
 
+=head1 DESCRIPTION
+
+Read C language source or header FILEs, extract embedded documentation comments,
+and print formatted documentation to standard output.
+
+The documentation comments are identified by the "/**" opening comment mark.
+
+See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
+
 =cut
 
 # 18/01/2001 - 	Cleanups
@@ -72,12 +81,6 @@ sub usage {
     my $message = <<"EOF";
 Usage: $0 [OPTION ...] FILE ...
 
-Read C language source or header FILEs, extract embedded documentation comments,
-and print formatted documentation to standard output.
-
-The documentation comments are identified by "/**" opening comment mark. See
-Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
-
 Output format selection (mutually exclusive):
   -man			Output troff manual page format. This is the default.
   -rst			Output reStructuredText format.
-- 
2.30.2

[PATCH v4 04/11] scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS

[Tomasz Warniełło]

Another step in the direction of a uniform POD documentation, which will
make users happier.

Options land at the end of the script, not to clutter the file top.

The default output format is corrected to rst. That's what it is now.

A POD delimiting comment is added to the script head, which improves
the script logical structure.

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e4203f13fa93..18eca172c4b5 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -52,6 +52,8 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
 
 =cut
 
+# more perldoc at the end of the file
+
 # 18/01/2001 - 	Cleanups
 # 		Functions prototyped as foo(void) same as foo()
 # 		Stop eval'ing where we don't need to.
@@ -81,11 +83,6 @@ sub usage {
     my $message = <<"EOF";
 Usage: $0 [OPTION ...] FILE ...
 
-Output format selection (mutually exclusive):
-  -man			Output troff manual page format. This is the default.
-  -rst			Output reStructuredText format.
-  -none			Do not output documentation, only warnings.
-
 Output format selection modifier (affects only ReST output):
 
   -sphinx-version	Use the ReST C domain dialect compatible with an
@@ -2563,3 +2560,27 @@ if ($Werror && $warnings) {
 } else {
     exit($output_mode eq "none" ? 0 : $errors)
 }
+
+__END__
+
+=head1 OPTIONS
+
+=head2 Output format selection (mutually exclusive):
+
+=over 8
+
+=item -man
+
+Output troff manual page format.
+
+=item -rst
+
+Output reStructuredText format. This is the default.
+
+=item -none
+
+Do not output documentation, only warnings.
+
+=back
+
+=cut
-- 
2.30.2

[PATCH v4 05/11] scripts: kernel-doc: Translate the "Output format selection modifier" subsection of OPTIONS

[Tomasz Warniełło]

Aim: unified POD, user more happy

This section is renamed to "Output format modifiers" to make it simple.

To make it even more simple, a subsection is added:
"reStructuredText only".

Other notes:
- paragraphing correction
- article correction

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 18eca172c4b5..b926faa16b00 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,13 +83,6 @@ sub usage {
     my $message = <<"EOF";
 Usage: $0 [OPTION ...] FILE ...
 
-Output format selection modifier (affects only ReST output):
-
-  -sphinx-version	Use the ReST C domain dialect compatible with an
-			specific Sphinx Version.
-			If not specified, kernel-doc will auto-detect using
-			the sphinx-build version found on PATH.
-
 Output selection (mutually exclusive):
   -export		Only output documentation for symbols that have been
 			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
@@ -2583,4 +2576,19 @@ Do not output documentation, only warnings.
 
 =back
 
+=head2 Output format modifiers
+
+=head3 reStructuredText only
+
+=over 8
+
+=item -sphinx-version VERSION
+
+Use the ReST C domain dialect compatible with a specific Sphinx Version.
+
+If not specified, kernel-doc will auto-detect using the sphinx-build version
+found on PATH.
+
+=back
+
 =cut
-- 
2.30.2

[PATCH v4 06/11] scripts: kernel-doc: Translate the "Output selection" subsection of OPTIONS

[Tomasz Warniełło]

Aim: unified POD, user more satisfied, script better structured

The plurals in -function and -nosymbol are corrected to singulars.
That's how the script works now. I think this describes the syntax better.
The plurar suggests multiple FILE arguments might be possible. So this
seems more coherent.

Other notes:
- paragraphing correction
- article correction

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 42 +++++++++++++++++++++++++++++-------------
 1 file changed, 29 insertions(+), 13 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index b926faa16b00..e49cdb307a35 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,19 +83,6 @@ sub usage {
     my $message = <<"EOF";
 Usage: $0 [OPTION ...] FILE ...
 
-Output selection (mutually exclusive):
-  -export		Only output documentation for symbols that have been
-			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
-                        in any input FILE or -export-file FILE.
-  -internal		Only output documentation for symbols that have NOT been
-			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
-                        in any input FILE or -export-file FILE.
-  -function NAME	Only output documentation for the given function(s)
-			or DOC: section title(s). All other functions and DOC:
-			sections are ignored. May be specified multiple times.
-  -nosymbol NAME	Exclude the specified symbols from the output
-		        documentation. May be specified multiple times.
-
 Output selection modifiers:
   -no-doc-sections	Do not output DOC: sections.
   -enable-lineno        Enable output of #define LINENO lines. Only works with
@@ -2591,4 +2578,33 @@ found on PATH.
 
 =back
 
+=head2 Output selection (mutually exclusive):
+
+=over 8
+
+=item -export
+
+Only output documentation for the symbols that have been exported using
+EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
+
+=item -internal
+
+Only output documentation for the symbols that have NOT been exported using
+EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
+
+=item -function NAME
+
+Only output documentation for the given function or DOC: section title.
+All other functions and DOC: sections are ignored.
+
+May be specified multiple times.
+
+=item -nosymbol NAME
+
+Exclude the specified symbol from the output documentation.
+
+May be specified multiple times.
+
+=back
+
 =cut
-- 
2.30.2

[PATCH v4 07/11] scripts: kernel-doc: Translate the "Output selection modifiers" subsection of OPTIONS

[Tomasz Warniełło]

Aim: unified POD, user more satisfied, script better structured

A subsection "reStructuredText only" is added for -enable-lineno.

Other notes:
- paragraphing correction

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 37 +++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e49cdb307a35..210e7e3b501b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,14 +83,6 @@ sub usage {
     my $message = <<"EOF";
 Usage: $0 [OPTION ...] FILE ...
 
-Output selection modifiers:
-  -no-doc-sections	Do not output DOC: sections.
-  -enable-lineno        Enable output of #define LINENO lines. Only works with
-                        reStructuredText format.
-  -export-file FILE     Specify an additional FILE in which to look for
-                        EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
-                        -export or -internal. May be specified multiple times.
-
 Other parameters:
   -v			Verbose output, more warnings and other information.
   -h			Print this help.
@@ -2607,4 +2599,33 @@ May be specified multiple times.
 
 =back
 
+=head2 Output selection modifiers:
+
+=over 8
+
+=item -no-doc-sections
+
+Do not output DOC: sections.
+
+=item -export-file FILE
+
+Specify an additional FILE in which to look for EXPORT_SYMBOL() and
+EXPORT_SYMBOL_GPL().
+
+To be used with -export or -internal.
+
+May be specified multiple times.
+
+=back
+
+=head3 reStructuredText only
+
+=over 8
+
+=item -enable-lineno
+
+Enable output of #define LINENO lines.
+
+=back
+
 =cut
-- 
2.30.2

[PATCH v4 08/11] scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONS

[Tomasz Warniełło]

Aim: unified POD, user more satisfied, script better structured

Notes:
- The -help token is added.
- The entries are sorted alphbetically.

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 210e7e3b501b..4a26a74318e6 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,11 +83,6 @@ sub usage {
     my $message = <<"EOF";
 Usage: $0 [OPTION ...] FILE ...
 
-Other parameters:
-  -v			Verbose output, more warnings and other information.
-  -h			Print this help.
-  -Werror		Treat warnings as errors.
-
 EOF
     print $message;
     exit 1;
@@ -2628,4 +2623,22 @@ Enable output of #define LINENO lines.
 
 =back
 
+=head2 Other parameters:
+
+=over 8
+
+=item -h, -help
+
+Print this help.
+
+=item -v
+
+Verbose output, more warnings and other information.
+
+=item -Werror
+
+Treat warnings as errors.
+
+=back
+
 =cut
-- 
2.30.2

[PATCH v4 09/11] scripts: kernel-doc: Replace the usage function

[Tomasz Warniełło]

Aim: unified POD, user more satisfied, script better structured

You can see the results with:

$ scripts/kernel-doc -help

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---

This ends the fundamental POD transformation.
---
 scripts/kernel-doc | 11 +----------
 1 file changed, 1 insertion(+), 10 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 4a26a74318e6..d7ca4877eeda 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -79,15 +79,6 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
 # 25/07/2012 - Added support for HTML5
 # -- Dan Luedtke <mail@danrl.de>
 
-sub usage {
-    my $message = <<"EOF";
-Usage: $0 [OPTION ...] FILE ...
-
-EOF
-    print $message;
-    exit 1;
-}
-
 #
 # format of comments.
 # In the following table, (...)? signifies optional structure.
@@ -468,7 +459,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
     } elsif ($cmd eq "Werror") {
 	$Werror = 1;
     } elsif (($cmd eq "h") || ($cmd eq "help")) {
-	usage();
+		pod2usage(-exitval => 0, -verbose => 2);
     } elsif ($cmd eq 'no-doc-sections') {
 	    $no_doc_sections = 1;
     } elsif ($cmd eq 'enable-lineno') {
-- 
2.30.2

[PATCH v4 10/11] scripts: kernel-doc: Drop obsolete comments

[Tomasz Warniełło]

What for? To improve the script maintainability.

1. License

As stated by Jonathan Corbet in the reply to my version 1, the SPDX line
is enough.

2. The to-do list comment

As suggested by Jonathan Corbet in reply to my version 3, this section
doesn't need to be transitioned. And so it is removed for clarity.

3. The historical changelog comments

As suggested by Jonathan Corbet in a reply to v3, this section can go.
I wanted to keep it, but since it doesn't contain copyright notices,
let's just have it clean and simple.

4. The "format of comments" comment block

As suggested by Jani Nikula in a reply to my first version of this
transformation, Documentation/doc-guide/kernel-doc.rst can serve as the
information hub for comment formatting. The section DESCRIPTION already
points there, so the original comment block can just be removed.

Suggested-by: Jonathan Corbet <corbet@lwn.net>
Suggested-by: Jani Nikula <jani.nikula@linux.intel.com>
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 143 ---------------------------------------------
 1 file changed, 143 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d7ca4877eeda..a5a397e22ea7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -12,9 +12,6 @@ use strict;
 ## 								 ##
 ## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
 ## Copyright (c) 2000 MontaVista Software, Inc.			 ##
-## 								 ##
-## This software falls under the GNU General Public License.     ##
-## Please read the COPYING file for more information             ##
 
 use Pod::Usage qw/pod2usage/;
 
@@ -54,146 +51,6 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
 
 # more perldoc at the end of the file
 
-# 18/01/2001 - 	Cleanups
-# 		Functions prototyped as foo(void) same as foo()
-# 		Stop eval'ing where we don't need to.
-# -- huggie@earth.li
-
-# 27/06/2001 -  Allowed whitespace after initial "/**" and
-#               allowed comments before function declarations.
-# -- Christian Kreibich <ck@whoop.org>
-
-# Still to do:
-# 	- add perldoc documentation
-# 	- Look more closely at some of the scarier bits :)
-
-# 26/05/2001 - 	Support for separate source and object trees.
-#		Return error code.
-# 		Keith Owens <kaos@ocs.com.au>
-
-# 23/09/2001 - Added support for typedefs, structs, enums and unions
-#              Support for Context section; can be terminated using empty line
-#              Small fixes (like spaces vs. \s in regex)
-# -- Tim Jansen <tim@tjansen.de>
-
-# 25/07/2012 - Added support for HTML5
-# -- Dan Luedtke <mail@danrl.de>
-
-#
-# format of comments.
-# In the following table, (...)? signifies optional structure.
-#                         (...)* signifies 0 or more structure elements
-# /**
-#  * function_name(:)? (- short description)?
-# (* @parameterx: (description of parameter x)?)*
-# (* a blank line)?
-#  * (Description:)? (Description of function)?
-#  * (section header: (section description)? )*
-#  (*)?*/
-#
-# So .. the trivial example would be:
-#
-# /**
-#  * my_function
-#  */
-#
-# If the Description: header tag is omitted, then there must be a blank line
-# after the last parameter specification.
-# e.g.
-# /**
-#  * my_function - does my stuff
-#  * @my_arg: its mine damnit
-#  *
-#  * Does my stuff explained.
-#  */
-#
-#  or, could also use:
-# /**
-#  * my_function - does my stuff
-#  * @my_arg: its mine damnit
-#  * Description: Does my stuff explained.
-#  */
-# etc.
-#
-# Besides functions you can also write documentation for structs, unions,
-# enums and typedefs. Instead of the function name you must write the name
-# of the declaration;  the struct/union/enum/typedef must always precede
-# the name. Nesting of declarations is not supported.
-# Use the argument mechanism to document members or constants.
-# e.g.
-# /**
-#  * struct my_struct - short description
-#  * @a: first member
-#  * @b: second member
-#  *
-#  * Longer description
-#  */
-# struct my_struct {
-#     int a;
-#     int b;
-# /* private: */
-#     int c;
-# };
-#
-# All descriptions can be multiline, except the short function description.
-#
-# For really longs structs, you can also describe arguments inside the
-# body of the struct.
-# eg.
-# /**
-#  * struct my_struct - short description
-#  * @a: first member
-#  * @b: second member
-#  *
-#  * Longer description
-#  */
-# struct my_struct {
-#     int a;
-#     int b;
-#     /**
-#      * @c: This is longer description of C
-#      *
-#      * You can use paragraphs to describe arguments
-#      * using this method.
-#      */
-#     int c;
-# };
-#
-# This should be use only for struct/enum members.
-#
-# You can also add additional sections. When documenting kernel functions you
-# should document the "Context:" of the function, e.g. whether the functions
-# can be called form interrupts. Unlike other sections you can end it with an
-# empty line.
-# A non-void function should have a "Return:" section describing the return
-# value(s).
-# Example-sections should contain the string EXAMPLE so that they are marked
-# appropriately in DocBook.
-#
-# Example:
-# /**
-#  * user_function - function that can only be called in user context
-#  * @a: some argument
-#  * Context: !in_interrupt()
-#  *
-#  * Some description
-#  * Example:
-#  *    user_function(22);
-#  */
-# ...
-#
-#
-# All descriptive text is further processed, scanning for the following special
-# patterns, which are highlighted appropriately.
-#
-# 'funcname()' - function
-# '$ENVVAR' - environmental variable
-# '&struct_name' - name of a structure (up to two words including 'struct')
-# '&struct_name.member' - name of a structure member
-# '@parameter' - name of a parameter
-# '%CONST' - name of a constant.
-# '``LITERAL``' - literal string without any spaces on it.
-
 ## init lots of data
 
 my $errors = 0;
-- 
2.30.2

[PATCH v4 11/11] scripts: kernel-doc: Refresh the copyright lines

[Tomasz Warniełło]

I wanted to clean up these lines, but in the end decided not to touch
the old ones and just add my own about POD. I'll leave the cleanup
for lawyers.

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---

Still credits go to Jonathat Corbet for alerting me when I moved them to
POD in version 1.
---
 scripts/kernel-doc | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a5a397e22ea7..f06f68f3c3d9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -12,6 +12,8 @@ use strict;
 ## 								 ##
 ## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
 ## Copyright (c) 2000 MontaVista Software, Inc.			 ##
+#
+# Copyright (C) 2022 Tomasz Warniełło (POD)
 
 use Pod::Usage qw/pod2usage/;
 
-- 
2.30.2

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

[Randy Dunlap]

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

Re: [PATCH v4 01/11] scripts: kernel-doc: Add the basic POD sections

[Randy Dunlap]

On 2/18/22 10:16, Tomasz Warniełło wrote:
> The NAME section provides the doc title, while SYNOPSIS contains
> the basic syntax and usage description, which will be printed
> in the help document and in the error output produced on wrong script
> usage.
> 
> The rationale is to give users simple and succinct enlightment,
> at the same time structuring the script internally for the maintainers.
> 
> In the synopsis, Rst-only options are grouped around rst, and the rest is
> arranged as in the OPTIONS subsections (yet to be translated into POD,
> check at the end of the series).
> 
> The third of the basic sections, DESCRIPTION, is added separately.
> 
> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> ---
>  scripts/kernel-doc | 25 +++++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 3106b7536b89..c8fbf1d3d5aa 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -16,6 +16,31 @@ use strict;
>  ## This software falls under the GNU General Public License.     ##
>  ## Please read the COPYING file for more information             ##
>  
> +=head1 NAME
> +
> +kernel-doc - Print formatted kernel documentation to stdout
> +
> +=head1 SYNOPSIS
> +
> + 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 ...
> +
> +Run `kernel-doc -h` for details.

Nit:
$ ./scripts/kernel-doc -h
says:
    Run `kernel-doc -h` for details.

> +
> +=cut
> +
>  # 18/01/2001 - 	Cleanups
>  # 		Functions prototyped as foo(void) same as foo()
>  # 		Stop eval'ing where we don't need to.

-- 
~Randy

Re: [PATCH v4 01/11] scripts: kernel-doc: Add the basic POD sections

[Tomasz Warniełło]

On Mon, 21 Feb 2022 22:10:22 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> Nit:
> $ ./scripts/kernel-doc -h
> says:
>     Run `kernel-doc -h` for details.

Hi Randy,

The -h printout is complete and the synopsis section is only a doc section.
To me this is a very minor concern. I wouldn't even bother to correct this.
The phrasing is not very intelligent in the -h context, but I wouldn't
contextualise this sentence for simplicity. It might be toned down to fit
nicer in multiple contexts, but in the end someone running the -h mode
doesn't need this information at all. And the same applies to this parameter's
description in the "Other parameters" subsection. A user running -h will
know that. What counts to me is syntactical coherence and again - simplicity.

Thanks,

Tomasz

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

[Randy Dunlap]

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

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

[Akira Yokosawa]

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

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@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
> 

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

[Tomasz Warniełło]

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

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

[Akira Yokosawa]

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

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

[Tomasz Warniełło]

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

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

[Akira Yokosawa]

[-CC lkml]
On Wed, 23 Feb 2022 15:04:03 +0100,
Tomasz Warniełło wrote:
> 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'd say _not_ introducing POD is the simplest, but I guess you have
another thought.

> 
>>>>> 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.

Apparently, users of ./scripts/kernel-doc are who run "make htmldocs" or
"make pdfdocs", a relatively small portion of Linux kernel development
community, I guess.  Note that they don't have direct interactions with
./scripts/kernel-doc in most (>95% ??) cases.

Normal Linux end-users don't bother with kernel-doc, I guess.

If you are interested in how the kernel dev community works, I'd
recommend starting from "Working with the kernel development community"
at https://www.kernel.org/doc/html/latest/process/index.html, that is
if you have not done so.

        Thanks, Akira

> 
> Tomasz

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

[Tomasz Warniełło]

On Thu, 24 Feb 2022 00:05:44 +0900
Akira Yokosawa <akiyks@gmail.com> wrote:

> I'd say _not_ introducing POD is the simplest, but I guess you have
> another thought.

Not at all. I'm in full drift.

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

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Apparently, users of ./scripts/kernel-doc are who run "make htmldocs" or
> "make pdfdocs", a relatively small portion of Linux kernel development
> community, I guess.  Note that they don't have direct interactions with
> ./scripts/kernel-doc in most (>95% ??) cases.
>
> Normal Linux end-users don't bother with kernel-doc, I guess.

In my experience, directly running kernel-doc is usually part of the
process of trying to figure out why kerneldoc comments aren't rendering
as expected; otherwise it's completely hidden.  I do think that these
changes can be helpful in that use case, and they bring the script a bit
closer to contemporary Perl standards.  Overall, I think it's a
worthwhile change.

Thanks,

jon

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

[Jonathan Corbet]

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

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

[Tomasz Warniełło]

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.