[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: DOCBOOK: Re: documenting an API: RFE
Hi Norman, hoping that this thread simply got lost in your pile of mails (instead of landing in your waste basket :-), I'll try another one to show what kind of enhancements I'd like to see in docbook: Norman Walsh wrote: > | 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? As you don't want to make docbook a modeling language, there is, as you admit, not much value in emphasizing individual modeling specific artifacts such as 'classes' (and thus 'classsynopsis'). So if we think for a moment about all 'modeling-artifact' related markup being stripped off, it all boils down to a refentry or similar. However, it would be wonderful to still preserve a way to group or classify refentries, albeit not necessarily in a fixed (hardcoded) way. What I'm thinking of is something similar to texinfo, and its way to deal with indices (http://www.gnu.org/manual/texinfo-3.9/html_node/texinfo_137.html): Indices are generated for elements that are marked for a particular index. That basically means all such entities are classified for specific (predefined as well as user-defined) categories, and then a special command triggers the generation of an index for a particular category. Using this scheme, I would like to have categories such as 'types', 'functions', 'variables', 'concepts', 'requirements', 'patterns', etc., and then just use refentries to actually describe all the individual items (with embedded 'synopsis' elements). In fact, having a) a generic container that I can associate a user-defined 'type' with (such as 'concept', 'type', 'requirement') to hook up specific templates in the output generating xsl [*] b) a means to generate indexes per category Would be fairly enough, and I believe make some of the elements that go into the modelling direction (funcsynopsis, classsynopsis, etc.) obsolete. Does some of this make any sense ? Kind regards, Stefan [*] may be a 'generic container' isn't going to be a solution. May be an attribute would do the job. But the famous 'role' doesn't seem to be enough, if only because it's not preserved in the generated output in all cases.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]