DOCBOOK: Re: Which element should be used as a status ?

[Frédéric Glorieux <fglorieux_aweb@mailhub.isdnet.net>]

Thanks a lot, very nice of you. May I continue (in spite of my English)? This
will be only semantic questions, usually effect of ignorance, in hope they are
not out of subject. 

> Since DocBook is about software documentation

I understand the goal, but you also know that not specific software project
prefers use docbook than other DTDs (TEI ?), for some reasons wich are
 - your reactivity
 - software support
 - your xsl tools
 - all your well structured types like bibliography, index, footnotes ...

You also understand that users could be glad to have expressed support of
their needs (a named element), to stay close to the generic tools, instead of
schema redefinition or proprietary attributes. That's why I will try to defend
my opinion, in the idea of _ software documentation_.

> I often use a legalnotice as a
> kind of status in *info elements (with an appropriate role). There's
> also an attribute to show the publication status.

To my opinion, <status/> make a nice type with <abstract/> and <audience/> to
qualify a section (%descobj.class; ???). Example
<section>
	<title>Advanced functionalities</title>
	<abstract>Description of the software advanced ... </abstract>
	<audience>Power users</audience>
	<status>This is only a draft ...</status>

(in this partial example,  <caution/>, <important/>, <note/>, <tip/> or
<warning/> may be used with precised instructions to redactors in replacement
of a <status/>)

This could be of general interest.


About an inline structure <concept/>, <samp/> or <definition/>

> You can use indexterm to mark index terms, but DocBook doesn't have
> the notion of an inline concept. The catch-all for things like this is
> phrase with a role attribute.
> Programlisting or screen or literallayout are common choices.

This is of course the specific software understanding of example. To express
more precisely my idea, is this correct? 

<para>
<phrase role="definition"><xref linkend="schema"/>A <phrase role="concept"
id="schema">Schema<indexterm><primary>Schema</primary></indexterm></concept>
give a structure to a document.</phrase> For example, <phrase
role="example"><xref linkend="schema"/>a book is an ordered collection of
chapters</phrase>.
</para>

In replacement of this lighter tagging
<para>
<definition ref="schema">A <concept id="schema">Schema</concept> give a
structure to a document.</definition> For example, <example>a book is an
ordered collection of chapters</example>.
</para>
Procession expectations: 
concepts are _not_ suppressed in the primary text flow, they contribute to the
population of an index with related definitions and examples. If no id/ref
provided, definitions and examples could be automatically related to a concept
in the same block. 

I'm afraid this is not well structured enough to be of general interest. But
perhaps someone else have better ideas.