This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [docbook] Re: formal objects in docbook 5


Norman Walsh wrote:

| Isn't such a property more like an annotation similar to the way indexes
| are generated using <indexterm> instead of an intrinsic type (whether it can
| be inferred or not) of some elements ?

Well, the List of Titles format seems to me to presuppose that all the
elements are "the same" and all the elments have a title.

For list-of generation something like a title is indeed be needed. But I'm thinking of more functionality one could add on top of docbook, i.e. an extended semantic model to track such artifacts.

There exist very expensive commercial tools to let software developers document
their development process, e.g. make sure all requirements are followed up on
in terms of design specs, etc., etc.

I didn't find the tools I have seen so far satisfying at all, and so I'm
wondering what it would take to reimplement it. As I said, for me 'requirement'
is merely a markup on top of the existing docbook vocabulary. No structural
constraints (or almost) as to what a requirement should look like (that's
best left up to the people who would work with the tool).
All I need is a way to track requirements, i.e. track their versions, perform
some validation, etc.

| I'd like to write documents that contain software engineering artifacts
| such as 'requirements' or 'use cases'. All I want is the ability to
| annotate existing docbook elements (such as variablelist, paragraph,
| or even section) to mark them as being a requirement in a way that
| allows me to track them, i.e. generate lists of requirements, set up
| special links between requirements and 'specifications' with a particular,
| domain-specific semantics, etc., etc.

The markup would be easy, you could just use the "role" attribute.

Ah well, I had hoped that docbook ng becomes more easy to extend, and thus the famous 'role' attribute would be slowly phased out.

But how would you want to present this:

  <para role="requirement">The product must be <emphasis>both</emphasis>
  a floor wax <emphasis>and</emphasis> a dessert topping. Our research
  shows that consumer are tired of having to make this semantically
  challenging decision every time they go to the super market.</para>

:-)


in a "List of Requirements"? I don't see any easy way to pull out a
title or other "title".
If you stick to things that hae titles (varialblelists, sections,
etc.) then a "List of Requirements" would be fairly easy to produce.

Good. We had a similar discussion around 'index', where I suggested to add a classifier attribute to generate multiple indexes in an attempt to generalize 'index'.

Using DocBook for requirements documents, use cases, and similar sorts
of application development documentation has come up before. On the
one hand, it seems odd that DocBook doesn't have any markup
specifically designed to help people mark these things up, on the
other hand, there is astonishing variety in the shape and size of
documents produced for this purpose and it may be that no specific
markup would have critical mass.

Indeed, I have seen quite a variety of templates to be used for 'requirements'. That's precisely why I'm now thinking of this kind of markup as an annotation *on top* of the docbook content model, instead of a handful of new elements. That way there is little the processing logic has to impose on a documents structure to be able to do its work.

Regards,
		Stefan

PS: FWIW, I find the 'readyset' project at http://readyset.tigris.org/
    quite intriguing, but I think it should be done with docbook, not
    xhtml :-)


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]