[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: multiple @syntax
From: |
Peter Simons |
Subject: |
Re: multiple @syntax |
Date: |
23 Jan 2005 12:29:20 +0100 |
Guido Draheim writes:
> I do have currently the impression that your parsers
> prefer to use multiple @syntax lines when adding multiple
> items.
Actually, my parser would report @syntax as an unknown tag.
> For the @category I was using a comma-seperated list
> which was working out quite well [...].
I would be curious to look at that. Could you point me to
one of the macros in the sf.net CVS repository that make use
of this feature?
> So, what do you think, adding a comma-seperated list for
> your parsers, and/or breaking the @cats into multiple
> lines in the (very rare) occasions where there are
> multiple category attributions?
I'm sorry, but I don't quite understand what you mean by
"breaking the @cats into multiple lines". Do you mean the
parser should allow multiple @category lines to be
specified?
> Next question, how about the "obsoletion" mark - we had
> that a few days ago - the gnu ac-archive oes currently
> contains 16 macros with my old style of "dnl obsoleted"
> attribution. Do we use "@obsoleted" next (as is my
> preference), keep with the in-document syntax, or add it
> to the list of @category attributions (adding up to the
> main category)
My preferred solution would be to have an "Obsolete"
category. A one-liner to describe why the macros has been
obsoleted should be added with the @summary tag, and all
other description just goes into the documentation without
any special mark-up. I am reluctant to define new tags (like
@obsoleted) right now because I have doubts that the
submitters will handle them right. Keep it simple always was
a motto of mine. ;-)
As an example, the obsolete macro AC_CHECK_CC_OPT would look
like this with proper markup:
dnl @synopsis AC_CHECK_CC_OPT(flag, cachevarname)
dnl @category Obsolete
dnl @summary use CFLAGS/CXXFLAGS related macros as soon as possible
dnl
dnl AC_CHECK_CC_OPT(-fvomit-frame,vomitframe) would show a
dnl message as like "checking wether gcc accepts
dnl -fvomit-frame ... no" and sets [...]
This way, the reason why a macro has been obsoleted is
readily visible on the index page -- you don't even have to
load the main page to see it. (Check out BNV_HAVE_QT on
gnu.org for an example of @summary usage.)
> Next question, how about an "experimental" mark - so
> these macros can be displayed as secondary on the website
> - just add to the @category listing?
I wouldn't mind adding an "Experimental" category, although
I still don't know what exactly makes a macro experimental.
IMHO, categories should help the _user_ to find things, and
"experimental" isn't a very useful description. IMHO, if a
macro is unstable or untested, then that would better be
pointed out in the _documentation_ than in its category.
> Next question, how to handle extra @syntax lines - is it
> ensured that they end up in the main documentation body?
I am sorry, but I don't know anything about @syntax. What is
that tag supposed to do?
> Is the main documentation body required to occur in one
> block or is it allowed to put extra @syntax lines
> anywhere in the main documentation block?
Tags and documentation can be mixed freely, the order in
which you specify things is not relevant.
Peter