[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: DOCBOOK: Re: documenting an API: RFE
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 / Stefan Seefeld <seefeld@sympatico.ca> was heard to say: [...] | http://synopsis.sf.net | | , but up to now I have not been able to represent | the result adequately in docbook, so the tool only | provides formatters for other formats such as html, | texinfo, etc. What do you find lacking. Digging through the framed documentation provided at the SF site, I'm not sure what part you can't represent in DocBook. | I'v been looking into the available docbook markup | elements, but either the right elements are missing | or they are not really suitable for the purpose: | | I'd like to document types, variables, constants, | functions, etc. But while some of them seem to be | supported (there are elements for 'classsynopsis' | and similar), others are not. Here is a list of elements | I miss. I'd very much appreciate if others could either | confirm that there is nothing semantically similar, or | how I could document these things instead: | | * 'type' seems to name types, not describe them. What | about a 'typesynopsis' to actually define specific types ? Can you show me an example of what you'd like to put in a type synopsis? | * same for 'variable': what about a 'variablesynopsis' (or 'varsynopsis') ? | And, while we are at it: what is special about a 'field' | (docbook's name for 'member variables') ? If there was a | generic 'variable' element, couldn't 'fieldname' be considered | a specialized 'variable' (or then 'varname') ? I suppose. The funcsynopsis stuff was one of DocBook's few forays into modeling. After years of requests, we built a classsynopsis element to model object oriented languages in a similar way. As a general rule, we've tried to avoid modeling in DocBook and there are days when I wish we hadn't done either funcsynopsis or classsynopsis :-) | * again for 'constant': a 'constsynopsis' to contain constant definition What sort of definition? | * a 'modulesynopsis' to define 'contexts', 'scopes', 'packages' or | whatever this may be called in the various programming languages There's already an RFE for package markup. And a longstanding action item on me to investigate. The problem is that there many different, conflicting notions about what a package is. Examples of what you have in mind would be useful. Be seeing you, norm - -- Norman Walsh <ndw@nwalsh.com> | Truth lies within a little http://www.oasis-open.org/docbook/ | uncertain compass, but error is Chair, DocBook Technical Committee | immense. -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (GNU/Linux) Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/> iD8DBQE+byzQOyltUcwYWjsRAuK7AJ90HeadJLkb8ufj69+9PljiGGWzGgCfeuzj y66lpcMCJ9wejZFB1UpZjyw= =sH0Q -----END PGP SIGNATURE-----
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]