Re: Macro Format

[Guido Draheim]

Peter Simons wrote:
> 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.

The abbrevs were largely taken to allow compatibility with
the gnu archive which is ignorant to the long names - the
lines of the marks are going to presented in the main
documentation part where those @-blurbs have no meaning
to the human eyes - they just look like formatting errors
of some kind ;-)=)

> 
> 
>  > @* (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?

There is nothing special about these lines - the lines are
just concatenated and formatted as if being one line. It's
just that the old tools did choose an either-or tactic when
seeing multiple lines which was a kind of limitation. The
tool just extends it to multiple lines - it does not inspect
the content all too heavily. Simplicity rules - of course
one can expand on that and get to parse the content of the
lines for micro syntax.

> 
> 
>  > @! 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?

It's a quite time that I was working on these parts of the
gendocs - the last thing was about getting the categorization
pages right with all the obsoletion stuff. I do not see any
specialty in the code about it, so I guess it comes out as
plain text on the other end. No micro syntax, no index
tables - i.e no list of authors and their macros, no list of
license and copyright blurbs, etc ... skipped until now. It
can be added of course, but.

> 
> 
>  > @, (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.

Exactly, I do currently have copies in the cvs - just with
some clever "sync" scripts the thing can be kept sane.

> 
>  > 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.

Yepp.

> 
> 
>  >> [...] "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?

A matter of taking over makefile rules. However, the gnu
ac-archive does not have any build files at them moment
so there is no place to add anything anyway.

> 
> I think it would be pretty nice if the user could say
> 
>   ./configure && make install
> 
> and get all macros and documentation installed.
> 

Yepp.

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