Process

This chapter provides an overview of the structuring process. Details of converting documents are also in this chapter.

The chapter is broken down into eight parts:

• Structuring overview

• Preparing to structure

• Generating structure

• Validating

• Saving to SGML

• Viewing your file online

• Proofreading your online file

• Cleaning up

---

Structuring
overview

This section presents the general steps and procedures needed to put a document online in either DynaText or PinPoint. A graphical representation of the structuring process is given Figure 1.

The procedures in the remainder of this manual cover the details of the conversion process. Any questions that the overview brings up are answered in the remaining sections of this manual.

A graphical overview

Figure 1 gives an overview of the structuring process at the file level. This process assumes the file to be converted uses the Convex FrameBuilder V4.x template or the FrameMaker V4.x template (though these templates can be used in FrameMaker V5.x).

Figure 1 Overview: converting OpenBook to DocBook

Figure 2 Overview: saving to SGML

---

Preparing to structure

This section tells you what tasks you need to perform in preparation for structuring a file.

NOTE: Always back up your files before converting them. Also, take one file through the entire conversion process to get a feel for how all the parts work together in producing the online document--in particular, the conversion table may not be mapping some fonts that you use frequently to elements.

See the "Available utilities" section on page 25 for information on the utilities needed to perform the various tasks involved in converting a document to FM+SGML using the Ramer template. The tasks themselves are discussed in the remainder of this chapter.

