Re: Macro Format

[Peter Simons]

Guido Draheim writes:

 > [The] current implementation uses abbreviations.

I'm not overly fond of keywords like '@,' and '@*' -- simply
because those abbreviations are very hard to remember if you
don't edit those macros everyday --, but I don't feel
strongly about that. Supporting them as abbreviations,
meaning: the verbose keywords still work, is fine by me.


 > @* (at-star) is abbrev for @synopsis with the extension
 >    of being allowed multiple times per macro.

 > @; (at-semi) is abbrev for @author with the extension
 >    of being allowed multipe times

Allowing multiple @synopsis and @author lines is definitely
a good idea. How does the generated HTML look for those? I'd
say,

  @synopsis AX_FOO(on)
  @synopsis AX_FOO(off)

translates to something along the lines of:

  <code>AX_FOO(on)</code><br/>
  <code>AX_FOO(off)</code>

and

  @author Joe Doe
  @author Jane Doe

becomes:

  Joe Doe, Jane Doe

How about e-mail addresses in the @author field? Right now,
I treat them as ordinary text; no <address>...</address>
markup or "mailto" link is generated for them. Is that worth
changing?


 > @! license info - to explicitly mark such a blurb which
 >    usually is put at the end of the documentation part

Is this free text? If, how do you handle licenses that don't
fit into one line?


 > @(c) makes it easier to write a copyright line that
 >    can be parsed out

Doesn't the copyright information repeat what the @author
field says already? If you have the authors and the macro's
license that should do the trick, or am I missing something?


 > @, (at-comma) is abbrev for @category which is actually
 >    the most important addition which I am using in some
 >    places

I have been thinking about making @category a mandatory
field (or: no @category == "misc") rather than using the
name of the directory the macro is in to determine that. The
reason simply being that this approach would allow to (a)
specify more than one category for a macro and to (b) change
a macro's categorization without moving the file in the CVS
tree.

 > It is also allowed to set an "obsolete" category here.

Exactly, all the categories mentioned in the policy document
could be implemented that way (including "experimental").

Another benefit is that by having a keyword for the
category, the macro author can choose himself how to
categorize his macro.


 >> [...] "autoconf-archive.tar.gz" doesn't have any
 >> configure script or installation mechanism right now,
 >> that's the part that I'd like to see adapted from the
 >> sf.net archive.

 > To just unpack an archive is the easy part - it must be
 > in a place that users and tools can find it. My
 > `acinclude` tool needs the parenting path and the
 > generated doc pages are registered in scrollkeeper (via
 > ac-archive-doc.omf). [...]

Well, that's why I was asking whether you would be willing
to adapt your existing setup. Our release archives differ
only in a few very minor details (the directories are called
differently), so I figure all the Autoconf and Makefile
stuff should be fairly simply to adapt?

I think it would be pretty nice if the user could say

  ./configure && make install

and get all macros and documentation installed.

Peter