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

[Dave]

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/