SPFE Documentation | Collections > EPPO-simple Demos > Procedures demo

Procedures demo

EPPO-simple provides two procedure structures. You may choose either one or use them both. The two structures are procedure and instructions. The procedure structure is intended for major procedure that cover a significantly complicated procedure. Each step in a procedure has a title and body, meaning that each step is a significant piece of work. Each step of a procedure may itself contain an instructions element with the detailed steps for completing the procedure step. Procedures generally accomplish some business process.

An instructions structure is a simple set of steps suitable for a straightforward do-this-then-this method. Instructions generally concern the manipulation of a piece of machinery. Instructions are similar to numbered lists, but the content model allows more sub-elements than numbered list. (But don't use instructions to get round the limit on the content model of a numbered list. Create a more permissive version of numbered list if that is what you need.) The following is an example of an instructions element:

  1. Turn on the widget wrangler.

    It is the big red button on the left.

  2. Press the green button and hold for five seconds.

Here is the code for the list above:

<instructions>
    <step>
        <p>Turn on the widget wrangler.</p>
        <p>It is the big red button on the left.</p>
    </step>
    <step>
        <p>Press the green button and hold for five seconds.</p>
    </step>
</instructions>

A procedure consists of a procedure title followed by an introduction and a set of steps. Each step has a title followed by text that elaborates on the step. Optionally, a procedure may have the following elements between the introduction and the steps:

Why is there no support for pre-requisites and post-requisites?

In some structured vocabularies, part of the model of a procedure is a set of pre-requisites (things you must do before the procedure or things you will need to do the procedure) and post requisites (things you can or must do after the procedure). This model does not fit with the Every Page is Page One philosophy that topic should be self-contained.

The idea of “things you need to do before this” can be re-expressed (more precisely) as “things you need to have in order to do this”. The EPPO-simple procedure model provides an inputs structure for this purpose. You can list each of the inputs (materials and tools) that the reader will need to complete the procedure. (Think of this like the ingredients list for a recipe.) You can use annotations within the body of a input or output listing, which will generate links to topics that relate to those items, thus providing the reader with links to procedures for creating any of the inputs that they don't have on hand.

The idea that there are certain things that you can do after a procedure is usually based on one of two ideas. The first is that once you have the output that the procedure creates you can do a number of other things. This is not generally a significant use case since most readers will do not a procedure at all without some end goal in mind. However, by using annotations in the body of an output listing, you will allow the build to produce links to any pages that discuss the use of those outputs. The second reason for listing post-requisites is to chain procedures into a workflow. This is not appropriate in Every Page is Page One design (and tends to hide the fact that a workflow exists). A workflow should be expressed using a workflow topic.

This is a procedure:

Blowing down little pigs' houses

This is how you blow down the house of a little pig.

Warning: Do not attempt to blow down a brick house

Brick houses cannot be blown down by wolf lungs. To blow down a brick house, try high explosives.

Caution: Avoid inhaling straw dust

Blowing down a straw house can create dust which may irritate the lungs. Use caution when blowing down straw houses.

Inputs

  1. Pig's house - You will need one pig's house made of straw or bricks.

  2. Wolf - You will need one healthy wolf with a good pair of lungs.

Outputs

  1. Pigs - Once the house is blown down, you will have pigs.

Step 1: Huff

To huff:

  1. Open mouth.

  2. Draw in air.

Step 2: Puff

Puff

Step 3: Blow the house down

Blow the house down.

Here is the code for the procedure above:

<procedure>
    <title>Blowing down little pigs' houses</title>
    <intro>
        <p>This is how you blow down the house of a little pig.</p>
    </intro>
    <admonitions>
        <warning>
            <title>Do not attempt to blow down a brick house</title>
            <p>Brick houses cannot be blown down by wolf lungs. To blow down a brick house,
                try high explosives.</p>
        </warning>
        <caution>
            <title>Avoid inhaling straw dust</title>
            <p>Blowing down a straw house can create dust which may irritate the lungs. Use
                caution when blowing down straw houses.</p>
        </caution>
    </admonitions>
    <inputs>
        <input>
            <name>Pig's house</name>
            <p>You will need one pig's house
                made of straw or bricks.</p>
        </input>
        <input>
            <name>Wolf</name>
            <p>You will need
                one healthy wolf with a good pair of lungs. </p>
        </input>
    </inputs>
    <outputs>
        <output>
            <name>Pigs</name>
            <p>Once the house is blown down, you will have pigs.</p>
        </output>
    </outputs>
    <steps>
        <step>
            <title>Huff</title>
            <p>To huff:</p>
            <instructions>
                <step>
                    <p>Open mouth.</p>
                </step>
                <step>
                    <p>Draw in air.</p>
                </step>
              </instructions>
        </step>
        <step>
            <title>Puff</title>
            <p>Puff</p>
        </step><step>
            <title>Blow the house down</title>
            <p>Blow the house down.</p>
        </step>
    </steps>
</procedure>

Although the procedure above contains an instructions element in the first step, the instructions element is not part of the procedure structure. Rather, it is in independent structure that is, by default, part of the text-nested group. It is available in a procedure step because the default content model of step is the text-nested group.

 

Reasons to develop your own procedure structure

You might want to develop your own procedure structure if: