Convex Press Web

Structuring Documents with FrameBuilder

Previous Page | Next Page | Contents | Convex Press Home | Help

Process

Exporting

When the document's structure is valid, export the document to SGML. For exporting, use HPTAG -> Export (only available in FrameBuilder on icarus). Any exporting errors encountered will be logged by the HPTAG application and displayed once the export has completed as much as it can.

Setting up to export

Performing the HPTAG export requires a specific directory setup in your working directory. This setup is described below.

Note

Disk space on icarus is reserved for doctools development; please work out of the bipod:/docs/collections file system. This file system is mounted on icarus:/rmt/bipod/docs/collections.
  1. Create a directory called "login.collection" in the bipod:/docs/collections file system.

    To do this, change to the /docs/collections directory, and issue the following command: 

    % mkdir login.collection
    where

    login
    is your user name.
  2. Create a directory called "books" in your collection directory by typing the following command: 
    % mkdir login.collection/books
  3. Create a directory in your "login.collection/books" directory for the purpose of storing the SGML version of your file.

    Example:

    If I have the first chapter of a book called "Foo User's Guide". I would do the following: 

    % cd /docs/collections/login.collection/books
	
    % mkdir 01fooug
Your directories are now ready for the SGML export process.

Performing the export

You can export your document to SGML once the directory setup outlined in the preceding section has been put in place.

  1. Open the file in Builder on icarus.
  2. Select HPTAG -> Export from the menu bar. A dialog prompts you to enter a name for the SGML output file.
  3. Save the output file as file.sgm in the books subdirectory you created in Step 3 of the preceeding section "Setting up to export."

    file must be the same as the directory name you created in Step 3 of "Setting up to export." Also, file must not exceed 8 characters and contain no period.

  4. Wait until you get the "SGML write completed" message. If there are any errors, the appropriate error logs will appear.
  5. Correct any errors that are listed in the exporting log (see Figure 8).
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.

Ignore the following messages:

See the "Solutions to exporting errors" section for more information on exporting error messages.

Following the export, you should have the following files in your file directory:

Exporting a book file

Export the book file after having exported and checked the individual files of the book.

  1. Generate a book file called book.struct which contains all the *.struct files--including the title page and copyright information. The preface must be wrapped as a chapter (the top-most element must be a <Chapter> element).
  2. Resolve cross-references. Unresolved cross-references will appear as question marks online.
  3. Import element definitions from the chapt.struct template into the new book file.
  4. Validate the book's structure. See Figure 6 in this chapter for a valid structure view of a book file.
  5. In the Element Validation dialog box, select Entire Book. If any of the component files are not valid, the book file will not be valid.
  6. Once the book is valid, select HPTAG -> Export in the book window.
  7. Run mkbook on the newly created book SGML output. The "Compiling your file for PinPoint" section shows the usage for mkbook.
  8. Use PinPoint to view the book online.

Solutions to exporting errors

The following list, which is arranged alphabetically, contains several HPTAG export errors/warnings and their solutions:

Cross-ref marker is found in an invalid location, click here...
Follow the hyperlink in the error log to the marker.
ID/IDREF string contains characters that may cause...
Follow the hyperlink in the error log to the troublesome marker, then wrap the marker in an <IndexToken> element.
Invalid characters are deleted during export, click here...
This message is generally caused by hard spaces. Follow the hyperlink. If there are hard spaces in the document at that point, turn off the Smart Spaces feature and replace the hard spaces with regular spaces using the Find/Change command. Always turn Smart Spaces back on.
Simple anchored frame is discarded, click here to go to it.
This message is generally caused by Frame 3.1 side-heads. Fix each side-head by hand (remove the anchored frame; place the heading text in an H1 paragraph and the paragraph text in an H1para). mifmucker automates the conversion from Frame 3.1 to Frame 4.0. See the "mifmucker" section for more information on mifmucker.
Simple cross-reference is discarded, click here to go to it.
Wrap the discarded cross-reference in the <CrossReference> element to prevent deletion.
Simple marker is discarded, marker type = 0, click here...
Follow the hyperlink in the error log to the troublesome marker, then wrap the marker in an <IndexToken> element.
Simple marker is discarded, marker type = 3, click here...
Follow the hyperlink in the error log to the troublesome marker, then wrap the marker in an <IndexToken> element.
Simple table is discarded, click here...
Wrap the discarded table in a <Table> element to prevent deletion.
Table cell is not structured.
Ignore this message.
Variable converted to text string, click here...
Ignore this message.
If you encounter any exporting messages that are not listed here, please send email to scox@convex.com relating the message and what you did to fix the problem.

Previous Page | Next Page | Contents | Convex Press Home | Help

Please submit comments and questions about these pages to scox@convex.com