Re: [Quilt-dev] [patch 24/26] Wordsmith Files section.

[Jean Delvare]

On Sat, 16 Jun 2018 12:22:56 -0400, address@hidden wrote:
> * Give working tree example a name that looks more like an actual
>   software project's directory name.
> * Fix pronoun/antecedent agreement (multiple occurrences).
> * Tighten language (e.g., unnecessary use of "some").
> * Reorganize discussion of how quilt finds its rc file to proceed
>   strictly in the order attempted (I think--I didn't actually check the
>   source).

You got it right.

> * Leave breadcrumbs about EDITOR and LESS, which used to be part of this
>   discussion; add cross-reference to where the material is now.
> * Make explicit the fact that quilt command names need to be manually
>   up-cased for use in QUILT_COMMAND_ARGS.

I don't find it clear. In my opinion, the example provided is
sufficient to clarify the expected format, "in uppercase" does not add
value and even adds confusion.

> * Set configuration variable names in italics.
> * Make tagged paragraphs readable as paragraphs (try it aloud).

I'm still not happy with that. I have never seen it used anywhere else
and I find it harder to read.

> * Transform a popular Denglish construction into idiomatic English.
>   
> https://english.stackexchange.com/questions/85069/is-the-construction-it-allows-to-proper-english
> * Change "path", when not used in the sense of $PATH, to "file
>   specification"; this is a doomed, Quixotic effort of mine.

As said in a previous patch, I disagree with that change, it make
things confusing. Computer users know what a "file path" means, while
"file specification" I have never heard of before.

> * Clarify that "if set to anything" variables function as Booleans.
> * Recast "a shortcut to" as "shorthand for", which is more idiomatic
>   English in context.
> * Add cross-reference to diffstat man page on first occurrence.
> * Fix typo: each commands -> each command.

I'm fine with the other changes, some more comments inline below.

> Index: quilt/doc/quilt.1.in
> ===================================================================
> --- quilt.orig/doc/quilt.1.in
> +++ quilt/doc/quilt.1.in
> @@ -230,7 +230,7 @@ the default is \\[lq]\\-FRSX\\[rq].
>  .SH FILES
>  .SS "Example of working tree"
>  .EX
> -work/
> +project\\-1.2.3/

Changing "work" to "project" is fine, but I can't see the value of
adding an arbitrary version to it, especially at a time when versioned
directories are disappearing in favor of continuous integration.

>  ├── patches/
>  │    ├── series         (list of patches to apply)
>  │    ├── patch1.diff    (one particular patch)
> @@ -250,12 +250,12 @@ work/
>  The
>  .I patches
>  directory is precious as it contains all your patches as well as the
> -order in which it should be applied.
> +order in which they should be applied.

I noticed that one while reviewing the previous patches, thanks for
fixing it.

>  .PP
>  The
>  .I .pc
> -directory contains some metadata about the current state of your patch
> -serie.
> +directory contains metadata about the current state of your patch
> +series.

Ditto.

> (...)
>  .I quilt
>  shall pass to
> -.I diffstat
> +.BR diffstat (1)
>  when generating patch statistics.

I'm still confused as to when you use italics and when you use bold for
software names, but I guess you know what you're doing.

> (...)
> @@ -481,7 +504,7 @@ scripts, with the help of several other
>  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.
> +in the PDF documentation, and in the help messages of each command.

Should "message" not be singular as well?

>  .SH "SEE ALSO"
>  .I How to Survive with Many Patches, or: Introduction to Quilt
>  is installed at

Thanks,
-- 
Jean Delvare
SUSE L3 Support