Re: [RFC PATCH v1 01/13] doc: typeset command-line options in monospace

From: Firmin Martin <firminmartin24@gmail.com>
To: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: Git Users <git@vger.kernel.org>
Subject: Re: [RFC PATCH v1 01/13] doc: typeset command-line options in monospace
Date: Sat, 10 Apr 2021 03:12:44 +0200	[thread overview]
Message-ID: <87r1jjgcxf.fsf@Inspiron.i-did-not-set--mail-host-address--so-tickle-me> (raw)
In-Reply-To: <8a44cb3d-d1ce-a3dc-82da-69a65d5baac2@gmail.com>

Hi Bagas,

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On 09/04/21 11.02, Firmin Martin wrote:
>>   help.browser, web.browser and browser.<tool>.path
>>   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   
>>   The `help.browser`, `web.browser` and `browser.<tool>.path` will also
>>   be checked if the 'web' format is chosen (either by command-line
>> -option or configuration variable). See '-w|--web' in the OPTIONS
>> +option or configuration variable). See `-w`|`--web` in the OPTIONS
>
> Why not `-w | --web`?

Good question.

There are multiple justifications:
- The "|" is a meta-character not included in the option name.
- If you run
      grep -Pn "'.*\|.*?'" *.txt
  under the Documentation/ directory, you will notice that we have
  already done something like this, but in italic:
  - In git-rerere.txt's Synopsis: `git rerere` ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']
  - In gitremote-helpers.txt: 'option dry-run' {'true'|'false'}:
- That is exactly what "man man" or some other man pages do (e.g. "man
  tar"). Of course, some man pages do not follow this convention
  (e.g. "man 7z").

Best,

Firmin

>
> -- 
> An old man doll... just what I always wanted! - Clara