[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Quilt-dev] [patch 24/26] Wordsmith Files section.
From: |
Jean Delvare |
Subject: |
Re: [Quilt-dev] [patch 24/26] Wordsmith Files section. |
Date: |
Tue, 26 Jun 2018 13:27:29 +0200 |
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
- [Quilt-dev] [patch 25/26] Make file tree diagram portable., (continued)
- [Quilt-dev] [patch 25/26] Make file tree diagram portable., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 26/26] Rewrite discussion of QUILT_COLORS configuration variable., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 19/26] Sort options in alphabetical order to ease human scanning., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 22/26] Wordsmith Exit Status section., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 24/26] Wordsmith Files section., g . branden . robinson, 2018/06/16
- Re: [Quilt-dev] [patch 24/26] Wordsmith Files section.,
Jean Delvare <=