DITA Machine Industry SC - Additional Images / Figures in Step (IssueNumberMIXX.htm)

["Gerald Goetz" <goetz@noxum.com>]

I am sending you a first version of a proposal we discussed
in the last meeting - Additional Images / Figures in Step.

This proposal still needs an official number. I have therefore
gave it the - temporary - number XX.

Thanks to Robin Sloan of PTC for the sample image.

Kind Regards,

Gerald Goetz
Noxum GmbH
Beethovenstr. 5
97080 Würzburg

Tel: +49 931 4 65 88 442
Fax: +49 931 4 65 88 599
 
Handelsregister: HRB 6212, Amtsgericht Wuerzburg Vertretungsberechtigte Geschaeftsfuehrer:
Norbert Klinnert, Volker Roemisch, Michael Stegmann

Title: DITA Proposed Feature # MIXX - Additional Images / Figures in Step

DITA Proposed Feature # MIXX - Additional Images / Figures in Step

Relax the content models of step and substep. Allow the elements image and fig to be placed before cmd within step and substep.

Longer Description

Problem

The current DITA 1.1 content models for step and substep do not support the placement of an element image or fig directly before an element cmd when more than one element step is present.

The elements context and info do allow image and fig but context only supports images / figures for all steps following and info only supports images / figures after a command.

Some technical documentations requires a special image / figure to be displayed before the command or at the same line height as the the command (see examples attached).

Solution

Allow the Elements image and fig as optional elements before cmd.

Scope

The changes in the content model are minor. The elements image and fig are already present. The content models affected are both defined in just one file:task.mod. All DITA 1.1 documents are still valid as the elements are not new and optional in their container elements.

Benefits

This feature would enhance the adoption of DITA in the machine industry and other areas. It would better support screen and picture oriented task descripitons.

Use Case

The author describes a task with several steps. One step / substep requires a specific image or figure. The author inserts the specific image or figure right before the cmd element.

Technical Requirements

The content models of step and substep would have to be modified.

Element step before modification:

<!--                    LONG NAME: Step                            -->
<!ELEMENT step          (%cmd;, 
                         (%info;  |%substeps; | %tutorialinfo; |
                          %stepxmp; | %choicetable; | %choices;)*, 
                         (%stepresult;)? )                           >

Element step after modification

<!--                    LONG NAME: Step                            -->
<!ELEMENT step          ((%image;| %fig;)*,
                          %cmd;, 
                         (%info;  |%substeps; | %tutorialinfo; |
                          %stepxmp; | %choicetable; | %choices;)*, 
                         (%stepresult;)? )                           >

Element substep before modification:

<!--                    LONG NAME: Sub-step                        -->
<!ELEMENT substep       (%cmd;, 
                         (%info; | %tutorialinfo; | %stepxmp;)*, 
                         (%stepresult;)? )                           >

Element substep after modification

<!--                    LONG NAME: Sub-step                        -->
<!ELEMENT substep       ((%image;| %fig;)*,
                          %cmd;, 
                         (%info; | %tutorialinfo; | %stepxmp;)*, 
                         (%stepresult;)? )                           >

Costs

Minimal. Change of two content models. No new elements / domains are introduced. The output of the publishing modules of the DITA Open Toolkit has to be validated.

Time Required

Two person hours for the DTD modification and the proper documentation (this does not include layout modifications in the DITA Open Toolkit).

B000B866.TIF