Re: [Quilt-dev] [patch 13/26] Set filespecs and environment variable names in italics.

[Jean Delvare]

Hi Branden,

On Sat, 16 Jun 2018 12:22:45 -0400, address@hidden wrote:
> Variable content in an italic context is set in roman for contrast, but
> still in italics in running roman prose.

I'm a bit confused by this one, I will admit. Comments inline.

> Index: quilt/doc/quilt.1.in
> ===================================================================
> --- quilt.orig/doc/quilt.1.in
> +++ quilt/doc/quilt.1.in
> @@ -71,9 +71,7 @@ When not found in the current directory,
>  recursively in the parent directories (this is similar to the way
>  .I Git
>  searches for its configuration files).
> -The
> -.I patches
> -directory may contain sub-directories.
> +The patches directory may contain sub-directories.
>  It may also be a symbolic link instead of a directory.
>  .PP
>  A file called
> @@ -84,8 +82,8 @@ Unless there are means by which series f
>  automatically, it is usually provided along with a set of patches.
>  In this file, each patch file name is on a separate line.
>  Patch files are identified by path names that are relative to the
> -.I patches
> -directory; patches may be in sub-directories below this directory.
> +patches directory; patches may be in sub-directories below this
> +directory.
>  Lines in the series file that start with a hash character (#) are
>  ignored.
>  You can also add a comment after each patch file name, introduced by a

You start with removing italics from file names but there is no
explanations as to why you do that. Looks opposite to the spirit of
this patch?

> (...)
> @@ -176,14 +184,15 @@ This behavior is intended to ease the sc
>  In addition to that,
>  .I quilt
>  recognizes the following variables:
> -.IP EDITOR 4
> +.TP
> +.I EDITOR

The patch subject claims to put the environment variables in italics,
but for all I can tell, they already were. So whatever you are doing
here would need a justification, and seems to belong to a separate
patch. How is .TP + .I better than the more compact .IP form?

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

This sentence is removed completely. I guess your point is that this is
too obvious to be documented, and I don't disagree, but it has nothing
to do with this patch.

> -.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 \\[lq]\\-FRSX\\[rq].
> +.TP
> +.I LESS
> +The arguments used to invoke the
> +.BR less (1)
> +pager;
> +defaults to \\[lq]\\-FRSX\\[rq].

Another undocumented, off-topic removal.

> (...)
> -.IP QUILT_COLORS 4
> +.TP
> +.I QUILT_COLORS

After this patch, the alignment of this sub-section is incorrect. The
first 3 paragraphs have a left margin of (I think) 16, but starting
with the first example (diff_hdr), the left margin is down to 12.
Before this patch, it was all consistent at 12.

> (...)
> -is installed at @DOCSUBDIR@/quilt.pdf.
> +is installed at
> +.IR "@DOCSUBDIR@/\\:quilt.pdf" .

For my own education, what is the purpose of the "\\:"? It does not
seem to make any difference.

-- 
Jean Delvare
SUSE L3 Support