Re: [PATCH v2] docs: add a FAQ

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Mar 25, 2020, 11:03 UTC
Message-ID: <20200325110328.GK6499@camp.crustytoothpaste.net>
In-Reply-To: <CAN0heSofpxFW81=sB+4ukx9S0JOJo_XuKDTBSkTy_-QK+jDz0Q@mail.gmail.com>

On 2020-03-25 at 06:23:49, Martin Ågren wrote:

Show 7 quoted lines

> On Wed, 25 Mar 2020 at 02:37, brian m. carlson
> <sandals@crustytoothpaste.net> wrote:
> > Note that the long lines for certain questions are required, since
> > Asciidoctor does not permit broken lines there.
> > ---
> 
> Missing sign-off.

Thanks, will fix.

Show 7 quoted lines

> > +You can also just enter your password when prompted, or you can place the
> > +password (which must be percent-encoded) in the URL.  The latter option is not
> > +particularly secure and can lead to accidental exposure of credentials, so it is
> > +not recommended.
> 
> So should we even mention it? Or should we use the "it is sometimes
> (erroneously) suggested" construct?

I'll rephrase this to make it a little more obvious that this is a bad idea.

Show 7 quoted lines

> > +Most hosting providers use a single SSH account for pushing; that is, all users
> > +push to the `git` account (e.g., `git@git.example.org`).  If that's the case for
> > +your provider, you can set up multiple aliases in SSH to make it clear which key
> > +pair to use.  For example, you could write something like the following,
> > +substituting the proper private key file:
> 
> Would this be in `~/.ssh/config`?

Ah, yes, we should tell that to the user.

Show 12 quoted lines

> > ++
> > +----
> > +# This is the account for author on git.example.org.
> > +Host example_author
> > +       HostName git.example.org
> > +       User git
> > +       # This is the key pair registered for author with git.example.org.
> > +       IdentityFile ~/.ssh/id_author
> > +       IdentitiesOnly yes
> > +# This is the committer for author on git.example.org.
> 
> Looks like you did s/account/committer/ instead of s/author/committer/?

So I did.

Show 7 quoted lines

> > +
> > +[[last-commit-amend]]
> > +I've made a mistake in the last commit.  How do I change it?::
> > +       You can make the appropriate change to your working tree, run `git add
> > +       <file>` or `git rm <file>`, as approrpiate, to stage it, and then `git
> 
> typoed "appropriate"

Will fix.

Show 20 quoted lines

> > +[[restrict-with-hooks]]
> > +How do I prevent users from making certain changes with hooks?::
> 
> I read this as:
> 
>   How do I prevent users from making "certain changes with hooks"?
> 
> As opposed to your intended meaning:
> 
>   How do I (with hooks) prevent users from making certain changes?
> 
> I'm not suggesting the latter as a "fix" for this "problem" though,
> since it's a bit clumsy. How about adding a comma:
> 
>   How do I prevent users from making certain changes, with hooks?
> 
> Or maybe just dropping those last two words.
> 
> Please trust your judgement on whether this is a problem, and if so, how
> to go about addressing it -- I know you have lots of such judgement.

How about, "How do I use hooks to prevent users from making certain changes?" That seems to both read smoothly and avoid the misplaced modifier.

Show 5 quoted lines

> > +Cross-Platform Issues
> > +~~~~~~~~~~~~~~~~~~~~~
> 
> I think you meant to use "--" as everywhere else instead of "~~". This
> is not a subsection of "Hooks".

Ah, yes. Apparently my fonts are so small that these are hard to distinguish with bright white on grey. I typically use the Setext style in my own documents, but that isn't what we do in Git.

> > +To do so, you can specify a linkgit:gitattributes[5] pattern with with the
> 
> "with with"

Ah, normally Vim flags those things.  Will fix.

Show 8 quoted lines

> > +[[windows-diff-control-m]]
> > +I'm on Windows and git diff shows my files as having a `^M` at the end.::
> > +       By default, Git expects files to be stored with Unix line endings.  As
> > +       such, the carriage return (`^M`) that is part of a Windows line ending
> > +       results is show because it is considered to be trailing whitespace.  Git
> 
> "results is show"? "is shown"? Perhaps with a comma after "shown" for
> better reading flow (IMVHO).

This should be "is shown". I'm not sure if a comma after "shown" is grammatical here as it stands, but I think we could write "is shown, since" and that would be okay. I'll check a reference and rephrase if necessary.

Show 6 quoted lines

> > +       defaults to showing trailing whitespace only on new lines, not existing
> > +       ones.
> 
> > +We also recommend setting a link:gitattributes[5] file to explicitly mark which
> 
> s/link:/linkgit:/

Will fix.

-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204