Re: [Quilt-dev] [patch 20/26] Wordsmith Description section.

[Jean Delvare]

On Sat, 16 Jun 2018 12:22:52 -0400, address@hidden wrote:
> * Introduce "unapplied" as a piece of jargon, since it is used that way.

I object. Associating "unapplied" with "reversed" is causing more
confusion than it solves in my opinion. Firstly because it makes the
user think that quilt is calling "patch -R" on the patch file, while
"quilt pop" is technically restoring the original files from a backup.
Secondly because a "revert" command actually exists, which does
something completely different from the "pop" command.

Removing the hyphen is fine though.

> * Don't end a sentence with an abbreviation period if possible (also,
>   man-pages(7) discourages the use of Latin abbreviations altogether).
> * Users of quilt are not merely outputting patches; they are consuming
>   them and altering them as well.
> * Clarify the (shall we say) truncability of command names.
> * Use directional double-quotes instead of boldface to set off literals.
>   Some typographers claim that frequent font face changes tire the eye.
> * Offer an example of a patch name.
> * Introduce the "quilt series" command in the same paragraph the series
>   file itself is first described, to eliminate forward reference.
> * Introduce quilt command names only once each.
> * Add a paragraph summarizing the work cycle for starting and refining a
>   new patch.

I'm fine with all that. A few comments inline below:

> (...)
> -Patch files are identified by path names that are relative to the
> +Patch files are identified by file specifications relative to the

I don't like that change. This is the first time I see "file
specifications" used for that purpose, and without the context I would
think of something completely different. What's wrong with "path names"?

> (...)
>  Different series files can be used to assemble patches in different
> -ways,
> -corresponding for example to different development branches.
> +ways, corresponding (for example) to different development branches.

I wonder if this would not be the right place to promote guards(1)?

> (...)
> +Later, when a patch is regenerated (\\[lq]quilt refresh\\[rq]), the
> +backup copies in
> +.IR .pc/ patch-name
>  are compared with the current versions of the files in the source tree
>  using GNU
> -.IR diff .
> +.BR diff (1).

Are you sure? This goes in the opposite direction of patch 11
"Italicize work titles".

> (...)
> +After editing, inspect the impact of your changes.
> +The current state of the patch can be examined (\\[lq]quilt diff\\[rq]);
> +a refresh updates it to incorporate the edits you have made.

"current state of the patch" is ambiguous. "quilt diff" shows the
current differences to the backup, which can differ from the
differences stored in the top-most patch file (hence the need to
"refresh" it.) This last sentence must be rewritten to make it clearer.
Maybe something like:

The current changes can be examined (\\[lq]quilt diff\\[rq]);
the changes stay local to your working tree until you call
\\[lq]quilt refresh\\[rq] to write them to the patch file.

Thanks,
-- 
Jean Delvare
SUSE L3 Support