On Sat, Jul 08, 2023 at 02:48:50PM +0200, Omar Polo wrote:
> On 2023/07/08 07:37:12 -0400, Josh Rickmar <jrick@zettaport.com> wrote:
> > On Sat, Jul 08, 2023 at 07:30:47AM -0400, Josh Rickmar wrote:
> > > To make cvg diffs less ugly...
> > 
> > Sorry, find/replaced in the wrong order when started editing the
> > original got.1 file. 
> 
> regardless of the discussion about cvg / got scope and whatnot, since
> you wrote the diff +1 for me to get this on.  I've used a similar
> pattern in some circumstances.  IMHO ".Cm got foo" to indicate the
> "foo" subcommand is misleading since only "foo" would be a "command
> modifier".

This is subjective of course, but I don't agree that this approach
works well in all cases. Where it doesn't work it relies too much
on markup to convey meaning. And that seems like a bad idea to me.
Sentences in our documentation should make sense without any markup.

Consider someone fresh to the software, reading this text without
seeing any markup:

"Without the -m option, import opens a temporary file ..."

Which sounds strange because "import" is a verb, not a noun.
Without context this sounds like the author of the docs made an error.

We are already stretching the English language by using "got" as a
proper noun which can likewise result in horrible sentences. But at
least readers will be able to anticipate "got" being used as a noun,
given the name of the page they are reading.