DOCBOOK: re procedure example

[Terry Allen <tallen@sonic.net>]

Please do not munge Reply-To!

Sabine Ocker wrote:
| Hello again!
| 
| A week or so ago I posted the message below to this list in the 
| hopes of starting a discussion on possible alternative usage suggestions.
| 
| It was mentioned to me that fellow docbook users may find some sample
| markup helpful in providing feedback about our proposed solution for
| the Sun writers. What follows is both a sample of the current workaround
| I mentioned in my original posting as well as data marked as we've proposed
| in RFE#145.
| 
| Sample of how we work around it now:
| 	
| <sect1>
| <title>Creating Concatenations</title>
| <para>Do not use this procedure on an existing file system or 
| data.</para>
| 
| <sect2 role="procedure">
| <title>How to Create a Concatenation</title>
| <procedure>

I don't see how the sect2 helps your workaround.  You
haven't said clearly what problem you're working around; as your
example is full of elisions, I can't learn much from
its content, and I can only assume that you want to keep 
everything you show here together.

| <step>
| <para>Check the prerequisites (<xref linkend="addtasks-20933">) 
| and the preliminary information.</para>
| </step>
| <step>
| <para>To create the concatenation from the Solaris Management 
| Console</para>
| </step>
| <step>
| <para>To create the concatenation from the command line, use the 
| following form of the metainit command:</para>
| </step>
| </procedure>
| 
| <sect3>
| <title>Where To Go From Here</title>

It seems to me that this should be outside the procedure,
because it's not part of the procedure (I guess, not knowing
the full content of the procedure or this section), but a piece
of info related to the procedure (and thus properly appearing
in parallel hierarchy within the same sect1 container).  Suppose 
the "Where to Go From Here" applied to a set of 3 procedures?  
You wouldn't want to put it in any one of the procedures.

| <para>Information for the IA archtecture is different.</para>
| </sect3>
| </sect2>
| </sect1>

Now your proposed solution:

| Sample of how we want to do it:
| 
| <sect1>
| <title>Creating Concatenations</title>
| <para>Do not use this procedure on an existing file system or 
| data.</para>

I don't see why *that* para doesn't belong within the procedure.

| <procedure>
| <title>How to Create a Concatenation</title>
| <procedure>

That second start tag must be a typo for a sect2 (all examples should
be parsed ...).

| <step>
| <para>Check the prerequisites (<xref linkend="addtasks-20933">) 
| and the preliminary information.</para>
| </step>
| <step>
| <para>To create the concatenation from the Solaris Management 
| Console</para>
| </step>
| <step>
| <para>To create the concatenation from the command line, use the 
| following form of the metainit command:</para>
| </step>
| 
| <simplesect>
| <title>Where To Go From Here</title>
| <para>Information for the IA archtecture is different.</para>
| </simplesect>
| </procedure>
| </sect2>
| </sect1>

More below.

| Michael Smith, can you please elborate upon the comments you posted
| earlier on why you don't think this will work?
| 
| Thanks everyone!
| Sabine Ocker
| 
| ---------------------------------------------------------------------	
| Hello fellow Docbook users!
| 		
| Sun Microsystems has proposed a change to the Docbook DTD which would 
| allow additional material after the last step in a procedure. Specifically,
| the writers have a need for a Titled Section within Procedure after any

not a need, a desire, until the need is explained.

| Steps--which is useful for related "Examples" as well as "Where to go 
| from Here" or "See Also" information. 
| 		
| Because this Section should have structure but an end point in the 
| Section heirarchy, we'd like to use SimpleSect. and extend the content
| model of Procedure to include it.

Unclear.

| We have internal requirements which don't allow us to include optional 
| Titles, and that's why Bridgehead doesn't quite work.

See next.

| We can't use Example because authors may reference other sort of information,
| as is mentioned above.

Unclear.  You CAN use example within a step, but you cannot put 
anything after a step within a procedure.  So even Bridgehead
won't do what you really want to do.  I think you are asking to expand
procedure to include comments (including simplesect) at the end,
before the end tag for procedure.  I also think your example fails
to support your request, but perhaps you can provide a better,
real one.

Here's how I would mark it up:

<?xml version="1.0"?>
<!DOCTYPE sect1 SYSTEM "c:\home\bin\xml\norm\412\docbookx.dtd">
<sect1>
<title>Creating Concatenations</title>
<procedure>
<title>How to Create a Concatenation</title>
<!-- moved the following para because of its sense, but
it doesn't matter -->
<para>Do not use this procedure on an existing file system or 
data.</para>
<step>
<para>Check the prerequisites 
<!-- removed the xref to avoid a parsing error -->
and the preliminary information.</para>
</step>
<step>
<para>To create the concatenation from the Solaris Management 
Console</para>
</step>
<step>
<para>To create the concatenation from the command line, use the 
following form of the metainit command:</para>
</step>
</procedure>
<simplesect>
<!-- sect2 works here too -->
<title>Where To Go From Here</title>
<para>Information for the IA archtecture is different.</para>
</simplesect>
</sect1>

Even if you want to insist on putting trailing info within a
procedure, I think it would be wrong to allow simplesect,
because it would confuse the section hierarchy with the
formal objects.

And procedure as it stands is parallel in construction with
the lists, which don't allow trailing content.  I think you
should use the section hierarchy for the containment you desire.

regards, Terry Allen