Re: Comprehension problem with macros

[G. Branden Robinson]

At 2023-04-24T12:11:02+0100, Ralph Corderoy wrote:
> > > yes, I remember having heard of the two different modes
> >
> > "Copy mode" and (not copy mode), which didn't have a name in CSTR
> > #54.  (Terser is better.  :-| )
> 
> No name is needed.  It would be clutter to add it.  troff is either in
> copy mode or is not in copy mode.  There is no need for a not-copy
> mode term.

I disagree--there can be a need when the reader doesn't know which modes
implicate others.  Does nroff mode imply no-space mode?  Does fill mode
imply adjustment mode?  Does no-fill mode?  Is there only one adjustment
mode, or several?  Does nroff mode imply constant character width mode?
What about underline mode?  Does adjustment mode imply hyphenation mode?
Are all of these questions meaningful?  Can a novice tell which, if any,
are nonsensical?

Please don't _answer_ these.  I pose them for the benefit of people
other than you.

> There are quite a few modes in troff, e.g. ligature.

With this, I do agree.  One of these days I mean to assemble a table of
them since their variety is so bewildering.

> There isn't a special term for not being in ligature mode.  Creating a
> mode ‘bar’ to indicate the mode isn't ‘foo’ increases what needs to be
> learnt and remembered from one term to two terms and the relationship
> between them.

When your labels are "foo" and "bar", that's true.

As with variable naming, when one chooses identifiers that communicate
meaning, they can pay their freight.

I concede that this is a point lost on those who still name the
variables corresponding to their command-line option parser "cflag",
"xflag", "zflag", and so on.  I'm sure this is brilliant for a person
who wrote the code and remembers what all of the flags mean for that
particular application.

It's not for anyone new to the code.

Sustainable documentation, like sustainable code, is written for the
benefit of people other than author at their moment of maximum
familiarity with the work.

Regards,
Branden

signature.asc
Description: PGP signature