[framemaker-dita] ANN: Renaming DITA Map Topics

[Jeremy H. Griffith]

On Wed, 24 Mar 2010 10:07:13 -0400, "Rick Quatro" <frameexpert at truevine.net> 
wrote:

>If you are using MIF2Go to generate DITA, you may be interested in a
>solution to get more "human readable" topic names. I am looking for feedback
>to see if there is a need or interest in this kind of solution. (I am not a
>MIF2Go expert, and there may be a built-in way of doing this.) Any feedback
>or constructive criticism is welcome.
>
>http://frameautomation.com/2010/03/24/renaming-dita-map-topics/

Interesting process.  I can see where it could be helpful to
some users, as many of your plug-ins certainly are.

There are a few methods to do this within DITA2Go.  You can
specify the file names individually with markers, have Mif2Go
generate them from the topic titles, or build the names using
macros that can incorporate sequence numbers and any other
identifier you please.  This is discussed in the Mif2Go User's
Guide, par. 32.7, "Renaming HTML files for automated systems".
Specifics for DITA are in par. 14.9.3, "Specifying the ID for 
a DITA topic".

That said... the names we generate automatically, by default,
have one big advantage over all other methods: they are all
*guaranteed* to be unique.  We've had many cases of people 
applying more meaningful names, then discovering, only after
a doc release, that they had duplicates... which means that
one copy overwrites the other.  We warn about this in the UG,
regarding the use of markers:
>Using FileName markers can result in two sections of your 
>document having the same name. When this happens the second 
>file overwrites the first, and the first topic does not 
>appear in HTML output. This error is almost impossible to 
>find, unless you search very specifically through all file-
>name settings and markers. Expect many problems of this type 
>if you use FileName markers to override Mif2Go-generated file 
>names.

And the use of topic titles:
>Naming split files using paragraph content is, according to 
>Mif2Go developers, a Very Very, Very Bad Idea. You are almost 
>certain to have name conflicts resulting in Mif2Go overwriting 
>one file with another, and you will not know it happened until 
>users complain. However, at your peril, you can assign file 
>names based on the content of paragraphs: either existing 
>paragraphs (usually paragraphs whose formats designate split 
>points), or paragraphs in a special format dedicated to this 
>purpose. 

Perhaps Rick's process avoids this, by rigorously checking
for duplicates.  In that case, it's a very good answer to
the problem that some users have with non-meaningful (but
persistent) names, like "aa123456", which are our default.

-- Jeremy H. Griffith, at Omni Systems Inc.
  <jeremy at omsys.com>  http://www.omsys.com/