comment #3:

> Not true!

Thank you for dispelling (a small portion of) my ignorance.

> With man pages (both man(7) and mdoc(7)) we have hyperlink
> support both for PDF and terminal output devices.

Yes; I should have clarified my original comment here was confined to output generated by grohtml.

> Consequently people can put hyperlinks to Internet URLs in
> their me(7) documents today.  The downside is that they
> have to input \X escape sequences to do it, and this seems
> to scare most *roff users

It may be partly that, and partly that the user has to have a broad base knowledge before they can even tackle it, needing to know (a) that this is even possible; (b) that \X is what makes it possible; (c) how to use \X; and (d) what to put in \X for the specific device.  The -me Reference Manual, due to its vintage, mentions HTML output once, in passing (a recent addition to the description of .bx), and doesn't mention \X at all, even in its list of troff escapes that -me users can feel free to use.  So for -me users a fifth thing would be (e) that \X is safe to use in -me, a fact which is undocumented altogether, rather than requiring the synthesis of various other documents that (a) through (d) do.  Upshot, this is power-user territory; a less experienced user is likely to first reach for the www macro set.

> I speculate that www.tmac was originally conceived as a
> supplementary macro package for any full-service package.

This is, essentially, still its modern-day purpose, too, since--as something (presently) autoloaded during HTML processing--it has to work with every full-service package.

And, other than the namespace pollution, that's a reasonable design.  For that matter, said pollution isn't a necessary part of the design (or, at least, needn't have been when it was first developed; we may be stuck with it now); as an auxiliary package, it really ought to have sequestered its macros into an easily recognizable namespace (e.g., prefixed with "WWW-").

> But the advent of mandoc and its community's insistence on a
> greatly reduced subsetting of the input language for the sake
> of portability (and concealment of mandoc's own limitations) has
> already taken man pages out of www.tmac's application domain.

Sure, but man pages have many dissimilarities with most other *roff documents, and in recent years have striven to make that divide starker.  I don't expect that what's good for the man-goose is good for the non-man-gander (if you'll pardon my gender conflation).

> I wonder if perhaps it would be better for other full-service
> packages to just go ahead and add extension macros for the
> features they want.

I don't see how this would be better for either developers or users.  For developers, it would be a huge DRY violation.  (There's already a lot of that in the classical packages, many of which use different syntax and independently written code to accomplish the same basic page-layout tasks, but that's all legacy infrastructure.)  For users, it makes knowledge of those macros transferable from one full-service macro set to another--not that many users seem to actively use more than one such package, but it does help in the support realm, where a -me user needing help with an HTML-specific question can draw upon the knowledge of all www.tmac users, not just those confined to her own -me sphere.

> I think this is the more polite thing to do, to avoid such a
> squat on the available portable name space.

I wonder how feasible it would be to mass-deprecate all the macro names www.tmac currently defines and, going forward, use revised names that conform to a recognizable pattern.  (This drastic change, obviously, would need wider community input.)  Still, it would be years before support for the existing macro names could be removed, whereas just removing the www autoload could be done immediately.

comment #2:

> comment #1:
> > 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.
>
> OK, I may as well wait and see where you land on that bigger issue before spending any more time on this minuscule one.

It is of course possible to use the HTML output device as a kind of weird terminal, or a somewhat dumb typesetter.  One of the things I want to do is clearly establish what those capabilities are.

> Regardless of whether the www macros are autoloaded, it sure seems like any document wanting to take any real advantage of HTML functionality--hyperlinks being the most basic and obvious example--will require them.

Not true!

Consider two practical examples recently demonstrated.

With man pages (both man(7) and mdoc(7)) we have hyperlink support both for PDF and terminal output devices.

As recently shown with my re-typesetting of Kernighan & Cherry's eqn user's guide, with a ONE-LINE patch to K&C's private `SC` sectioning macro, we have clickable links to sections in the navigation pane.  Under the original definition of a hyperlink as I understand it, text you can poke your finger on to "go" to the referenced material is exactly what this is.

Internet URLs do demand specialized support.  man(7) and mdoc(7) already have macros to support those and do so in HTML, PDF, and terminal output; they don't need to load the 'www' package to get it.

The means of access to this type of feature is the device control command, and the recognition of such commands by the output driver program is where the magic really happens.

Consequently people can put hyperlinks to Internet URLs in their me(7) documents today.  The downside is that they have to input \X escape sequences to do it, and this seems to scare most *roff users (they did me backed when I signed on to join this navy).

I speculate that www.tmac was originally conceived as a supplementary macro package for any full-service package.  But the advent of mandoc and its community's insistence on a greatly reduced subsetting of the input language for the sake of portability (and concealment of mandoc's own limitations) has already taken man pages out of www.tmac's application domain.

I wonder if perhaps it would be better for other full-service packages to just go ahead and add extension macros for the features they want.  In some cases even that isn't necessary: as seen with the porting of K&C's paper to gropdf(1), if a work title or author name is well-behaved input-wise, it can be shoved into document metadata verbatim.

Having a stronger `troff` request to sanitize any diversion, string, or macro of node data is a feature that I am increasingly coming to think is both feasible and desirable.  Think, instead of "asciify", "utf8ify".  Anything that can be back-converted to ASCII or a UTF-8 sequence (not forgetting that our old friends the hyphen-minus, caret, tilde, etc. are not ASCII unless remapped) is, and everything else is thrown out.

I relatedly think that arguments to the `tm` family of requests (including `ab`) should be similarly handled.  I think it would be significant effort for little benefit to add general localization support for troff output to the standard error stream.  That is, I don't want troff to have to care whether the environment uses Latin-1 or Latin-9 or Unicode.  So the argument(s) to these requests would be scooped into a temporary anonymous troff string and then "utf8-sanitized" as described above, then re-emitted.   As a first cut I wouldn't even inspect the environment, but just blast out the bytes in UTF-8 and if somebody's terminal encoding ain't that, they get mojibake.

I seem to have wandered onto the topic of Debian #906091...

>  Still, forcing the user to explicitly specify this macro package means the only users who do so will be ones using macros from it, so they should know what macros it defines and be able to avoid those.

I think this is the more polite thing to do, to avoid such a squat on the available portable name space.

original submission:

> 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 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. :(