I'm still working on this.

Archiving FrameMaker, PDF, and HTML

You need to archive files into our doc repository under the following circumstances:

• When writing a book, you need to archive your FrameMaker sources at least twice per week.

• When writing a book, you need to archive a PDF version of your book whenever you want others to review your book. You will definitely have to archive a PDF version of the book for Beta; you might also have to archive an HTML version of the book for Beta.

• When you have finished a book, you need to archive your final FrameMaker sources, final HTML, and final PDF.

The following table summarizes the archiving locations:

This Web page explains how to archive.

Archiving FrameMaker Sources While You Write The Book

While writing a book, you must keep your FrameMaker sources in a standard directory. We ask you do to do this to ensure that:

• Your book will get backed up. Books stored on UNIX or in Source Safe get backed up; books stored on the hard drive of your personal computers do not.

• The other writers on your project will always know where to find your doc sources. Trust me--this will save you and your doc lead a lot of hassle.

• The course developers will be able to find your doc sources.

If your FrameMaker sources are on a Windows system, use an ftp program to archive the files. Note that some ftp programs with GUIs change the case of filenames during the transfer, which causes lots and lots of problems. Do not use such ftp programs. If you ftp program doesn't change filenames, then you are free to use it.

Copy your FrameMaker source files to a directory having the following format:

/udir/fscott/BooksInProgress_FramemakerSources/productversion/title

Don't forget to copy everything needed for another writer to build the book. So, for example, if you have an images or graphics subdirectory, don't forget to copy it as well.

If your FrameMaker source files are stored on DOS, you can use ftp to transfer files. If your FrameMaker source files are stored on UNIX, you can use the UNIX commands to transfer files.

Archiving PDF and HTML While You Write the Book

While writing a book, you must keep your PDF and HTML files in a standard directory. We ask you do to do this to ensure that:

• Other people across the company can learn what's going on in the new release.

• Various engineers, including remote Sales Engineers, can review your docs and provide valuable feedback.

You should update the PDF version of your book once a week. Depending on commitments, you might also have to update the HTML version of your book for Beta tests.

Place your PDF files in a directory having the following format:

/udir/fscott/BooksInProgress_HTMLandPDF/pdf/productversion

Place your HTML files in a directory having the following format:

/udir/fscott/BooksInProgress_HTMLandPDF/html/name_of_product/name_of_book

If your PDF file is stored on DOS, you can use ftp to transfer it. If your HTML source files are stored on DOS, you can also use ftp to transfer them.

If your PDF file is stored on UNIX, you can use the UNIX commands to transfer it. If your HTML source files are stored on UNIX, you can also use UNIX commands to transfer them.

After transferring the PDF or HTML files to the repository, you need to add a notation to the following file, alerting everyone to the new copy: To do so, just edit the following HTML file:

/udir/fscott/DocWebsite/newprogress.htm

You must be user fscott to edit this file.

Edit this file to include a link to your work in progress. The URL of your work in progress is:

http://boreal.divine.com:5019/bip/pdf/product_name/filename.pdf

For example, the URL for the link to the Architect's Guide for the Cheetah project is:

http://boreal.divine.com:5019/bip/pdf/Cheetah/architect.pdf

After adding the appropriate notations to newprogress.htm, you should check your link. So, using a browser, go to Books In Progress page and click your new link.

Archiving FrameMaker Sources After You Finish the Book

After you complete a book, you must place your precious FrameMaker sources in a standard directory. We ask you do to do this to ensure that:

Copy your completed FrameMaker source files to a directory having the following format:

/udir/fscott/CompletedBooks_FramemakerSources/productversion/name_of_book

For example, the FrameMaker source files for the Content Server 3.6.2 release of the Developer's Guide would be in the following directory:

/udir/fscott/CompletedBooks_FramemakerSources/ContentServer3.6.2/devguide

Don't forget to copy everything needed for another writer to build the book. So, for example, if you have an images or graphics subdirectory, don't forget to copy it as well.

If your FrameMaker source files are stored on DOS, you can use ftp to transfer files. If your FrameMaker source files are stored on UNIX, you can use the UNIX commands to transfer files.

Archiving PDF and HTML After You Finish the Book

After finishing a book, you must archive your final PDF and HTML files. Then, you should ask Barry to make your final PDF and HTML files public within Open Market and to our customers.

Archiving Your Completed PDF Files

Place your completed PDF files in a directory having the following format:

/udir/fscott/CompletedBooks_HTMLandPDF/CONTENT_MANAGEMENT/PDF/productversion/

For example, the PDF file for the Content Server 3.6.2 release of the Developer's Guide would be in the following directory:

