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]

[docbook] Re: formal objects in docbook 5


/ Stefan Seefeld <seefeld@sympatico.ca> was heard to say:
| docbook uses the term 'formal object' (or short 'formal') in a number
| of places to demark some elements. I couldn't find any clear definition
| of what it means for an element to be 'formal', other than that it has
| a title.

That's all it means.

| I then ran the first question of 'Some Open Questions' in http://norman.walsh.name/2003/05/21/docbook:
|
| "Is the distinction between formal/informal useful anymore?"
|
| What is the answer to this question in the context of the upcoming
| docbook 5 schema ?

DocBook NG still has both the formal and informal versions.

The odd man out in all this is equation which, for backwards
compatibility reasons in DocBook *4* still has an *optional* title,
even though there's also an informalequation element. I see two
possible ways forward:

  1. Keep the formal/informal distinction and make title on equation
     required. (This is what I've actually done in DocBook NG.)

  2. Drop the distinction, drop informal{equation,table,example,figure}
     and make title on all those elements optional.

Option 1 is probably easier for users and for tools, so I'm inclined
to go that way at the moment. The only advantage to option 2, really,
is that DocBook becomes four elements smaller. But the semantic
disjunction is probably too high a price to pay.

| The reason I'm asking is that I had come across situations where I would
| want a 'list of <A>', where <A> is any domain-specific artifact users
| could introduce. The current docbook DTD predefines (hard-codes) a set
| of such lists for some 'formal objects' (figures, say), though it is not
| clear to me what makes them special. In other words: what taxonomy leads to
| figures, equations, images to have the priviledge of being listable ?

Nothing but history. Lots of existing books provide lists of figures,
tables, examples, and equations. It would be reasonable to allow users
to select "list of X" for any X that had a title. In fact, we already
support list of procedures.

| 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.

| 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.
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.

| As docbook 5 is now in the making, I figured this is the best time to
| bring the topic up. Does the above make any sense at all ? Are there
| alternative ways to achieve the same with other (better) techniques ?

It's the perfect time, indeed.

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.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Resist the urge to hurry; it will
http://www.oasis-open.org/docbook/ | only slow you down--Bruce Eckel
Chair, DocBook Technical Committee |

Attachment: pgp00000.pgp
Description: PGP signature


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