Question on EDD

Tom,

  As I understand your message, you want to obtain formatting such as:

<SubmittalExternalApprovalWorkflows>
     <SubmittalExternalApprovalWorkflow>
           <WorkflowName>
           Name of the workflow instance
           </WorkflowName>

from a structure such as:

<codeblock>&lt;SubmittalExternalApprovalWorkflows&gt;</codeblock>
<codeblock>&lt;SubmittalExternalApprovalWorkflow&gt;</codeblock>
<codeblock>&lt;WorkflowName&gt;</codeblock>
<msgblock>Name of the workflow instance</msgblock>
<codeblock>&lt;/WorkflowName&gt;</codeblock>

  In particular, you are asking how to define an EDD that will allow the indentation to be set automatically.
Have I understood the question correctly?

  The problem is that the indentation is determined by the nesting level of the structure you are representing (with tags such as SubmittalExternalApprovalWorkflows rather than codeblock) and not by the sequence of codeblock and msgblock elements sketched above.

  In your place, I would probably use a structure such as:

<codeblock>
  &lt;SubmittalExternalApprovalWorkflows&gt;
  <codeblock>
     &lt;SubmittalExternalApprovalWorkflow&gt;
     <codeblock>
        &lt;WorkflowName&gt;
        <msgblock>Name of the workflow instance</msgblock   
        &lt;/WorkflowName&gt;
     </codeblock>   
  </codeblock>  
</codeblock>

  Note that in this representation the second codeblock is a subelement of the first one and not an element that follows it. This hierarchical approach allows you to specify the formatting in an all-contexts rule that simply increases the indentation for each level of nesting:

1. In all contexts
      Basic Properties
        Indents
           Move first indent by: 0.25in

  The elements you would use in the EDD are:

<AllContextsRule>
  <ParagraphFormatting>
    <BasicProperties>
      <Indents>
        <FirstIndentChange>0.25in</FirstIndentChange>
      </Indents>
    </BasicProperties>
  </ParagraphFormatting>
</AllContextsRule>

  Many other variations are possible. For example, if you want to use paragraph catalog entries, you could use a level rule rather than a context rule:

1.  If level is: 1
      Use paragraph format: codeblock1
    Else, if level is: 2
      Use paragraph format: codeblock2
    Else
      Use paragraph format: codeblock3

You could also use a context rule:

1.   If context is: * < codeblock < * < codeblock
       Use paragraph format: codeblock3
     Else, if context is * < codeblock
       Use paragraph format: codeblock2
     Else
       Use paragraph format: clockblock1

Note that you must test for the most deeply nested context first in a context rule since the least restrictive context matches all codeblocks.

DITA 1.0 does not support the markup I've suggested because it does not allow codeblocks to be nested. Nor does it allow msgblock within codeblock (although it does allow msgph, which is probably fine for your needs). You could either specialize to allow the nesting or go back to the sequential markup you first suggested but add an attribute to distinguish the cases:

<codeblock otherprops="1">&lt;SubmittalExternalApprovalWorkflows&gt;</codeblock>
<codeblock otherprops="2">&lt;SubmittalExternalApprovalWorkflow&gt;</codeblock>
<codeblock otherprops="3">&lt;WorkflowName&gt;</codeblock>
<msgblock otherprops="3">Name of the workflow instance</msgblock>
<codeblock otherprops="3">&lt;/WorkflowName&gt;</codeblock>

  With this approach, you could set the formatting with a context rule that checks the attribute values:

1.  If context is: [otherprops="1"]
      Use paragraph format: codeblock1
    Else, if level is: [otherprops="2"]
      Use paragraph format: codeblock2
    Else
      Use paragraph format: codeblock3

  Of course, if you are going to specialize DITA (Russ, this is for you if you are still reading my typical long-winded prose), instead of extending the definition of existing elements, you can define new ones. For example, XMLelement could automatically insert visual start- and end-tags:

<XMLelement tag="SubmittalExternalApprovalWorkflows>
  <XMLelement tag="SubmittalExternalApprovalWorkflow>
    <XMLelement tag="WorkflowName>
      <msgblock>Name of the workflow instance</msgblock>
    </XMLelement
  </XMLelement>
</XMLelement>

  Here, in addition to setting the indentation, the EDD would assign an XMLelement a prefix of:
     \<<$attribute[tag]>\>
and a suffix of:
     \</<$attribute[tag]>\>
so that the above would be formatted as:

<SubmittalExternalApprovalWorkflows>
     <SubmittalExternalApprovalWorkflow>
           <WorkflowName>
           Name of the workflow instance
           </WorkflowName>
     </SubmittalExternalApprovalWorkflow>
</SubmittalExternalApprovalWorkflows>

        --Lynne

Lynne A. Price

Text Structure Consulting, Inc.

Specializing in structured FrameMaker consulting, application development,

and training

lprice@txstruct.com            http://www.txstruct.com

voice/fax: (510) 583-1505      cell phone: (510) 421-2284

Tom,

It is not clear to me exactly what you are doing. First guess is your FrameMaker file will look like this:

<codeblock>SubmittalExternalApprovalWorkflows</codeblock>

      <codeblock>SubmittalExternalApprovalWorkflow</codeblock>

            <codeblock>WorkflowName</codeblock>
            <msgblock>Name of the workflow instance</msgblock>
            <codeblock>/WorkflowName</codeblock>

      <codeblock>/SubmittalExternalApprovalWorkflow</codeblock>

<codeblock>/SubmittalExternalApprovalWorkflows</codeblock>

Is this what you are planning to do? If so, I cannot think of a way to control the indentation.

AN ALTERNATIVE would be to use the SAME structure in Frame as in the XML file, that is:

<SubmittalExternalApprovalWorkflows>

      <SubmittalExternalApprovalWorkflow>

            <WorkflowName>
            Name of the workflow instance
            </WorkflowName>

     </SubmittalExternalApprovalWorkflow>

</SubmittalExternalApprovalWorkflows>

Then in your EDD create a prefix AND a suffix for each element that displays the name of the element. For example,  the prefix for the WorkflowName element would be

<WorkflowName>/r

and the suffix would be

/r</WorkflowName>

The /r is a line break; this will put the opening tag for the element on the line above the content and the closing tag on a line below the content. The EDD also sets the left indentation for the entire element.

IF an element can be at ANY level, then you can set the indentation as relative. Then each time the element is displayed, it indents itself by an amount ADDED to the enclosing element.

Using this scheme, there is no need for codeblock and msgblock. You just use the features of the EDD to format the elements in a special way in your documentation.

Hope this helps, at least a little,

Van