Mike Bianchi wrote:
On Wed, Feb 03, 2010 at 02:08:47PM -0500, Larry Kollar wrote:
:
This actually brings up something that has been bugging me for a
while,
and I think deserves its own thread: we should come up with some
namespace guidelines for macro packages, especially for internal-use
macros, to prevent conflicts. Whatever we agree on could go in the
texinfo document.
Yes, please. I would very much like that conversation.
I'm willing to transform the mm macros to whatever we agree upon.
It seems like this is a popular idea, so I'm changing the Subject
line to make it easier to find in the archives later on.
Looking at popular packages, there already are some unwritten
conventions: for example, any macro name in ALL-CAPS is usually meant
to be called by users (-me and -mdoc are the only major packages that
consistently violate that "rule").
Further, the various *.tmac packages seem to fall into two groups:
1) Primary packages (-ms, -mm, -man, -mdoc, -me) -- these packages
can often be used with no other packages, and aren't combined with
each other.
2) Support packages (-mwww, -mhdtbl, -mpdfmark, etc) -- these
packages add useful functionality to the primary packages, but for
the most part can't be relied on alone to format most kinds of
documents. For elaborate documents, several of these may be called
upon to work in conjunction with a primary package.
This simplifies matters somewhat -- it means we really need only
focus on namespaces for *support* packages. For example, the -ms and
-mm packages could both define a "foo" macro that does completely
opposite things, but it doesn't matter because I can't think of a
situation where you'd want to use them both at once. (You might want
to follow an -ms document with a series of -man documents, but that's
another can of worms that would require some low-level work in the
formatter. Worth talking about, but as a separate discussion.)
Besides, retrofitting namespaces into primary packages may break
documents that call low-level macros to fix a particular issue --
we're not supposed to do it, but we do (and I'll admit, you'll find
an occasional "....@reset" in my documents).
So there are two situations where we run into namespace conflicts:
1) A support package attempts to do something that one or more other
packages already support. A good example is the ".SP" macro in
hdutil.tmac, renamed to "t*SP" this afternoon. ;-) A non-accumulating
space macro would be a useful addition to -ms, but it's already in -
mm. Another one is ".LI" in -mwww, which (as we saw a couple weeks
ago) conflicts with the ".LI" definition already in -mm.
2) Support packages provide similar (or completely different)
functions, using a name common to either primary or support packages,
especially at a low level. Namespace-ing primary packages would help,
but IMO it should be the responsibility of the support package (and
its maintainers) to use unique names at both high and low levels.
That leaves us with the nature of the namespaces themselves. The -
mwww macros, and my own -ms hacks, use "xxx:name" where "xxx" is
unique to the package; for example "www:paraspace." The hdtbl macros
partially use "t*name." I'm not married to the colon, although both
XML and C++ use it -- so it would be immediately recognizable by many
people. The thing is, we left the two-character limitation behind a
long time ago, so there's little reason *not* to use descriptive
names (and namespaces) especially at a low level.
OK, I've held forth long enough. Time for others to add their two
cents/pfennings. ;-)
-- Larry