At 2023-03-12T06:23:33+0100, Helge Kreutzmann wrote:
> Hello Alex,
> On Sun, Mar 12, 2023 at 12:31:05AM +0100, Alejandro Colomar wrote:
> > On 3/11/23 18:13, Helge Kreutzmann wrote:
> > > Without further ado, the following was found:
> > >
> > > Issue: mountd(8) → B<mountd>(8)
> >
> > We don't use that formatting in example code.
>
> I think I saw it elsewhere, but then probably from one of our ~ 100
> other projects.
>
> (And again, for hyperlinking etc. I think it can be helpful; I just
> checked, even with formatting I can simply copy that code out - so
> there is not disadvantage?)
I don't have anything quantitative for you, but my impression from my
own readings in software is that generally, in typeset material, code
comments don't indulge in much style variation. They might be set
uniformly in a slanted face, or in proportional typeface where the code
proper is monospaced, but not much beyond that.
Also, I think having URLs in code comments in documentary examples is
typographically dangerous. In examples, filling is (usually) off, and
URLs can get long, so the risk of oversetting the output line is
greater. You also don't know how wide the user's terminal is going to
be. On top of that, groff man(7) permits the user to configure the
"standard indentation amount".
-rIN=standard-indentation
Set the amount of indentation used for ordinary paragraphs (.P
and its synonyms) and the default indentation amount used by
.IP, .RS, .TP, and the deprecated .HP. See subsection
"Horizontal and vertical spacing" above for the default. For
terminal devices, standard-indentation should always be an
integer multiple of unit "n" to get consistent indentation.
These factors combine to make it hard to judge how much room you're
going to have for your code examples.
So I would avoid putting URLs in example comments.
In fact, I could counsel against any code comments in examples at all,
unless they're so short that they don't increase the total width of the
example.
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature
