Docbook and Frame 7.2

[Lynne A. Price]

At 06:45 AM 1/5/2006, Bernard Aschwanden wrote:
>If you are dealing with docbook then I strongly suggest starting with 
>read/write rules that knock out the 8317 elements you don't need and keeps 
>the stuff you find useful. I also found a ton of the attributes to be 
>overkill and dropped them as well.

John,
   I echo Bernard's advice above (by the way, Bernard, thanks for the 
acknowledgment elsewhere in your reply!).

   Let me point out that FrameMaker makes it easy to drop the unneeded 
elements and attributes. When I start a DocBook project, I use FrameMaker's 
File > Structure Tools > Import DTD command to simplify the EDD. This 
command updates an EDD to correspond to a (possibly revised) version of a 
DTD. Since it processes read/write rules, though, any rules to drop 
unneeded elements and attributes affect the result.

   In a bit more detail, Imake a list of all elements (see below for one 
way of doing so). Then given:

   abbrev
   abstract
   accel
   ackno
   acronym
   action
   ...

I use a text editor macro to insert:

   element "

at the beginning of each line and:

   " drop;

at the end to produce:

   element "abbrev" drop;
   element "abstract" drop;
   element "accel" drop;
   element "ackno" drop;
   element "acronym" drop;
   element "action" drop;
   ...

I do something similar for attributes. I save all these rules in a file and 
include that file in my read/write rules.  I delete the rules for elements 
and attributes that I know I want to use. Then I use an application that 
invokes those rules to import the DocBook DTD into the DocBook starter kit 
EDD that comes with FrameMaker. FrameMaker not only removes the element 
definitions for the dropped elements, but it removes references to those 
elements in the general rules for the retained elements. I then have a much 
simpler version of the DocBook starter kit EDD that I can edit to change 
the formatting as necessary for my project. If I later decide I had dropped 
an element or attribute that I want to use, I can remove the associated 
drop rule and import the DTD once more into the current version of my EDD.

To make the list of elements, I create a new EDD by opening the DocBook DTD 
without a structured application. Then I create a list of elements and 
paragraphs (usually an alphabetized list since that makes it easy to locate 
entries in the list) selecting the Tag element to include in the generated 
list and formatting it without page numbers. I save the result as text. I 
do the same for the attributes, selected the Name element to include in the 
list. Since the same attribute may be defined for multiple elements, I 
remove the duplicates with a utility such as the UNIX uniq command.

>Finally, there are enough consultants (myself included) on this list that 
>someone can always be hired to pitch in on the project.

As another such consultant, I agree with the above as well!

>-----Original Message-----
>From: framers-bounces+bernard=publishingsmarter.com at lists.frameusers.com 
>[mailto:framers-bounces+bernard=publishingsmarter.com at lists.frameusers.com] 
>  On Behalf Of John Pitt
>Sent: Thursday, January 05, 2006 5:34 AM
>To: framers at lists.frameusers.com
>Subject: Docbook and Frame 7.2
>
>My questions. How do I:

As Bernard suggested, most (if not all) of your questions are addressed in 
the Structure Application Developer's Guide.

>@ control column widths in tables?

You can have an attribute whose value is a space-separated list of the 
widths of successive columns, such as "1in 3.5cm 200pt". You can request 
proportional widths "3* 2* 5*" divides the available space (which is either 
the width of the text frame or the width of a column) into widths in the 
indicated proportions. More specifically, FrameMaker adds the numeric 
values of all proportional widths, and assigns a width to each column that 
is the numeric value for that column divided by that sum. In this case, 
3+2+5 = 10, so the first column would be 3/10 the width of the available 
space, the next one 2/10, and the last 5/10. You can mix fixed and 
proportional widths:
"2* 3in 1*" makes the middle column 3 inches wide, gives the first column 
2/3 of the remaining space and the last column 1/3.

Alternatively, you can use the CALS table model (which DocBook does) and 
have an empty colspec element at the start of each tgroup. The colspec 
elements exist only in XML (in FrameMaker, they correspond to properties of 
the resulting table and its content rather than to elements). Each defines 
some properties of a table column, including its width.

>@ control the total width of tables?

Unless you are using proportional widths as discussed above, the total 
width of a table is the sum of the column widths.

>@ prevent the last column in multi-column tables appearing as the first 
>column?

By correctly specifying the number of columns, with the correct number of 
colspec elements, with an attribute for the number of columns, or (if all 
tables have the same number of columns) with an FM Property rule.

FM supports DTDs that simply list successive cells without row elements. 
For example:

    <table cols="3">
       <cell>Item</cell>
       <cell>Quantity</cell>
       <cell>Price</cell>
       <cell>Chocolate</cell>
       <cell>3</cell>
       <cell>$27</cell>
       <cell>paper</cell>
       <cell>1</cell>
       <cell>$10.99</cell>
       <cell>soap</cell>
       <cell>2</cell>
       <cell>$5.45</cell>
    </table>

Suppose you have data that is broken into rows, but the number of cells in 
a row is greater than the number of columns:

    <table cols="2">
      <row>
       <cell>Item</cell>
       <cell>Quantity</cell>
       <cell>Price</cell>
      </row>
      <row>
       <cell>Chocolate</cell>
       <cell>3</cell>
       <cell>$27</cell>
      </row>
      <row>
       <cell>paper</cell>
       <cell>1</cell>
       <cell>$10.99</cell>
      </row>
      <row>
       <cell>soap</cell>
       <cell>2</cell>
       <cell>$5.45</cell>
      </row>
    </table>

Although a human can include that the attribute value 2 in the table 
start-tag is an error and a 3-column table is desired, FM attempts to force 
the content into 2 columns.

>@ remove whitespace elegantly?

What white space do you want to remove and what do you consider elegant? In 
general, FM assumes that all data characters in your document are 
significant, including white space characters. However, to allow you to 
indent your XML markup, when opening an XML document, the DocBook client 
that comes with the DocBook starter kit condenses a sequence of white space 
characters into a single space in the content of most elements. You can 
also use a custom FDK client of your own or XSLT to process white space (or 
any other content) however you wish.

>@ find an easily understandable guide to using DocBook/Frame?

DocBook and FrameMaker are two separate tools, and each is documented on 
its own. Rather than looking for documentation on how they work together, 
look for explanations of each of them separately. Then FM's DocBook Starter 
Kit online manual will make sense.

         --Lynne


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