Skip to main content
T
tommyr
Known Participant
March 11, 2010
Question

Question on EDD

  • March 11, 2010
  • 2 replies
  • 2176 views

Hello. I have the following scenario: We are documenting config file that a user might need to edit (within the software that we sell), which is in XML format. When the user opens a config file (in TextPad for example), it's like any other XML file, meaning it's line by line but the parent-child elements are not indented. In our documentation, we like to convey the hierarchical structure of the config file though indentation and spacing, for easier readability. Currently, the documentation for these config files (in the pleasant format) is in structured FM, but each config file example will be its own refefrence topic in our DITA implementation.

I would like to edit the EDD in our structured app to change the paragaph style of the text , depending on where the element appears. For example, we have opening and closing tags in this config file, with text in between, such as this:

     <EmailDay>
     Day on which the weekly e-mail reminder is to be sent
    </EmailDay>

In addition, there are THREE potential levels of elements, depending on the config file, as in the following example:

<SubmittalExternalApprovalWorkflows>

      <SubmittalExternalApprovalWorkflow>

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

What context rule would I use in the EDD to accomplish this? I have flirted with the {first} and {not first} rules, but those are limiting. I am thinking maybe the {after element} or {before element} rules as well. Can someone please point me down the righ path?

FYI - I plan to use one element in our FM structured app for the <> tags (called codeblock) and another element (called msgblock) in the structured app for the text values (bolded above)

thanks much

Tom

This topic has been closed for replies.

2 replies

L
Lynne A. Price
Inspiring
March 11, 2010

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

T
tommyrAuthor
Known Participant
March 12, 2010

Thanks you very much Lynne. I did not receive any of the text from your first post, but I can see it all now.

After reading your suggestions, the attribute approach might be best. I was actually thinking about whether I could use the attributes to distinguish the elements, but I did not know you can set conditions based on attributes in the EDD; that's good to know though because I can then not worry about the hierarchy and positioning to drive formatting changes. The only caveat is that the attributes must assigned, which is fine because we don't document tons of these config files.

I knew about not being able to nest codeblocks, so I quickly eliminated that option. I also want to avoid specialization, as we are using the apps provided by purchasing Leximations DITA-FMx plug-in for FrameMaker.

I just tested the attribute method. I am changing the paragraph style based on the attribute. For some reason, however, the indents are not showing in the file. They appear in the paragaph designer but the text isn't physically indented on the screen.

Tom

T
tommyrAuthor
Known Participant
March 12, 2010

Tom,

Your first and last paragraph rules may be overriding the text format

rules. A useful tool for debugging EDDs is the StructureTools > Show

Element Context command. This command will show you which rules have been

applied to the current element and each of its ancestors (marking those

that have "fired" with an arrow). The results are not always what the

developer expects.

--Lynne


Thanks Lynne. I had concerns about those but left them alone because they are applying rules to entirely different elements. And because this is an inherited EDD from DITA-FMx, there are some rules that I don't anticipate needing.

thanks again

Tom

Van Kurtz
Van Kurtz
Inspiring
March 11, 2010

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

T
tommyrAuthor
Known Participant
March 11, 2010

Thanks Van.

I am not sure I would want to go the route you suggested, for a couple of reasons. 1) I do not want to create new DITA elements, and 2) the element names in the config XML file are too many to insert prefixes and suffixes for all of them in the EDD. I will chew on this for a while. It did not strike me as difficult to do at first glance.

I was hoping for maybe a context rule that states the "path" of the elements that precede the current element (using the *< section < refbody) which would be the parent or even sibling of the current element.

Thanks again

Tom

Terms & ConditionsAccessibility statement
Using the community Terms of use Privacy Cookie preferences Do not sell or share my personal information ad choicesAdChoices