[Quilt-dev] [patch v2 02/26] Man page: eliminate or replace blank lines

[Jean Delvare]

Blank lines are bad roff style.  Per CSTR #54, blank lines are the
equivalent of ".sp 1", but in GNU roff this can be overridden with a
blank line macro (".blm"), and all macro packages for text formatting
(mm, ms, me, man, etc.) have macros for paragraph separation, and the
inter-paragraph spacing is usually different from ".sp 1" for typesetter
output (this can be seen in PostScript and PDF output).  Explicit
spacing is also unnecessary immediately adjacent to section headings.

See section 5.3 of CSTR #54, "Troff User's Manual", Ossanna & Kernighan
<https://www.troff.org/54.pdf>.

[JD: Added an empty request (.) before each section to preserve the
 readability of the input.]
---
 doc/quilt.1.in |  114 +++++++++++++++------------------------------------------
 1 file changed, 31 insertions(+), 83 deletions(-)

--- quilt.orig/doc/quilt.1.in   2022-07-05 11:49:09.051202552 +0200
+++ quilt/doc/quilt.1.in        2022-07-05 13:42:41.655833591 +0200
@@ -1,26 +1,26 @@
 .\\" Created by Martin Quinson from the tex documentation
 .\\"
 .TH quilt 1 "Dec 17, 2013" "quilt"
-
+.
 .SH NAME
 quilt \\- tool to manage series of patches
-
+.
 .SH SYNOPSIS
 .B quilt
 [-h] command [options]
-
+.
 .SH DESCRIPTION
 Quilt is a tool to manage large sets of patches by keeping track of the
 changes each patch makes. Patches can be applied, un-applied, refreshed,
 etc. The key philosophical concept is that your primary output is patches.
-
+.PP
 With quilt, all work occurs within a single directory tree. Commands can be
 invoked from anywhere within the source tree. They are of the form
 .B quilt cmd
 similar to CVS, svn or git commands. They can be abbreviated as long as the 
specified
 part of the command is unique. All commands print some help text with
 .B quilt cmd -h.
-
+.PP
 Quilt manages a stack of patches. Patches are applied incrementally on top
 of the base tree plus all preceding patches. They can be pushed on top of
 the stack
@@ -34,7 +34,7 @@ see below), the contents of the stack
 and the patches that are not applied at a particular moment
 .RB ( "quilt next" , " quilt unapplied" ).
 By default, most commands apply to the topmost patch on the stack.
-
+.PP
 Patch files are located in the
 .I patches
 sub-directory of the source tree (see EXAMPLE OF WORKING TREE below). The
@@ -47,7 +47,7 @@ searches for its configuration files). T
 .I patches
 directory may contain sub-directories. It may also be a symbolic link
 instead of a directory.
-
+.PP
 A file called
 .I series
 contains a list of patch file names that defines the order in which patches
@@ -68,10 +68,10 @@ by a space followed by a hash character.
 quilt adds, removes, or renames patches, it automatically updates the series
 file. Users of quilt can modify series files while some patches are
 applied, as long as the applied patches remain in their original order.
-
+.PP
 Different series files can be used to assemble patches in different ways,
 corresponding for example to different development branches.
-
+.PP
 Before a patch is applied (or ``pushed on the stack''), copies of all files
 the patch modifies are saved to the
 .RI .pc/ patch
@@ -82,19 +82,19 @@ the backup copies in
 .RI .pc/ patch
 are compared with the current versions of the files in the source tree using
 GNU diff.
-
+.PP
 Documentation related to a patch can be put at the beginning of a patch
 file.  Quilt is careful to preserve all text that precedes the actual patch
 when doing a refresh. (This is limited to patches in unified format; see
 .B diff
 documentation).
-
+.PP
 The series file is looked up in the .pc directory, in the root of the source
 tree, and in the patches directory.  The first series file that is found is
 used. This may also be a symbolic link, or a file with multiple hard links.
 Usually, only one series file is used for a set of patches, so the
 patches sub-directory is a convenient location.
