How do I change the text for the prereq element to "Before you begin"

Report · Jul 12, 2011

Hi,

I am creating structured docs in DITA (eventually to be published online using RoboHelp), and I want to make, for example, the following changes:

- Change prereq element label text to "Before you begin"

- Add a label to the context element that says "About this topic"

- Change the steps element label text to "Procedure"

- Remove the "Additional Information" label for the step info element.

You get the idea. Can someone at least point me in the right direction? Will I need to create an EDD? Modify the existing one? Something else altogether? Can you point me to the chapter in the Help that covers how to do this?

Thanks!!

Report · Jul 12, 2011

Hi Capt...

I'm not aware of anything in the documentation that would cover this.

First you'll need to clone the structure application to create an application(s) of your own. You should always create your own rather than modifying the default apps so that you can always go back and use the default apps when yours breaks (it will break, I guarantee it). Here's some information on cloning the default apps ..

http://docs.leximation.com/dita-fmx/1.1/?ditafmx_cloningtapps.html

Note that this was written for DITA-FMx so the paths and filenames won't be what you're looking for, but it should give you the general idea of which files to look for.

Some of the labels you're looking to change may be in the template and some may be in the EDD as an element prefix (off hand I can't say).

However, the real question is .. which version of FM are you using? If FM8 or FM9, this is a reasonable task. If FM10, you're in for quite a chore since the apps are far more complex (if you're using DITA 1.2.)

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com

Report · Jul 12, 2011

Using Frame 10.....

Report · Jul 12, 2011

DITA 1.1 or DITA 1.2?

Report · Jul 12, 2011

DITA 1.2

Report · Jul 13, 2011

Well, then you'll need to spend some time carefully analyzing the structure and relationship of the app files. They accurately mirror the structure of the DITA 1.2 DTD files but use text insets, variables, and conditional tagging to import modules and maintain the different general rules for different topic types. I can't even begin to explain what to do. The only documentation on this is provided as notes in the EDD files. The fundamental idea is the same as before ..

1) create a clone of the app(s) you want to modify so you have your own custom apps (be sure to test the validity of the cloned apps before making *any* changes)

2) make your modifications to your custom apps

Someone should fully document this process .. it was complicated for DITA 1.1, but it's really really hard for DITA 1.2.

...scott

Report · Jul 13, 2011

Scott

,

Surely the DITA 1.2 EDDs are not that hard to modify! And I hope that the notes in the EDDs are useful.

I certainly agree it is wise to back up the original before making modifications. That can be done by saving copies of the files that are changed, or making a copy of the affected directories without modifying the application definitions in structapps.fm (or another application definition file).

The FrameMaker 10 DITA 1.2 EDDs and DTDs are located in AdobeFrameMaker10\Structure\xml\DITA_1.2\app. This directory has the same subdirectories as those in the DITA 1.2 distribution from OASIS, with the addition of one more that is FrameMaker-specific. In the DITA 1.2 distribution, each subdirectory of app itself has a subdirectory called dtd which contains relevant DTD modules and complete DTD shells that assemble the needed modules. In FrameMaker 10, in addition to the dtd subdirectory, the app subdirectories also have subdirectories called edd (which contains complete EDDs and EDD modules that parallel the modules and DTD shells in the dtd subdirectory), templates (which contains the templates corresponding to the complete EDDs), and rules (which contain read/write rules used with those templates).

In particular, subdirectory technicalContent has a dtd subdirectory with a file called task.mod that contains the declaration for the prereq element. In parallel, technicalContent also has an edd subdirectory with a file called task.eddmod.fm that has the element definition for prereq. As shipped, this element definition defines a prefix of "Prerequisite ". Sounds like the only needed change to this file is to replace the prefix with "Before you begin ".

Once the change has been made (and saved) in the EDD module, the text insets to it need to be updated. In parallel to where the DTD module is used, task.eddmod.fm is used as a text inset in:

app\learning\edd\learningContent.edd.fm
app\machineryIndustry\edd\machineryTask.edd.fm
app\technicalContent\edd\ditabase.edd.fm
app\technicalContent\edd\generalTask.edd.fm
app\technicalContent\edd\task.edd.fm

So to incorporate the change, the user should open whichever of these EDDs he plans to use and use Edit > Update References to update text insets marked for manual update. He can then open the corresponding templates and import element definitions from the updated EDD into the appropriate template.

The advantage of the text insets is that a change made once can be incorporated into several (in this case 5) complete EDDs. A user who doesn't want to bother with the text insets, though, can convert them to text and make the change in each needed EDD. To convert text insets to text, click on any text inset (such as the one with the copyright notice at the beginning of the file). Then bring up the Text Inset Properties dialog with Edit > Text Inset Properties, click on Convert to bring up Convert Text Insets To Text, then click the All Text Insets radio button and click Convert again.

--Lynne

Report · Jul 13, 2011

Hi Lynne...

As with everything .. it's all relative.

If you start with the general assumption that EDD and structure application development is tricky for most people until they get comfortable with the syntax and file relationships. The DITA 1.1 EDDs are relatively simple since they are comprised of just a handful of files. With DITA 1.2 you start with multiple directories of files that are interlinked with text insets, variables, and conditions. I think that this structure is perfectly logical and sensible, and the insets are an absolute requirement .. it's just going to be difficult for most people to wrap their head around (well, it is for me).

The notes in the EDDs are very helpful, but I'd like to see a diagram that shows how they are all related, and possibly some pointers as to where to start when you want to modify any given topic model.

It will be interesting.

Cheers,

...scott

Report · Jul 14, 2011

Scott,

I'm sure the two of us largely agree on these issues.

You are quite right that a diagram could be helpful.

The complication of DITA 1.2 over DITA 1.1 arises because there are so many more DTDs and those DTDs are built from reused pieces. The EDD organization just follows the DTD organization. People who want to make minor modifications (such as tweaking a single prefix) may not be familiar with the DTDs' module structure. In fact, people who want to change FrameMaker formatting shouldn't even have to know wanything about DTDs. Still, there's the match up of EDDs to templates and with 22 different EDDs spread over 7 directories (I'm not counting ditaval and FrameMaker), there's some familiarity required.

Someone could provide a pair of directories: one with versions of all 22 EDDs with the text insets converted to text (and a comment added at the beginning to explain what's been done); the other with the corresponding templates, along with an application definition file with appropriate changes. That way, people who want to make quick changes without elegance would have a simpler starting point. This someone could also draw the diagram. I'm not necessarily pointing a finger at you here. I could put it on my to-do list, but that list is already pretty long ...

--Lynne

Report · Jul 15, 2011

Thank you, Lynne. This is helpful, at least in pointing me in the general direction. I saw the prereq element, though I didn't see how to change some of the other elements. For example, in a task, when I add the steps element, I get a Task prefix. (This prefix happens to be extremely unfortunate for me because I'm documenting a product in which you manage tasks, and so to have the Task prefix about procedures about tasks is going to be really confusing to our users. I would like to change this to Procedure, which frankly makes more sense to me anyway.)

I do not understand why Adobe does not provide a simple way to make these changes, or on failing that, why they can't at least provide some decent instructions on how to do this.

Thanks again.

Report · Jul 19, 2011

The word "Task" that appears before the first step is not a prefix. Note that the first step in the steps element uses paragraph format step.begin. Look at the Advanced tab in the paragraph designer. This paragraph format applies a frame above of StepsBegin which contains a horizontal rule across the page width as well as this word. You can change it on the Frames reference page of your template.

A couple of ways you could find how the text is generated:

1) You've already observed that the text appears when you insert the steps element. Therefore, you can look at the format rules for steps in the EDD. They apply step.begin to the first paragraph. You can then look at the template to see how step.begin is defined.

2) You can bypass the EDD by creating a steps element and then looking at the paragraph designer to see if the text is coming in through the paragraph format.

--Lynne

Report · Jul 19, 2011

I am thrilled to report that I've figured it out, thanks to you, Lynn. At first I tried editing the reference page of the topic. It seemed to work, except that I had to do it again for every new topic I created. I was prepared to live with that, but then once I quit and then came back to my work, I saw that this "solution" wasn't sticking. Then I realized, as you did point out, that I needed to edit the reference page of the *template* !! Ahhh...now it works perfectly. All my steps sections are automatically being preceded by the word Procedure. Nice! Thanks!