[Groff] Toward a convention for namespaces

[Larry Kollar]

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 "address@hidden" 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