Re: DOCBOOK: Info on FuncSynopsis

[Norman Walsh <ndw@nwalsh.com>]

/ Bernd Kreimeier <bk@lokigames.com> was heard to say:
| After a long break from SGML I am now staring at the official
| book in order to write up our API specifiction. I am stuck
| at the announced v4.0 changes to FuncSynopsis. Am I mistaken
| in expecting
| 
|       <funcsynopsis><funcprototype> 
|       <funcdef>void<function>Listener{n}{sifd}{v}</function></funcdef>
|       <paramdef>&enum;<parameter>param</parameter></paramdef>
|       <paramdef>&type;<parameter>values</parameter></paramdef>
|       </funcprototype></funcsynopsis>
| 
| to work with 3.x and 4.0 both?

No, that'll work in both. What got removed from 4.0 was the ability
to have funcdef and friends directly in funcsynopsis without the
intervening funcprototype.

| I would also appreciate a clarification on FuncSynopsisInfo. 
| The examples in book (copied in at least on FAQ) of
| 
|    #include <varargs.h>
| 
| seems really weird to me. This is a requirement, not
| (additional) info.

Funcsynopsisinfo is just a bag to put other stuff in. And while
it's true that the #include is not strictly part of the
synopsis, it isn't uncommon (in Unix manpages at least) to
include this information in the synopsis.

| Further, I am at a loss on how to
| actually specify the parameters, return values, and
| purpose of the function within FuncSynopsis. I currently
| maintain a separate table that lists the text and
| description for parameters, plus their legal values/range, 
| default value. Am I missing the right way to integrate 
| actual specification text with FuncSynopsis?

There's currently no way to integrate the text into the
funcsynopsis.  But I'd be interested in seeing any proposals for
doing so.

| Further: I maintain internal comments "marked" as RFC, NOTE,
| REF that can be exempt using 
|  <![ IGNORE [
| Are there DocBook elements or attributes I should use to 
| mark such optional "meta"-content? For internal purposes
| these would ideally be printed with e.g. a different color
| or framed - some way to distinguish them from the actual
| document.

<remark> in DocBook 4.0, perhaps. (or <comment> in 3.x.)

| p.s.:
|   http://www.oasis-open.org/docbook/
| has news to Apr 10,
|  http://www.docbook.org/
| only till Feb 17 - no mirror also it claims so.
| Why two different  sites anyway?

One's the official site for DocBook: TDG, the other is the
official DocBook TG site.

| Finally, the mailing list page does not mention archives?

It needs to be updated. I've just been swamped. See 
http://xml.org/archives/docbook and http://xml.org/archives/docbook-apps

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | O for a Muse of fire, that would
http://www.oasis-open.org/docbook/ | ascend / The brightest heaven of
Chair, DocBook Technical Committee | invention, / A kingdom for a
                                   | stage, princes to act / And
                                   | monarchs to behold the swelling
                                   | scene!--William Shakespeare, Henry
                                   | V