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

[Dave]

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

[comment #3 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.


    _______________________________________________________

Reply to this item at:

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

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