Re: multiple @syntax

[Peter Simons]

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