Re: FrameMaker+SGML (or Structured FM7) EDD and R/W rules Management

["Lynne A. Price" <lprice@xxxxxxxxxxxx>]

At 10:29 AM 7/4/02 -0400, eric.dunn@ca.transport.bombardier.com wrote:

>That might be a valid approach, but it wasn't what I was envisioning. It would
>certainly be easier than what I was envisioning though. I would think that it
>would be worthwhile to go to the lengths of creating an EDD that included the
>R/W rules not as comments but as the actual R/W rule elements in the positions
>that they apply. 

Eric,
  Exactly. I was not trying to suggest otherwise. I merely observed that it's
fairly straightforward to get FM to ignore the EDD part of what you call the
UberEDD when processing r/w rules and to ignore the r/w rule part when processing
EDDs. All that is necessary is for FM to view the "other part" as documentation
or comments. For EDD processing, the r/w rules should either be placed outside
of element definitions or within Comments; for r/w processing the formatting of
the EDD elements should be surrounded by comment delimiters.

>This UberEDD would be unreadable by FM as either EDD or R/W. The UberEDD would
>be saved to SGML using four separate R/W rules and processes.
>1 - UberEDD as-is saved as SGML for use in a CVS type system.
>2 - UberEDD stripped to R/W rules. This SGML file is then read into FM using the
>correct application to create a valid R/W file.
>3 - UberEDD stripped to EDD. This SGML file is then read into FM using the
>correct application to create a valid EDD file. EDD is then saved as DTD. EDD is
>imported into template file.
>4 - UberEDD stripped to Application File. This SGML file is then read into FM
>using the correct application to create a valid Application file.

  As you know, I've saved EDDs to SGML before for exactly your reason 1. If you
are going to maintain r/w rules for saving EDDs to SGML (or XML), very little
extra effort is necessary for the functionality of 2, 3, and 4. All you need are
the different drop rules to discard the portions of the UberEDD that are not
included in each output. These rules should be modularized, of course, either in
separate include files or with conditional text so that the rules for your three
different "stripping" applications are easily maintained.
  Of course, when you are working with so many different files, it helps to have
an automated process (perhaps an FDK client) that will update all derived files
each time you modify the UberEDD.
  I will warn you that when I save an EDD as a DTD, I almost always make some
modifications to the DTD such as adding comments to the beginning and including
some entity declarations. Any script or other tool that automates derivation of
the various outputs should be able to automate such EDD modifications.

>Actually I was toying with the idea of using conditional text to allow for
>differences between and multiple versions of DTD, EDD, and so forth. Perhaps a
>solution using attributes to identify required contexts. After all, if the
>read/write rules are to drop attributes or elements these elements and
>attributes shouldn't be present in both the EDD and DTD. For the differences, I
>was thinking an attribute (or element) for InEDD and InDTD. The conditions for
>the differences would have to be processed somewhere in the process #3.

  You may be familiar with the work I presented at the 2000 FrameUsers conference
on a reusable EDD. We worked in a documentation environment where there were
some 16 structured templates using 7 variations of the same EDD. 6 variations
used the same structure, with a few formatting differences. The 7th tweaked
a few of the element names and general rules as well as varying the formatting
a bit. The EDDs were large (almost 200 pages) and it was impractical to maintain
them as separate parallel files. Attempts to make virtually every change 7 times,
and to remember to import element definitions from the right EDD into the right
templates were both time consuming and error prone.
  Instead, we maintained all 7 variations in one EDD file, using three techniques:

1) For strings that changed in different variations, we used variables within the 
   EDD. Variables were typically used for things like dimensions, prefixes, and
   element names. We maintained separate FM documents, called variable definition
   files, that had the variable definitions appropriate to each variant EDD. One
   step in preparing each variant was importing variable definitions from the
   appropriate variable definition files. We split up the definitions across multiple
   files because some definitions were shared by multiple variations.

2) For elements and subelements that changed in different variant EDDs, we used
   conditional text. There were more than 7 conditions, again because some variant
   structures were used by multiple variant EDDs.

3) For repeatedly used structures such as attributes defined for multiple element
   types or common formatting used by multiple element types, we used text insets.

Tying all the variations together was an FDK client. This client reads a configuration
file that give a name to each variant EDD. The configuration file lists the variable 
definition files used by each variant, the conditions that should be shown, and
the templates that use the resulting element definitions. For each variant, the client 
imports variable definitions from the specified files, shows the specified conditions
and hides all others, saves the variant edd under the specified name (for use in
debugging), and imports element definitions from the resulting EDD into the specified
templates.

As an aside, I will mention that we've considered polishing this client a bit and
selling it. It can save weeks of work and make it practical to build systems that
would not otherwise be feasible. Nevertheless, we don't anticipate a large market.
If anyone would consider such a tool, please write directly to me.

Anyway, I believe this system could be extended to support r/w rules and application
definitions in the way you are suggesting, Eric.

There is a philosophical issue that we haven't discussed, though. Modularization
is a great thing when it's necessary. People working on one EDD tend to like the 
fact that FM puts formatting information and structural information into the same
file. People who must maintain different ways to format the same data, though, 
prefer the DTD and stylesheet model and wish that FM didn't merge them. People
who don't need to maintain variations of any part of their application data shouldn't
be forced to separate it from the rest just because other people might want to
maintain variations.

Tools that both:

1) Allow developers to view related mterial within one file so that all related 
   information can be displayed together

2) Still allow modules to be shifted in and out

are a great help in an environment that warrants their cost.



>
>PS: I will assume that you will not be reading this post until after your long
>weekend. Hope you have/had an enjoyable 4th of July. Here in Quebec we just had
>2 long weekends in a row, so it's hard to be jealous.

Thank you. What more enjoyable way to spend a long weekend than catching up
on email?

	--Lynne

Lynne A. Price
Text Structure Consulting, Inc.
Specializing in FrameMaker+SGML consulting and training
lprice@txstruct.com
http://www.txstruct.com
voice/fax: (510) 583-1505
cell phone: (510) 421-2284


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **