Question on EDD

Report · Mar 11, 2010

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:

            <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

Report · Mar 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:

            <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

Report · Mar 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

Report · Mar 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><SubmittalExternalApprovalWorkflows></codeblock>
<codeblock><SubmittalExternalApprovalWorkflow></codeblock>
<codeblock><WorkflowName></codeblock>
<msgblock>Name of the workflow instance</msgblock>
<codeblock></WorkflowName></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>
<SubmittalExternalApprovalWorkflows>
<codeblock>
     <SubmittalExternalApprovalWorkflow>
     <codeblock>
        <WorkflowName>
        <msgblock>Name of the workflow instance</msgblock
        </WorkflowName>
     </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:

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"><SubmittalExternalApprovalWorkflows></codeblock>
<codeblock otherprops="2"><SubmittalExternalApprovalWorkflow></codeblock>
<codeblock otherprops="3"><WorkflowName></codeblock>
<msgblock otherprops="3">Name of the workflow instance</msgblock>
<codeblock otherprops="3"></WorkflowName></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

Report · Mar 11, 2010

Such as what? It looks like your post didn't come through ...

Report · Mar 11, 2010

Tom,

Did you get my complete response? The first time I sent it, it stopped at the first less-than sign. I tried a second time and I believe it went through.

--Lynne

Report · Mar 11, 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

Report · Mar 12, 2010

Tom,

Sometimes, but rarely, when the formatting is not as it should be, I reimport the element definitions from Current with remove overrides checked. This forces FrameMaker to reapply the EDD to the document, that is, reformatting it. You might need to do this to see the correct paragraph indentations. If not, check your EDD context rules VERY carefully; there may be a minor mistake OR the ORDER of the context rules is wrong (a later context rule can override an earlier one).

Van

Report · Mar 12, 2010

Thanks Van. I will give this a shot.

Report · Mar 12, 2010

Did not work. There are three sections in the EDD for that <codeblock> element 1) Text Format Rules 2) Format Rules for First Paragraph and 3) Format Rules for Last Paragraph. However, the rules I have in #1 are not repeated in 2 and 3. This is strange.

Tom

Report · Mar 12, 2010

Tom,

The text format rules for an element are not always repeated in the rules for the first paragraph and the last paragraph. For example, I have text formatting rules for element A; however, if that element comes after element B, then I want element A to start at the top of the page. In this case, the formatting rule for the first paragraph states to start at the top of the page if the element A is after element B. Here the formatting for the first paragraph is a little different from the other paragraphs in the element. In my situation, the rules for first and last paragraph usually do something extra to those rules specified for the element in general.

Another point...if you reimport the element definitions with removing any overrides AND the paragraph is still not indenting correctly, then I reiterate reviewing your EDD very carefully. My experience is that in a situation like that there is a context rule somewhere that is counteracting the effect of the rule you think should be doing the formatting.

I do a lot of contextual formatting with lists, numbered and bulleted, inside each other down to four levels. And my EDD can correctly handle all the level indentations as well as determining which bullets and which numbers to use, no matter the level of the list. The EDD is rather complicated, but it can get it done. You may need to add some complexity to handle all the cases that may arise. Once the EDD is worked out, using it is a piece of cake.

Van

Report · Mar 12, 2010

Thanks Van.

Would it be possible to contact you "offline" to help me figure this stuff out. Thanks

Tom

Report · Mar 12, 2010

The only general text formatting rule I have in the EDD is the following:

If context is: [otherprops=”1”]
     Use paragraph format: codeblock
Else, if context is: [otherprops=”2”]
     Use paragraph format: codeblock2A
Else, if context is: [otherprops=”3”]
     Use paragraph format: codeblock2B

The only other rules set for <codeblock> apply only to <li>, <ul>, and so on. My test topic is a reference type topic with NO lists.

Tom

Report · Mar 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

Report · Mar 12, 2010

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

Report · Mar 12, 2010

Lynne. I think I have discovered my problem. We are using XDocs for our CMS, DITA-FMx as our DITA plug-in. It is recommended that, when creatng topics through DITA-FMx (and not XDocs) that we use a different struct apps file. Mind you, going forward, we will be creating topics exclusively through Xdocs, but I am using the DITA-FMx apps to test some of this. Sometimes when we do this, FM gets confused.

Apparently, the wrong struct apps was being called because when I did the Show Element Context on <codeblock> it showed a setting I had done last night to a different EDD. Anyway, I think I have solved it. Thanks for the tip on the Show Elements - what an excellent tool.

Tom

Report · Mar 12, 2010

Indents still are not working ..so maybe I will double- and triple-check the EDD rules and see potential overwriting.

Report · Mar 12, 2010

Indenting fixed. I was used to a small pt. size (unstructured) something like 0.5 pt but it's much, much bigger, more like 27 or so.

Report · Mar 13, 2010

Tom,

If you are using two similar applications, StructureTools > Export

Element Catalog as EDD is another debugging tool that you can use to

confirm that a document is using the one you expect. It creates a new EDD

from the element definitions in the current document. The result is rarely

identical to the original. The section structure of the original is lost,

as are any Para elements, and the element definitions are alphabetized by

tag. Still, you can look for a particular definition and make sure it is

the one you want. You can even define an element or format change list

whose only purpose is to identify the EDD underlying the document.

--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

Report · Mar 15, 2010

Thanks Lynne. That will help immensely.