[bug #62726] [me] intro manual: clarify available user namespace

[G. Branden Robinson]

Follow-up Comment #1, bug #62726 (project groff):


[comment #0 original submission:]
> doc/meintro.me.in
<http://git.savannah.gnu.org/cgit/groff.git/tree/doc/meintro.me.in> gives this
advice about naming user-defined macros: "In order to avoid conflicts with
names in -me, always use upper case letters as names.  The only names to avoid
are *TS*, *TH*, *TE*, *EQ*, and *EN*."
> 
> This is less than half the set of two-uppercase-letter macros -me defines,
but expanding the sentence to read "avoid EQ, EN, TS, TH, TE, PS, PE, PF, IS,
IE, IF, GS, GE, and GF; and also HX, LK, HR, LI, and DC if generating HTML
output" is awfully cumbersome.

This point is well-taken.  I have for quite a while been contemplating
_removing_ the auto-load of the _www_ macro package from the macro file for
the _html_ output device, however.  It stomps on the traditional name space
pretty hard, and I think for parity with other output devices it should be
less intrusive.

> doc/meref.me.in
<http://git.savannah.gnu.org/cgit/groff.git/tree/doc/meref.me.in> sidesteps
such a list by recommending any name containing at least one uppercase letter,
with the additional caveat "The names employed by any preprocessors in use
should also not be repurposed."  This simplifies the wording, but places more
burden on the user to know all the names used by his preprocessors, or even
that a preprocesor is invoked at all with -Thtml output.

Yes, but the name space pollution doesn't originate in _pre-grohtml_, but
_www.tmac_.

Nevertheless I agree that the situation is burdensome for the novice.
 
> This slight additional burden seems appropriate for readers of the reference
manual, but the intro manual targets novice users and should probably make no
assumptions about their level of knowledge.  So the full list of conflicting
names might make some sense here.  But it sure is ugly.
> 
> One could argue that a user using tbl will surely be aware of the small
number of tbl macros, and a user not using tbl should feel free to clobber
them.  But I feel that even novice users ought to be steered away from macros
that have established meanings, as that will make their documents easier for
others (or future, more knowledgeable versions of themselves) to later expand.
 (http://lists.gnu.org/r/groff/2013-09/msg00022.html has a cautionary tale
relevant to this.)
> 
> I'm open to suggestions on how to best handle this.  If no one (including my
future self) has any, I'll write a patch that will probably just have
meintro.me.in list all 19 claimed names.

I don't have any better ideas at present. :(


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?62726>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/