[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Macro Format
From: |
Guido Draheim |
Subject: |
Re: Macro Format |
Date: |
Tue, 18 Jan 2005 02:16:02 +0100 |
User-agent: |
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.2) Gecko/20040906 |
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+@>+++
- Re: bnv_have_qt: QT_CXXFLAGS should contain -DQT_THREAD_SUPPORT if needed, Peter Simons, 2005/01/14
- Re: bnv_have_qt: QT_CXXFLAGS should contain -DQT_THREAD_SUPPORT if needed, Bastiaan Veelo, 2005/01/14
- Message not available
- Re: bnv_have_qt: QT_CXXFLAGS should contain -DQT_THREAD_SUPPORT if needed, Peter Simons, 2005/01/15
- Re: bnv_have_qt: QT_CXXFLAGS should contain -DQT_THREAD_SUPPORT if needed, Guido Draheim, 2005/01/15
- Macro Format (was: bnv_have_qt: QT_CXXFLAGS ...), Peter Simons, 2005/01/15
- Re: Macro Format, Guido Draheim, 2005/01/15
- Re: Macro Format, Peter Simons, 2005/01/17
- Re: Macro Format, Guido Draheim, 2005/01/17
- Re: Macro Format, Peter Simons, 2005/01/17
- Re: Macro Format,
Guido Draheim <=
- Re: Macro Format, Braden McDaniel, 2005/01/15
- Re: Macro Format, Alexandre Duret-Lutz, 2005/01/15
- Re: Macro Format, Peter Simons, 2005/01/16