-
+.PP
 The .pc directory and its sub-directories cannot be relocated, but it can be
 a symbolic link. While patches are applied to the source tree, this
 directory is essential for many operations, including taking patches off the
@@ -104,42 +104,33 @@ 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
-
 @REFERENCE@
-
+.
 .SH COMMON OPTIONS TO ALL COMMANDS
-
 .IP \"\\fB--trace\\fP\" 8
-
 Runs the command in bash trace mode (-x). For internal debugging.
-
 .IP \"\\fB--quiltrc\\fP file\" 8
-
 Use the specified configuration file instead of ~/.quiltrc (or
 /etc/quilt.quiltrc if ~/.quiltrc does not exist).  See the pdf
 documentation for details about its possible contents.  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
-
 The exit status is 0 if the sub-command was successfully executed, and
 1 in case of error.
-
+.PP
 An exit status of 2 denotes that quilt did not do anything to complete
 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
-
 .fam C
 .RS
 .nf
@@ -161,22 +152,20 @@ work/
 .fi
 .RE
 .fam T
-
+.PP
 The patches/ directory is precious as it contains all your patches as
 well as the order in which it should be applied.
-
+.PP
 The .pc/ directory contains some metadata about the current state of
 your patch series. 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.
-
+.
 .SH CONFIGURATION FILE
-
 Upon startup, quilt evaluates the file .quiltrc in the user's home
 directory, /etc/quilt.quiltrc if the former file does not exist, or
 the file specified with the --quiltrc option.  This file is a regular
@@ -184,33 +173,25 @@ bash script. Default options can be pass
 a 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. A useful setting for C source code is "-p", which causes GNU diff
 to show in the resulting patch which function a change is in.
-
 .IP QUILT_PATCH_OPTS 4
-
 Additional options that quilt shall pass to GNU patch when applying
 patches.  For example, recent versions of GNU patch support the
 "--reject-format=unified" option for generating reject files in unified
 diff style (older patch versions used "--unified-reject-files" for that).
-
+.IP
 You may also want to add the "-E" option if you have issues with quilt
 not deleting empty files when you think it should. The documentation of
 GNU patch says that "normally this option is unnecessary", but when patch
@@ -219,139 +200,106 @@ empty files from deleted files, patch de
 -E option is given. Beware that when passing -E to patch, quilt will
 no longer be able to deal with empty files, which is why using -E is
 no longer the default.
-
 .IP QUILT_DIFFSTAT_OPTS 4
-
 Additional options that quilt shall pass to diffstat when generating
 patch statistics. For example, "-f0" can be used for an alternative output
 format. Recent versions of diffstat also support alternative rounding
 methods ("-r1", "-r2").
-
 .IP QUILT_PC 4
-
 The location of backup files and any other data relating to the current
 state of the working directory from quilt's perspective. Defaults to ".pc".
-
 .IP QUILT_PATCHES 4
-
 The location of patch files, defaulting to "patches".
-
 .IP QUILT_SERIES 4
-
 The name of the series file, defaulting to "series". Unless an absolute path
 is used, the search algorithm described above applies.
-
 .IP QUILT_PATCHES_PREFIX 4
-
 If set to anything, quilt will prefix patch names it prints with their
 directory (QUILT_PATCHES).
-
 .IP QUILT_NO_DIFF_INDEX 4
-
 By default, quilt prepends an Index: line to the patches it generates.
 If this variable is set to anything, no line is prepended.  This is
 a shortcut to adding --no-index to both QUILT_DIFF_ARGS and
 QUILT_REFRESH_ARGS.
-
 .IP QUILT_NO_DIFF_TIMESTAMPS 4
-
 By default, quilt includes timestamps in headers when generating patches.
 If this variable is set to anything, no timestamp will be included.  This
 is a shortcut to adding --no-timestamps to both QUILT_DIFF_ARGS and
 QUILT_REFRESH_ARGS.
