[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: Info on FuncSynopsis
/ 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC