URL:
<https://savannah.gnu.org/bugs/?62726>
Summary: [me] intro manual: clarify available user namespace
Project: GNU troff
Submitter: barx
Submitted: Fri 08 Jul 2022 07:27:13 PM CDT
Category: Macro me
Severity: 1 - Wish
Item Group: Documentation
Status: None
Privacy: Public
Assigned to: None
Open/Closed: Open
Discussion Lock: Any
Planned Release: None
_______________________________________________________
Follow-up Comments:
-------------------------------------------------------
Date: Fri 08 Jul 2022 07:27:13 PM CDT By: Dave <barx>
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.
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.
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.
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?62726>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
