Re: Macro Format

[Guido Draheim]

Peter Simons wrote:
> Guido Draheim writes:
> 
>  > Well, I was extending the orginal submission format a bit
>  > to allow more meta-information to be added - they all
>  > just take the @format.
> 
> What extensions did you make? How does your formatter differ
> from the one I originally wrote? (Or in other words: What
> features would I have to add here to understand all inputs
> your formatter does?)

I was trying hard to ensure that any macro can be easily
pushed into the gnu ac-archive - unmodified. The orginal
idea of adding more @format strings with an alphalettered
keyword did seem too intrusive to my eyes. Therefore the
current implementation uses abbreviations.

@* (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
@! license info - to explicitly mark such a blurb which
   usually is put at the end of the documentation part
@(c) makes it easier to write a copyright line that
   can be parsed out
@, (at-comma) is abbrev for @category which is actually
   the most important addition which I am using in some
   places

Without any specifics a macro has a default category
being derived from the subdirectory name - just as it
used to be - but the at-comma allows to explicitly set
a primary category and optionally one can extend it
with a series of secondary categories separated by
comma (that's why the abbrev uses at-comma). It is
also allowed to set an "obsolete" category here.

In order to maintain maximum compatibility, the parser
can also see "dnl obsoleted[:\s] marks which imposes
a default category of "obsoleted" no matter where the
macro was found. The categorisation part is so important
that I was even going to use an extra hint file outside
of the m4 source where extra category hints can be set
just so that I do not need to modify the original macro
text.

Along with those primary and secondary category hints
I am implementing the life cycle attribution as it was
discussed a while back. Essentially, there are those
user macros at the ac-archive that are implied to be
"experimental" and an "obsolete" hint is forcebly the
primary category with the original ones becoming all
secondary. The result of this processing can be seen
at http://ac-archive.sourceforge.net/C_Support/index.html
which has "live" macros at the top, followed by some
"experimental" additions and closed by hints to macros
marked as "obsoleted".

> 
> 
>  > When speaking about packaging we should think it to be
>  > more in terms of "third-party" developers like distro
>  > makers that tend to download a source tarball, add some
>  > configure hints and patches as needed for their distro,
>  > and go to install/pack them.
> 
> Well, they can! It's just that "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. It would be nice to provide RPMs too.
> 

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). I do
suggest to use `autoconf` so that users get a standard way
to specify a "--prefix" and allowing it to patch some
acinclude.in or GNUmakefile.in with the target locations.
At the moment there is not even a single makefile in the
gnu ac-archive that shows how the "obscure" autoconf-archive.tar.gz
is coming into existance - it could be anything out of your system.

The sfnet presentation system, on the other hand, has extensions
like: presenting macros per category, building a inverted index
for searching by keyword, add info blurb on the right side per
category (pointing back to gnu for gnu categories and hinting
about the author for the experimental stuff) - and the acinclude
tool will see "obsoleted" hints and warn about it while updating
a project with the latest in ac-archive macro content without
knowing much about the presentation. The build system has been
distinctly been made in a way that everyone can pick up the
ac-archive content, add his own experimental subdirectory and
start rebuilding. To help keep a third-party cvs in sync there
are a series of `make sync` targets around (running `make sync`
just shows a help page). Plus all the doc install and rpm
building is a small deed in comparison for the rest of the
automatisms.

have fun,
-- guido                                  http://google.de/search?q=guidod
GCS/E/S/P C++/++++$ ULHS L++w- N++@ s+:a d(+-) r+@>+++ y++ 5++X- (geekcode)