[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: documenting an API: RFE
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 / Stefan Seefeld <seefeld@sympatico.ca> was heard to say: | Norman Walsh wrote: | |> | 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): |> You can certainly create indexes in DocBook (by adding indexterm |> elements). And you could easily generate special-purpose indexes by |> gathering together the definitions that you markup in your sources. | | Sorry, I totally missed the automatic index generation when reading your (online) | book. The examples on the <index> element all fill the index explicitely with | <indexentry>, that made it look inappropriate for my purposes. Right. I think you want to generate some additional index terms from other markup, perhaps implicitly. I wasn't suggesting that you need to markup all your cases with indexterm explicitly. | I don't really understand what you mean with 'gathering together the definitions'. | I'd like to classify those 'indexterms' such that I could generate an index | for a specific class. | |> | Using this scheme, I would like to have categories such as 'types', |> <type> | | My impression was that <type> is to be used to mark up a word within a text. | What I'm after is some structure such as a 'term' / 'synopsis' pair, i.e. | a formal definition (of types, in this case). Given that this is agnostic | to programming languages, I'd like to provide some attribute that gives | the language specific name of the type, i.e. the 'meta-type', such as | 'class', 'typedef', 'enum' (in C++) to name just a few. I'm sorry, I'm obviously being clueless. Can you provide some concrete examples? Just make up the element names you think you need. I simply don't understand what you're looking for yet. |> | 'concepts', 'requirements', 'patterns', etc., and then just use |> These look more like section headings or something to me. | | Indeed, they could be. But they may as well not. I'm trying to find a way | to mark an element in a way that doesn't impose any specific substructure, | yet allows me to recognize that this is a 'requirement' definition (say). | For example http://www.bredemeyer.com/pdf_files/UseCase_Template.PDF I'm offline at the moment, so I can't look at the example. | proposes a table as a 'use case template'. I'd like to provide similar | templates for this and other artifacts that occur in the software development | process, using docbook. For now, I'm using '<variablelist role="usecase">, | and I wrote special xslt templates (and of course css styles) for all the | different output media I'd like to support (html and fo, notably). If variablelist suits your needs, that seems like a fine approach to me. | So the question I have is: is this the right approach ? Could it be done | in better ways, a) within the current docbook vocabulary, and b) could | docbook itself be enhanced to better support this. | Again, I'd like to be able to generate an index for all 'use cases' (say). | Or, if a toc is more suitable, a 'toc'. [...] | Put differently, what is necessary (with or without changes to the docbook | dtd/schema) to be able to index all type definitions in the document (whether | classes, functions, enums, whatever). I don't think I can offer any enhancement suggestions until I understand your needs better. Be seeing you, norm - -- Norman Walsh <ndw@nwalsh.com> | My problems start when the smarter http://www.oasis-open.org/docbook/ | bears and the dumber visitors Chair, DocBook Technical Committee | intersect.--Steve Thompson, | wildlife biologist at Yosemite | National Park -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (GNU/Linux) Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/> iD8DBQE+iefmOyltUcwYWjsRAkCJAJ0czMchKUZNes4vpLG0VAD782YboACgn2GX 3vcN8Wg4WAKhgKmJsDoypTY= =zf5e -----END PGP SIGNATURE-----
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]