1. Copy the set of templates to a subdirectory in your working directory, as indicated in the following example:

   % cd my_working_directory

   % mkdir templates

   % cd templates

   % cp -r /usr/spool/globdata/etc/FrameTemplates/FMSGML/* .

   Alternatively, you can open template files by selecting File ->New -> Convex/desired_template then save the individual file to your working directory. You must save the template before FM+SGML allows you to use it for importing element definitions or generating structure.

   The File -> New -> ... setup may not be available if you are running FM+SGML on your workstation. If you would like this setup on your workstation, see the section "Running FM+SGML on your workstation" section on page 37.

2. Open the document to be structured in FrameMaker V4.x or FrameBuilder.

3. Show all conditional text in the file. By having all text showing, FM+SGML can generate structure for the entire file. Delete any duplicate figures and tables created for previous editions of the online document. Save and close the file.

4. If you use a script or alias named either maker or makersgml on icarus, temporarily disable the script/alias before using open2doc-1.pl.

5. Run open2doc-1.pl on the file. The open2doc-1.pl script is in icarus:/usr/local/doctools/open2doc/.

   Caution: Do not start an open2doc-1.pl or open2doc-2.pl script if you have one of the scripts currently running.

6. Open the documents listed below in FM+SGML:
   • The document to be structured
   • The appropriate template file (Chapter, Sample_Appendix, and so on)

7. Import the formats from the appropriate template file (Chapter, Sample_Appendix, and so on):

   1. Select File -> Import -> Formats.

   2. Make sure that all the "Import and Update:" options and the "While Updating, Remove:" options in the Import Formats window are selected.

   3. Select name_of_the_appropriate_template in the box labeled "Import from Document:".

   4. Select Import.

8. Import the element definitions from the appropriate template file (Chapter, Sample_Appendix, and so on):

   1. Select File -> Import -> Element Definitions.

   2. Make sure that both the "While Updating, Remove:" options (Format Rule Overrides, Information Inherited from Book) in the Import Element Definitions window are selected.

   3. Select name_of_the_appropriate_template in the box labeled "Import from Document:".

   4. Select Import.

---

Generating structure

Generating structure for a file is the easiest step in converting a file to an online document.

1. Open the appropriate documents:

   • The file to be structured

   • The conversion table

   Assuming you set up your template directory as indicated in the "Preparing to structure" section on page 4, the conversion table is located at my_working_directory/templates/conversion/conversion.table. Otherwise, the table can be opened through File -> New -> Convex/ -> conversion.table on idiom or icarus. You must save the file before it can be used in generating structure.

   NOTE: The conversion table uses paragraph and character tags from the FrameBuilder/FrameMaker v4.x templates. If your files use tags not found in those templates--or you modified the existing tags--the structure generation will be hindered.

2. Select File -> Utilities -> Structure Current Document from the menu bar in FM+SGML.

3. Select the conversion table from the resulting window.

4. Select the Add Structure button.

5. FM+SGML will generate a nameless, structured version of the file. Name the file file.fm5.struct where

   file

   denotes the chapter number and the book of the file you are structuring. For example, the structured version of Chapter 1 in the book Foo User's Guide could be named 01fooug.fm5.struct.

   NOTE: After generating structure, your converted file may have many blank pages following the text. These pages are added due to a bug in FM+SGML that mifmucker (through open2doc-1.pl) reveals. Delete these pages using the command Special -> Delete Pages.

---

Validating

Once a file's structure has been generated, it must be validated. At its simplest, validating is a game of connecting the dots--only the dots are elements. You achieve a valid structure by arranging the elements in a manner that conforms to the Element Definition Document (EDD).

The EDD governs the organization of the document by allowing only certain elements to be used within or following any particular element. See Peter's course notes for more information on how EDDs work. The course notes are FrameMaker V4.x files and are located in icarus:/home/cash/work/training.

The Structure View and the Element Catalog

The Structure View window and the Elements window (commonly referred to as the Element Catalog) are crucial to the validation process. The Structure View displays the structure of the document, while the catalog lists elements.

In the FM+SGML document, select the [ ] square at the top of the right scroll bar of the FM+SGML window to display the Element Catalog. Then select the square containing the "bubble diagram" immediately below the [ ] square to open a Structure View window.

Figure 3 Displaying the Structure View and the Element Catalog

To determine which elements are valid for a particular location in a document, place the cursor in the corresponding location in the structure view and click the left mouse button.

Note how the Element Catalog changes in the next two figures as the cursor location changes.

In Figure 4, the left mouse button was pressed with the cursor between the <Sect2> elements. As indicated by the checkmarks, the first three elements in the Element Catalog are valid (can be inserted "legally") at that position; the plus marks (+) next to check marks indicate that the associated elements are valid at the current level and also at the next deeper level. The question marks next to elements 4 through 8 indicate that those elements are valid for the current location, but if inserted, any sibling and children elements would become invalid.

Figure 4 Element catalog with cursor after <Sect2> element

In Figure 5, the left mouse button was pressed with the cursor between the <Title> and <Para> elements. All the elements visible in the catalog are valid for the new cursor location.

Figure 5 Element catalog with cursor after <Title> element

When viewing the Element Catalog, note that the elements that are valid for the current location of the cursor are at the top of the list, with checkmarks to the left (see Figure 4). (All elements listed may have checkmarks depending on the display option selected.)

To view all elements, select the Options button at the bottom of the Elements window (see Figure 5). In the resulting window, select All Elements.

Having all elements listed is useful because you can wrap text in an invalid element, then move the element (and its text) to a location at which that element is valid. Also, if you define any keyboard macros, having all elements available is sometimes necessary.

With a newly opened document, the Element Catalog defaults to displaying only the valid elements, unless the file had previously been saved with the catalog showing all elements (or some other display option).

Editing in the Structure View

The FM+SGML file can be edited in both the main window and in the Structure View window. In the latter case, editing is restricted to elements; the elements can be cut, copied, pasted, or moved. In Figure 6, the highlighted section of the Structure View corresponds to the highlighted section of the document.

Figure 6 Document and Structure View

Procedure for validating

The list below details actions that you must perform for every newly structured file. If you feel that more of your document should have been wrapped by the conversion table, go back to your FrameBuilder/FrameMaker V4.x and re-tag the paragraphs or characters to match the entries in the conversion table, or if you used template tags that are not being wrapped, request a change in the conversion table by contacting Peter Cash (x4389).

1. Validate all the structure--except for the cross-references:

   1. Change the <NoName> element at the top of a document's structure view to the appropriate element (for example, a <Chapter>, <Appendix>, or <Preface> element).

   2. Look for dashed lines. These lines indicate an invalid progression of elements. Move the first element in the path of the dashed line to another location, or wrap it in an element that is valid in the current location. This new element must also validly wrap the original element.

   3. Look for squares. These squares appear along the lines to indicate a missing element that is required for some previously-used element.

   4. Make sure that all elements are properly nested. An element can be valid in a location even though it belongs two levels up in the structure.

   5. Begin validating by selecting Element -> Validate from the menu bar of the document window. Proceed to locate invalid structures in your document by selecting the Start Validating button. Repeatedly clicking this button sequentially hits any invalid structures in the selected document.

2. (Optional) Run open2doc-2.pl on the file. You do not need to run this script on files that do not contain figures. If you use a script or alias named either maker or makersgml on icarus, temporarily disable the script/alias before using open2doc-2.pl.

   The open2doc-2.pl script fixes figures by changing the fill to 0%. The script is in icarus:/usr/local/doctools/open2doc/.

   NOTE: If your vector graphics rely on an object's being transparent, you will have to also manually fix those graphics to achieve your intended effects.

3. Validate the cross-references:
   1. Double click on the cross-reference in the document window to open the Cross-Reference Window

   2. Select the triangle associated with the Source Type field, then select either

      Elements Listed in Order

      or

      Elements Listed by ID

   3. Select the element in the Element Tags pane that matches the element of the intended cross-reference source text

   4. Select the cross-reference source text from the Source Text pane

   5. Select the appropriate format from the Format field

   6. Select the Replace button

4. After fixing the cross-references, the structure should be valid. Check for validity by clicking the Start Validating button in the Element Validation window (opened by selecting Element -> Validate from the menu bar). The message "Document is valid." is returned when the document's structure is valid; otherwise, locations of invalid structure will be highlighted in the document, and a corresponding message will be displayed in the Element Validation window.

Examples of validly structured documents

Look at the templates for examples of structured documents.

To browse the Chapter template, select
File -> New -> Convex/ -> Chapter. Alternatively, you can open the file at /usr/spool/globdata/etc/FrameTemplates/FMSGML/Chapter.

You may also want to print the template with the element tags showing. To display element tags in FM+SGML, select View -> Element Boundaries (as Tags).

The templates can be very helpful in determing how to wrap items. The template directory contains the following files:

Validating a book

Once you have validated all the files of a book, validate the book file itself--including the TOC, LOF, LOT, and Index, as well as the frontmatter (title and copyright information).

Structuring frontmatter

To structure the frontmatter:

1. Open the template file (title.doc).

2. Cut and paste from your existing frontmatter into the template.

Validating generated files

Although the generated files (TOC, LOF, LOT, and Index) are not saved to SGML (and not needed online), you can validate them and leave them in the book file. (You can also remove them from your book file before saving to SGML.)

To validate a generated file:

1. Add a generated file to the book file by selecting File -> Add File, then choose the type of file to add (TOC, LOF, LOT, or Index).

2. Set up the file to include the following elements (in FM+SGML, you specify the elements to include in the generated file--not the paragraph tags).

   Table 1 Setting up generated files

   Generated file	Set up to include the elements*
   TOC	Appendix, Chapter, Glossary, Index, Preface, Sect1, Sect2, Sect3
   LOF	Figure
   LOT	Table
   Index	Index

   *You may want to include other elements as well, depending on your preferences.

3. Generate the book file, updating all the generated files.

4. Open the generated file and its corresponding template file (SampleTOC.doc, SampleLOF.doc, SampleLOT.doc, or SampleIX.doc).

5. Import the formats from the appropriate template file into the generated file by selecting File -> Import -> Formats and choosing the template file when prompted. Be sure all the options in the Import Formats window are selected.

6. Import the element definitions from the appropriate template file into the generated file by selecting File -> Import -> Element Definitions and choosing the template file when prompted. Be sure all the options in the Import Element Definitions are selected.

7. In the generated file, select Edit -> Select All in Flow then wrap the flow in one of the elements indicated below.

   You will be prompted to select attributes for the new element; do not select any attributes, just choose Wrap Element.

   Table 2 Generated files and elements to wrap them in

   Generated file:	Element to wrap in:
   TOC (Table of Contents)	ToC
   LOF (List of Figures)	LoT
   LOT (List of Tables)	LoT
   Index	Index

8. Delete the contents of the element (ToC, LoT, or Index) but not the element itself.

9. Generate the book to check and update cross-references and to update the generated files. Figure 7 provides a structure view of a book showing the wrapping of front matter and appendixes.

To validate a book select (from the document window menu bar) Element -> Validate... -> Start Validating with the Entire Document option selected. All component files must be valid for the book to be valid.

Figure 7 Valid structure view of a book

After validating a book file, save the book in the SGML format as discussed in the "Saving to SGML" section on page 16.

<BOOK-COMPONENT> elements in the Structure View

Your book's structure view may show an element named <BOOK-COMPONENT>. This element appears when files are added to a structured book.

To validate the book's structure:

1. Make sure each file--for which there is a <BOOK-COMPONENT> element--is structured.

2. Generate the book. During generation, the top-most element of each file in the book is picked up by FM+SGML and placed in the book's structure.

Assuming the file is structured correctly and placed in the book in the right position, the book's structure will be valid when generation completes.

---

Saving to SGML

When the document's structure is valid, save the document to SGML by using the File -> Save as item with the SGML format selected. Any errors encountered are logged by the application and displayed once the save has completed as much as it can.

Setting up to perform the SGML save

Performing the SGML save requires (more accurately, the EBT products require) a specific directory setup in your working directory. This setup is described below.

NOTE: Before saving (exporting) or importing any SGML, you must:

1. Open the following file:

icarus:/work/packages/frame/fmsgml/fminit/usenglish/sgml/docbook/app/sgmlapps.doc.

2. In the sgmlapps.doc file you just opened, execute the command
File -> Developer Tools -> Reread SGML Application File (you only need to execute this command once per FM+SGML session).

3. In the file you are exporting, make sure the SGML application is set to DocBook; check this by executing the command File -> Set SGML application. Change the SGML application to DocBook if need be.

1. On icarus, go to the directory indicated below:

   % cd /work/cold/collections/test_cols/docbook/books/

2. Issue the following command:

   % mkdir MyBook

   where

   MyBook abbreviates the title of your book. MyBook must not exceed 8 characters and must contain no period.

3. Make the figures subdirectory:

   % mkdir MyBook/figures

Performing the SGML save

You can save your document to SGML once you have performed the steps outlined in the preceding section. The SGML save can be performed on a single chapter or on an entire book.

1. If you are saving a single file to SGML, open the file in FM+SGML. Place your cursor in the main flow of the document.

   If you are saving a book to SGML, generate a book file called book.fm5.struct that contains all the *.fm5.struct files--including the frontmatter (title page and copyright information) and generated files (TOC, LOF, LOT, Index). The validation of generated files is discussed in the section "Validating a book" section on page 13.

   Be sure to generate the book to update cross-references. Unresolved cross-references will appear as question marks online.

   Validate the book's structure. See Figure 7 in this chapter for a valid structure view of a book file.

2. Select File -> Save as from the menu bar, then select the SGML format and enter a name for the SGML output file.

3. Save the output file as MyBook.sgm in the MyBook subdirectory you created in Step 2 of the preceeding section "Setting up to perform the SGML save."

   NOTE: FM+SGML considers an SGML export as a save operation--there is no confirmation of a successful export. (This behavior differs from FrameBuilder.)

4. If the save cannot be completed, you will get the message "SGML save aborted." Examine the error log to determine why the save was aborted. Correct any serious errors that are listed in the exporting logs; you can safely ignore many of the messages.

   Some messages have hyperlinks to the errors. Click on a link to go to the source of an error, and then determine the best manner in which to fix the given problem. Call Peter Cash (x4389) or Scott Cox (x4710) with questions.

Error messages from the SGML save

There are numerous warning and error messages displayed after the SGML save is completed. Of course, you also get messages if the save is not completed. Listed below are some of these messages and methods to correct the corresponding problems.

• Cannot export the FrameMaker+SGML graphic element(Graphic) in the specified graphic format(TIFF)

  This message is generated when there is not a figures subdirectory in the directory being exported to. FM+SGML cannot export the element because it is trying to export the graphic into a subdirectory that does not exist.

  Make a figures subdirectory (as described in the section "Setting up to perform the SGML save" section on page 16) and perform the SGML save again.

• Length of name, number, or token exceeded the NAMELEN limit.

  This message is generated if the sgmlapps.doc file has not been read. Read the file as described in the section "Setting up to perform the SGML save" section on page 16.

• Could not find external general entity graphic X (figY.tif)

  (X and Y are positive numbers.)

  This message is generally bogus; you can safely ignore it in most cases.

---

Viewing your file
online

After exporting your file to SGML, you can view it online using DynaText (or PinPoint). However, you first need to set up DynaText (or PinPoint) and compile the SGML file.

Setting up DynaText (or PinPoint)

In order to use DynaText (or PinPoint) to read your files online, you should perform the following steps on icarus:

1. Make sure /usr/ebt/bin (or /usr/pinpoint/bin) is in your search path.

2. Copy /usr/ebt/data/.ebtrc into your home directory on icarus, naming it .ebtrc.mine:

   % cp /usr/ebt/data/.ebtrc ~/.ebtrc.mine

3. Set environment variables so that both DynaText and PinPoint use the .ebtrc.mine file. In C-shell notation, you would set the variables as indicated in the following commands:

   % setenv EBTRC /home/login/.ebtrc.mine

   % setenv RCPATHNAME $EBTRC

   where

   login

   is your user name.

4. Edit your .ebtrc.mine file to contain the following line:

   COLLECTION /work/cold/collections/test_cols/docbook=My Collection

   where

   My Collection

   is any string you want

5. Copy the styles.ent file into the directory where you exported the file (book):

   % cd /work/cold/collections/test_cols/docbook/books/MyBook

   % cp /work/cold/collections/test_cols/docbook/ents/styles.ent .

   where

   MyBook

   is the book directory you created in the section "Setting up to perform the SGML save" section on page 16.

   NOTE: This styles.ent is only for informal, everyday use. You may need a book-specific styles.ent file for performing online QAs. Contact Peter Cash (cash, x4389) for more information.

   Compiling your file for DynaText (or PinPoint)

   In order to view your file in DynaText (or PinPoint), you will need to "compile" your SGML file with mkbook. To do this, use the following command on icarus (make sure /usr/ebt/bin is in your path):

   % mkbook -fa -col /work/cold/collections/test_cols/docbook MyBook

   where

   MyBook

   is the book directory you created in the section "Setting up to perform the SGML save" section on page 16.

   Reducing graphics size (shrinktif.pl)

   Currently, the SGML save produces graphics in the tiff format that are too large to use. The script shrinktif.pl reduces the size of the graphics. This script is located in icarus:/usr/local/doctools/bin/.

   If you already have /usr/local/doctools/bin in your path but the script is not being found, execute the rehash command:

   % rehash

   Use the script on the tiff files in your figures subdirectory as indicated below:

   % cd /work/cold/collections/test_cols/docbook/books/MyBook/figures

   % shrinktif.pl [-size value] *.tif

   where

   MyBook

   is the book directory you created in the section "Setting up to perform the SGML save" section on page 16.

   -size value

   is an optional command-line option you can use to control the amount figures are reduced. Valid value amounts are: 0.375, 0.5, 0.625, and 0.75.

   NOTE: After using the shrinktif.pl script, your graphics may still be too large or may be unreadable. Check the graphics immediately after running the script by using the xv program (in icarus:/usr/local/doctools/bin). Also, the graphics may be rendered ineffective by the open2doc-2.pl script--this problem can be fixed manually. Ask Ken Harward (x4980) or Scott Cox (x4710) for assistance.

   Using DynaText (or PinPoint)

   The file can be viewed by performing the following steps:

   1. Start DynaText on icarus:

      % /usr/ebt/bin/dtext

      Start PinPoint on icarus:

      % /usr/pinpoint/bin/pinpoint

   2. Select your collection (as defined in your .ebtrc.mine file) in the Collections list (left window).

   3. Double-click on your book's name in the Books list (right window).

   4. Read away.

   When you make changes to your file and re-export it, overwrite your previous SGML output file and run mkbook on the new file. Do not keep creating new directories each time you change a file.

   See PinPoint's online help for information on customizing the appearance and behavior of PinPoint.

   ---

   Proofreading
   your online file

   Once you have your file in DynaText (or PinPoint), you must review it. For information on reviewing DynaText (or PinPoint) books, see the PinPoint Book QA Process and Checklist at http://wwwcpress/pinpoint/ppbookQA.html.

   Repeatedly adjust the document`s element structure (exporting and viewing the results) until the online document satisfactorily matches the hard copy.

   DynaText/PinPoint stylesheets

   Stylesheets determine how an element is formatted in DynaText and in PinPoint. If your document is validly structured but does not look right online, you can request a change to the stylesheets.

   Filing bugs against the stylesheets

   The PinPoint Style Issues and bugs web page (http://wwwcpress/pinpoint/ppstyle_changes.html) defines the procedure for requesting stylesheet changes.

   ---

   Cleaning up

   After you are finished testing your book, please delete your files from the icarus file system, as indicated below:

   % rm -r /work/cold/collections/test_cols/docbook/books/MyBook

   where

   MyBook

   is the book directory you created in the section "Setting up to perform the SGML save" section on page 16.

   ---

   [ Previous Page ] [ Next Page ] [ Contents ] [ Getting help ]