-
 .IP QUILT_PAGER 4
-
 The pager quilt shall use for commands which produce paginated output. If
 unset, the values of GIT_PAGER or PAGER is used.  If none of these variables
 is set, "less -R" is used.  An empty value indicates that no pager should be
 used.
-
 .IP QUILT_COLORS 4
-
 By default, quilt uses its predefined color set in order to be more
 comprehensible when distiguishing various types of patches, eg.
 applied/unapplied, failed, etc.
-
+.IP
 To override one or more color settings, set the QUILT_COLORS variable in
 following syntax - colon (:) separated list of elements, each being of the
 form <format name>=<foreground color>[;<background color>]
-
+.IP
 Format names with their respective default values are listed below,
 along with their usage(s).
 Color codes(values) are standard bash coloring escape codes.
 See more at http://tldp.org/LDP/abs/html/colorizing.html#AEN20229
-
 .RS 4
 .IP \\fBdiff_hdr\\fP 10
 Used in 'quilt diff' to color the index line. Defaults to 32 (green).
-
 .IP \\fBdiff_add\\fP 10
 Used in 'quilt diff' to color added lines. Defaults to 36 (azure).
-
 .IP \\fBdiff_mod\\fP 10
 Used in 'quilt diff' to color modified lines. Defaults to 35 (purple).
-
 .IP \\fBdiff_rem\\fP 10
 Used in 'quilt diff' to color removed lines. Defaults to 35 (purple).
-
 .IP \\fBdiff_hunk\\fP 10
 Used in 'quilt diff' to color hunk header. Defaults to 33 (brown/orange).
-
 .IP \\fBdiff_ctx\\fP 10
 Used in 'quilt diff' to color the text after end of hunk header (diff 
--show-c-function generates this). Defaults to 35 (purple).
-
 .IP \\fBdiff_cctx\\fP 10
 Used in 'quilt diff' to color the 15-asterisk sequence before or after a hunk. 
Defaults to 33 (brown/orange).
-
 .IP \\fBpatch_fuzz\\fP 10
 Used in 'quilt push' to color the patch fuzz information. Defaults to 35 
(purple).
-
 .IP \\fBpatch_fail\\fP 10
 Used in 'quilt push' to color the fail message. Defaults to 31 (red).
-
 .IP \\fBseries_app\\fP 10
 Used in 'quilt series' and 'quilt patches' to color the applied patch names. 
Defaults to 32 (green).
-
 .IP \\fBseries_top\\fP 10
 Used in 'quilt series' and 'quilt patches' to color the top patch name. 
Defaults to 33 (brown/orange).
-
 .IP \\fBseries_una\\fP 10
 Used in 'quilt series' and 'quilt patches' to color unapplied patch names. 
Defaults to 0 (no special color).
-
 .RE
 .RS 4
 In addition, the \\fBclear\\fP format name is used to turn off special
 coloring. Its value is 0; it is not advised to modify it.
-
+.PP
 The content of QUILT_COLORS supersedes default values. So the value
 diff_hdr=35;44 will get you the diff headers in magenta over blue
 instead of the default green over unchanged background. For that, add
 the following content to ~/.quiltrc (or /etc/quilt.quiltrc):
-
+.PP
 .nf
   QUILT_DIFF_ARGS="--color"
   QUILT_COLORS='diff_hdr=35;44'
 .fi
 .RE
-
+.
 .SH AUTHORS
-
 Quilt started as a series of scripts written by Andrew Morton
 (patch-scripts). Based on Andrew's ideas, Andreas Gruenbacher completely
 rewrote the scripts, with the help of several other contributors (see
 AUTHORS file 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
-
 The pdf documentation, which should be under @DOCSUBDIR@/quilt.pdf.
 Note that some distributors compress this file.
 .BR zxpdf ( 1 )
 can be used to display compressed pdf files.
-
+.PP
 .BR diff ( 1 ),
 .BR patch ( 1 ),
 .BR guards ( 1 ).