                       Python Interface Manual Maintenance Notes
                      Brad Whitlock, Tue Feb 1 14:09:35 PST 2005
                      ===========================================

	It is important to follow certain practices when updating the VisIt Python Interface manual so that it continues to have a uniform style. These notes list a few rules of thumb that I've stuck to when I created the Python Interface Manual and when I've updated it. Please try to follow the same rules of thumb because I know where you live.

FrameMaker
===========
	I used FrameMaker (type maker at the command prompt) to write the  Python Interface Manual. I used the version of maker on hyper. I think it is version 5. The suns have version 7 and it issues lots of version warnings about our documents that I don't want to have to worry about so *please* use the version on hyper until hyper is retired. It is pretty quick and responsive if you set your display back to your desktop.

Working on the User Manual
===========================
	Each chapter of the VisIt Python Interface Manual is stored as its own FrameMaker file but there is an overarching "book" file called: Manual.book that you should open when you want to do work on the manual. When you open Manual.book, FrameMaker opens a small window that contains the list of all of the chapter files that are in the book. To open a particular chapter, just double-click on its filename in the list of chapters.
	It is good practice to check out all of the chapter FrameMaker files before starting to edit them because eventually you will have to generate/update the book. There are also Clearcase triggers that prevent multiple people from editing the Python Interface Manual on different branches because FrameMaker files can't be merged from two or more sources. If you ever find that you want to edit a file that you know no one is editing but clearcase won't allow it, the file probably has the SingleBranchName attribute set to prevent multiple users from editing the file. If you want to remove that file attribute so you can edit a particular file, type: cleartool rmattr SingleBranchName file@@ where "file" is the name of the file that you want to check out. Be very careful about removing SingleBranchName because multiple developers should *NOT* update the same files at the same time.
	When you add content to a chapter in the middle of the document, you might cause the page numbers to update in the chapter that you edited. The process of generate/update on the book updates the page numbers in all chapter documents and regenerates the table of contents and index. To generate/update the Python Interface Manual, select File->Generate/Update... from the Book window's main menu to open the Generate/Update window. The Generate/Update window contains controls that allow you to not generate the table of contents and index but you should typically just click the Update button so those documents are regenerated. You might see some consistency messages about colors in the appendices but if FrameMaker opens such a warning message window, click the "Skip" toggle button because those warnings are not particularly important. Once you've generated/updated the files in the Python Interface Manual, save the updated files by choosing File->Save in the book window's main menu.
  

Text
=====
	Most of the text uses the "Body" paragraph tag unless it's a section
heading or figure number, etc. Sections that represent Python source code should use the "Code" paragraph tag. If you're naming an object that is the proper
name of a GUI widget or window, select the name and make it use the "GUIText"
character style so you make it bold the right way. To do this, select the text that you want to highlight by dragging on it with the mouse and then right-click on it so you can access the Characters menu option where you can find the "GUIText" character style. If you refer to another chapter name in the document, make sure to highlight the name of the chapter using the "Chapter #" character style.

Markers
========
	I've used markers throughout the manual for such things as chapter
titles and index entries. A chapter title uses the Header/Footer 1 marker to
indicate the start of a chapter. This marker is used to set the chapter name at
the top of each page in the chapter. I used Header/Footer 2 for top level items
in a chapter (e.g. 1.0, 2.0, ...) because this marker is used to set the topic 
of interest in the footer at the bottom of each page in the chapter. Finally, 
for important things that I'd like to appear in the Index, I used the Index 
marker.
	To create a marker, select the text that you want to mark and open the 
Marker window located in Frame's Special menu. The selected text will be in the
Marker window but you can edit the marker text to be whatever you want. Select 
the appropriate marker type and click the New marker button. If you're changing
an existing marker, the button will have "Edit marker" in it.

Adding a new function reference
===============================
	Functions are usually listed in the manual in alphabetical order. When you want to add a new function reference, find the function that would go before your new function and go to the bottom of the page. I've found it helpful if I type the name of the new function, Enter, and the one line description of the function. Once I've done that, I click on the name of the function and change its paragraph tag to Func-Title-Head. This ends up making a new page for the new function. Next, click on the one line description and change its paragraph tag to Func-Title. Go to the end of the line and hit Enter. This will change the paragraph tag to give you the synopsis. Hit Enter and type the function synopsis, which is a simple one line usage. Go through the rest of the sections as applicable and make sure you use the right paragraph tags. The description section uses the "Body" tag and code examples use the "Code" tag.

Finding unresolved cross-references
====================================
	Sometimes FrameMaker will complain that a chapter contains unresolved cross-references if you've made a mistake at some point. Finding and fixing the unresolved cross-references is easy if you know how. Here's how: open the Find window by clicking on Edit->Find/Change... in the document window's main menu. Once the Find/Change window appears, select "Unresolved Cross-References" from the Find combo box and click the Find button. If there are unresolved cross references, clicking the Find button will find the first one and highlight it in the document window. If you find an unresolved cross-reference, open the cross-references window by selecting Special->Cross-Reference from the document window's main menu. Usually when there is an unresolved cross-reference, you referenced the wrong marker type when you created the figure cross-reference. Use the cross-reference window to select the correct figure paragraph marker and click the Replace button. Repeat the process until there are no more unresolved cross-references.