/udir/fscott/CompletedBooks_HTMLandPDF/CONTENT_MANAGEMENT/PDF/ContentServer3.6.2/

Archiving Your Completed HTML Files

Place your completed HTML files in a directory having the following format:

/udir/fscott/CompletedBooks_HTMLandPDF/CONTENT_MANAGEMENT/HTML/productversion/booktitle

For example, the HTML version of the Content Server 3.6.2 release of the Developer's Guide would be in the following directory:

/udir/fscott/CompletedBooks_HTMLandPDF/CONTENT_MANAGEMENT/HTML/ContentServer3.6.2/DevGuide

Copying Your PDF and HTML Files

If your PDF file is stored on DOS, you can use ftp to transfer it. If your HTML source files are stored on DOS, you can also use ftp to transfer them.

If your PDF file is stored on UNIX, you can use the UNIX commands to transfer it. If your HTML source files are stored on UNIX, you can also use UNIX commands to transfer them.

Building the List of Books

Read this carefully. The system changed dramatically in Fall, 2001. You no longer edit the online.htm file; in fact, the online.htm file is now defunct.

The internal doc site (and soon, the Support doc site) provides documentation through a generated file. In other words, a shell script creates content_docs.htm; you would not edit this "by hand." For the time being, just let Barry generate these files. For those interested, here's how the system works.

Follow these steps to build the list of books:

1. Edit the appropriate XML file.
2. Edit the appropriate product configuration file.
3. Optionally, edit the master configuration file.
4. Run the build scripts.

Step 1: Edit the Appropriate XML File

The administrator (Barry, for now) creates an XML file describing all the documentation for a particular product. For example, the file Content Server.xml describes all Content Server documentation. These XML files are currently all located in the following directory:

/udir/fscott/DocWebsite/Books

Content Server
3.8

ContentServer/3.8/productoverview/index.htm
ContentServer/3.8/productoverview.pdf
140



Content Server
3.8

na
ContentServer/3.8/dbschema.pdf
208

 

Content Server
3.6.3

ContentServer/3.6.3/releasenotes/ReadMe.htm

As with all XML, the XML placed into one of these XML files has to be done just so; if the supplied XML doesn't conform to the DTD, then the XML will be rejected.

2. Edit the Appropriate Product Configuration File

A product configuration file describe all the releases of a particular product. That is, a product configuration file controls which doc releases of a product are made available to customers. For example, an older doc release might only be made available to divine employees, while a brand newer doc release would probably be made available to customers, divine employees, and JumpStart users. The product configuration files are all located in directory:

/udir/fscott/DocWebsite/Books

The configuration files all end with the .ini suffix. So, for example, the configuration file for Content Server is in file Content Server.ini. For example, here's a portion of Content Server.ini:

#Rel    Big     Active  Old     Support Jump    In-Progress
3.6.3   MinorB  Y       N       Y       N       N
3.6.2   Medium  Y       N       Y       N       N
3.6     Medium  Y       N       Y       Y       N
3.5     Major   Y       N       Y       N       N
3.1     Medium  Y       N       Y       N       N
3.0     Major   Y       N       Y       N       N
2.1     Major   Y       N       Y       N       N   

Each line describes one release of the product. For example, the line starting with 3.5 describes release 3.5 of Content Server. There are seven columns on each line; the columns are separated by tabs. The seven columns have the following meanings:

Rel	The release name or number
Big	Indicate the "size" of the release. The choices are as follows: Minor, which indicates that this was a release-notes-only release. MinorB, which indicates that this was a release-notes-only release Medium, which indicates that some books were issued, but it was not a major release. Major, which indicates that the whole docset was touched. You can optionally append a "B" to Minor or Medium. The B suffix tells one of the build scripts (see Step 4) to omit header information in the table for this release.
Active	If 'Y', this release will be made available to divine employees.
Old	If 'Y', this release will be made available to divine employees in the "old releases" table.
Support	If 'Y', this release will be made available to customers and partners in the Support Web site.
Jump	If 'Y', this release will be accessible on JumpStart. (Currently, this column is ignored.)
In-Progress	If 'Y', this release will be made available to divine employees as a book-in-progress. (Currently, this column is ignored.)

3. Optionally, Edit the Master Configuration File

The administrator controls the master configuration file. The master configuration file for content books is stored at the following pathname:

/udir/fscott/DocWebsite/Books/content_configuration.ini

This file is fairly stable. The only time that the administrator would need to alter this file is when a new product is introduced.

4. Run the Build Scripts

The build scripts plow through the product XML files, the product configuration files, and the master configuration file to generate index files.