Re: Bold and italics, semantics and constness (was: [PATCH v2] mctp.7: Add man page for Linux MCTP support)

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi, Branden!

On 11/22/21 10:06, G. Branden Robinson wrote:
>>> Phrasal semantic newlines!  :D  This 180-proof Kernighan whiskey is
>>> a stronger prescription than I would write (mainly because it
>>> requires natural-language-aware grepping), but if your contributors
>>> don't rebel, I think we will all ultimately see the benefits in
>>> diffs.
>>
>> I feel an urge to add it to man-pages(7).  :-}
> 
> I saw that.  I don't object, exactly, but I would be prepared for some
> contributors to simply disregard it.  Some man pages are going to be
> more excellent than others.  man-pages(7) calls out wait(2) and pipe(2)
> as models, for example.

So far, only one rebelled a bit.  I assume that I'll be fixing those few 
pages myself.  If this advise reduces the amount of work that I have to 
do, it's useful.  If some contributors learn to appreciate the benefits 
of thinking in terms of phrases when writing technical stuff, it will 
have been very useful.

> 
> I think in many cases this Kernighanization of man page running text is
> going to fall to you because contributors will feel it unnecessary or
> that they cannot justify to their managers the expenditure of the time
> necessary to write documentation so scrupulously.  I would agree that it
> can improve man page quality--attention to phrase and clause boundaries
> compels the writer to re-read what they write and may reveal to them
> gaps in the discussion or outright errors.

Those that would complain about phrases I think would also complain 
about clauses.  It's the same switch for the brain, just a bit further. 
  If they prefer to maintain the man-pages with looser rules, they can 
do themselves; no-one's paying me for reviewing their patches.  I'll 
keep doing this, as long as it's entertaining to me.  If managers don't 
want to spend worker's time in writing quality pages, I may ask some 
salary for my time reviewing their pages.

> 
> But documentary diligence is not part of the culture of much software
> development these days.  It's not Lean/Agile/XP/MVP.  Documentation is a
> cost center.  It's the opposite of secret sauce.  What will please the
> Street?  Move fast; break stuff; be far away when the building catches
> on fire.

I have had a very bad (and luckily short) experience with 
Lean/Agile/XP/MVP.  If I can help sabotage that, I will happily and 
intentionally do.


>>>> Only for Branden:  I just noticed a difference between
>>>> man-pages(7) and groff_man(7) advise:  groff_man(7) advises to use
>>>> italics for preprocessor constants, while man-pages(7) recommends
>>>> bold:
> [...]
>>> Would we then also bold constants that are C objects with the
>>> "const" type qualifier rather than language literals emplaced by the
>>> preprocessor?
>>
>> Yes!  The difference between "const" variables and macros is just
>> preprocessor, but they are all intended for very similar usage.
> 
> Hmm, yes, but personally I wouldn't mind it if we had a notation that
> distinguished preprocessor symbols from things the compiler proper sees.
> With only 3 faces in man(7), we probably can't get there from here, but
> I have dreams of a better world.  A Texinfo partisan would likely point
> out that the distinction is already made clear in the GNU C Library
> manual, for example.

Are we talking about libc, or C documentation in general?  Because libc 
doesn't have any 'const' variables at all, at least that I know of.

So we don't even need to care in the Linux man-pages.  Maybe manual 
pages for other C libraries can better decide what to do with those.



>> We have a mapping in our brains that says
>> "literal -> bold, variable -> italics".
> 
> I don't think I will ever be able to suppress my need to point out that
> this is a _loose_ generalization.  Italics are also used for emphasis
> and work titles in standard English.
> 
>> If we extend that mapping,
>> macros are replacements for literals,
>> so we would use bold for them too.
>> And "const"s are also mostly intended for the same use as macros,
>> so bold goes for them too.
> 
> But constness can be cast away; and some C library functions that
> _should_ take const-qualified parameters or return const-qualified
> objects, don't (and worse, got standardized without such qualifiers
> either out of excessive deference to poor practice or for fear of
> upsetting too many implementors).  So you might mislead the reader who
> assumes that a C object in bold type is always const-qualified, leading
> them to perform superfluous casts, which make the code noisier to read.
> Or you might mislead the reader who assumes that a C object in bold type
> is always "semantically" to be treated as "const" (i.e., don't assign to
> objects of this name even if you can without provoking a compiler
> complaint) might make the opposite false and overgeneralized inference,
> and fail to apply "const" where it would be useful.

I think we're talking about 2 different things:

- 'const' variables
- pointers to 'const'

'const' variables can never be cast away.  It's an error.

$ cat const.c
void foo(void)
{
	const int a = 1;

	a = 2;
}

That will never compile, and you can't cast 'a' enough so that you can 
make it work.  If you modify it through a pointer to 'const', then you 
can, but it will be Undefined Behavior, which brings us to the other 
thing: pointers to 'const'.

$ cat pointer_to_const.c
void bar(const int *p)
{
	int *q;

	q = (int *)p;
	*q = 3;
}

This is allowed by the compiler, but it is Undefined Behavior _unless_ 
the variable pointed to by 'p' is really not const.  Casting away const 
is IMO also braindamaged, so I don't consider it a valid thing.

One of the things that I like from C++ is that they correctly 
implemented const.  Hey, "asd" is 'char *' in C, but of course if you 
modify it, demons fly out of your nose!


Going back to formatting:

Pointers to const are just variables.  Their value is the address of 
some const, but that's not important.  The important thing is that they 
are variables, and therefore, you use italics with them.

So the only thing that IMHO should be bold (apart from constants and 
macros that expand to constants) should be global 'const' variables:

const int FOO = 3;

which some people prefer over macros, and which in C++, one could write as:

constexpr int FOO = 3;

In the case above, I don't see a reason why one would want to 
differentiate that from say

#define FOO  3


But in function parameters, 'const' is useless in variables, since they 
already got a copy, so they won't alter the original.  And in pointers, 
const applies to the pointee, but the pointer itself is variable, so 
italics.


>> Did I convince you? :)
> 
> No, but not for lack of trying.  :)  I don't think there is much
> distance between us, practically speaking.

No there isn't. :)

> I guess I should mention...I didn't announce it here, but groff 1.23.0
> will have a new "MR" macro for man page cross references[2] and its
> grotty(1) driver will emit OSC 8 hyperlink escape sequences to
> supporting terminal devices for clickable URLs and man page cross
> references declared with "MR".[3]

OMG, those HTML people better be scared of competition :D

> 
> I reckon groff is due for another release candidate...

Yes, please :-)


Cheers,
Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/