Re: [Quilt-dev] [patch 04/26] Reorganize sections to use only section names endorsed by man-pages(7), and put them in the recommended order.

[Jean Delvare]

On Sat, 16 Jun 2018 12:22:36 -0400, address@hidden wrote:
> Use subsection macro (SS) where helpful.

That one is harder to review...

> 
> Index: quilt/doc/quilt.1.in
> ===================================================================
> --- quilt.orig/doc/quilt.1.in
> +++ quilt/doc/quilt.1.in
> @@ -112,9 +112,9 @@ and refreshing patches
>  .RB ( "quilt refresh" ).
>  Files in the .pc directory are automatically removed when they are
>  no longer needed, so there is no need to clean up manually.
> -.SH QUILT COMMANDS REFERENCE
> +.SS Quilt commands reference
>  @REFERENCE@
> -.SH COMMON OPTIONS TO ALL COMMANDS
> +.SH OPTIONS

I understand the rationale for renaming the section, however the
information "common to all commands" is lost in the process, while I
believe it was valuable (in contrast with all options listed under
"Quilt commands reference", which are command-specific.) I think it
should be reintegrated as an introduction message before the first
option.

>  .IP \"\\fB--trace\\fP\" 8
>  Runs the command in bash trace mode (-x).
>  For internal debugging.
> @@ -125,7 +125,7 @@ See the pdf documentation for details ab
>  The special value \"-\" causes quilt not to read any configuration file.
>  .IP \"\\fB--version\\fP\" 8
>  Print the version number and exit immediately.
> -.SH EXIT STATUS
> +.SH "EXIT STATUS"
>  The exit status is 0 if the sub-command was successfully executed, and
>  1 in case of error.
>  .PP
> @@ -134,7 +134,18 @@ the command.
>  This happens in particular when asking to push when the whole stack is
>  already pushed, or asking to pop when the whole stack is already popped.
>  This behavior is intended to ease the scripting around quilt.
> -.SH EXAMPLE OF WORKING TREE
> +.SH ENVIRONMENT
> +In addition to that, quilt recognizes the following variables:

After the move, it is no longer clear what "to that" refers to. The 2
environment variables are in fact a complement to all the variables
which can be set in quiltrc files. They are listed separately because
they are not quilt-specific.

Given that these are actually independent from the rest, my
recommendation would be to simply drop the "In addition to that,".

> +.IP EDITOR 4
> +The program to run to edit files.
> +If it isn't redefined in the configuration file, $EDITOR as defined in
> +the environment will be used.
> +.IP LESS 4
> +The arguments used to invoke the pager.
> +Inherits the existing value of $LESS if LESS is already set in the
> +environment, otherwise defaults to "-FRSX".
> +.SH FILES
> +.SS "Example of working tree"

I don't believe that the example working tree belongs to the FILES
section. EXAMPLE is listed as an allowed section name in man-pages(7),
so why not just use that?

Also note that somewhere else in the man page is a pointer to this
part, under the form "see EXAMPLE OF WORKING TREE below." Notice the
use of capitals. As these capitals will be gone after your rework, the
pointer should be adjusted accordingly.

>  .fam C
>  .RS
>  .nf
> @@ -166,9 +177,7 @@ Changing its content is not advised.
>  This directory can usually be regenerated from the initial files and the
>  content of the patches/ directory (provided that all patches were
>  regenerated before the removal).
> -.SH EXAMPLE
> -Please refer to the pdf documentation for a full example of use.

You are dropping this line completely. I know that the pdf
documentation is mentioned later in the "SEE ALSO" section, but there
the "example" keyword is missing. We really want to point users looking
for concrete examples to that pdf documentation. So either the
statement above must stay, or the description under "SEE ALSO" must be
extended to state that the pdf documentation includes a full example of
use.

> -.SH CONFIGURATION FILE
> +.SS "Configuration file"
>  Upon startup, quilt evaluates the file .quiltrc in the user's home
>  directory, or the file specified with the --quiltrc option.
>  This file is a regular bash script.
> @@ -177,15 +186,6 @@ QUILT_${COMMAND}_ARGS variable.
>  For example, QUILT_DIFF_ARGS="--color=auto" causes the output of quilt
>  diff to be syntax colored when writing to a terminal.
>  .PP
> -In addition to that, quilt recognizes the following variables:
> -.IP EDITOR 4
> -The program to run to edit files.
> -If it isn't redefined in the configuration file, $EDITOR as defined in
> -the environment will be used.
> -.IP LESS 4
> -The arguments used to invoke the pager.
> -Inherits the existing value of $LESS if LESS is already set in the
> -environment, otherwise defaults to "-FRSX".
>  .IP QUILT_DIFF_OPTS 4
>  Additional options that quilt shall pass to GNU diff when generating
>  patches.
> @@ -319,7 +319,7 @@ in the distribution).
>  .PP
>  This man page was written by Martin Quinson, based on information found
>  in the pdf documentation, and in the help messages of each commands.
> -.SH SEE ALSO
> +.SH "SEE ALSO"
>  The pdf documentation, which should be under @DOCSUBDIR@/quilt.pdf.
>  Note that some distributors compress this file.
>  .BR zxpdf ( 1 )

It is getting late here, so I'll review the remainder of this patch
series tomorrow.

-- 
Jean Delvare
SUSE L3 Support