Next / Previous / Contents / Shipman's homepage

9.3. Procedures

A step-by-step procedure is generally presented in a form similar to the bullet list, but with step numbers taking the place of bullets.

Enclose the entire procedure within a procedure element. Each step is enclosed within a step element containing one or more para or simpara elements.

For example, this input:

    <procedure>
      <step>
        <para>
          Throw the football.
        </para>
      </step>
      <step>
        <para>
          Pick it up first.
        </para>
      </step>
    </procedure>

produces this output:

  1. Throw the football.

  2. Pick it up first.

If the steps of your procedure refer to other steps, you can get DocBook to insert the step number into each reference automatically. To do this:

  1. Invent a name I for each step, and add an attribute xml:id=I to the corresponding step element.

  2. Wherever you want to refer to a step, use the element <xref linkend='I'/>, where I is the name of the step you are referring to.

    This element will be replaced by the text “step N” where N is the step number.

Here's an example. This is a (facetious) solution to the famous Halting Problem. First, in output form:

  1. Has the program halted? If so, go to Step 3.

  2. Go to Step 1.

  3. Done: we now know that the program halts.

And now the source for the above:

      <procedure>
        <step xml:id='start-step'>
          <para>
            Has the program halted?  If so, go to
            <xref linkend='done-step'/>.
          </para>
        </step>
        <step xml:id='loop-step'>
          <para>
            Go to <xref linkend='start-step'/>.
          </para>
        </step>
        <step xml:id='done-step'>
          <para>
            Done: we now know that the program halts.
          </para>
        </step>
      </procedure>