OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[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]