M100353: Preparing portal API documentation

Documentation for the portal API is embodied in the product code. Here's how to get it into FM file for print, PDF, and so on.

Preparing portal documentation

Reference documentation for the portal is drafted inside the portal source files by the engineers. Chris Grinton has an extraction tool and XSL conversion that turns this into an intermediate XML file correctly formatted (we hope! :-) for input to the following process. This runs automatically on each product build.

Set up your structure application environment

  1. Ensure that you have copied the entire directory structure for the portal chapter to your PC. Specifically, you must have the app subdirectory that includes MGSportalTemplate.fm, portal.dtd, portal_EDD.fm, and portal_rules.fm.
  2. Ensure that your structapps.fm file contains the definition of the MGS Portal application. The structapps.fm file lives in your FM 7 installation, normally somewhere like C:\Program Files\Adobe\FrameMaker7.0\structure. The definition it should include looks like this (at time of writing...):

    Application name: ManageSoft Portal DOCTYPE: documentation DTD: C:\doc\src\customization\portal\app\portal.dtd Read/write rules: C:\doc\src\\customization\portal\app\portal_rules.fm Template: C:\doc\src\customization\portal\app\MGSportalTemplate.fm Namespace: Disable Use default API client. XML Display Encoding: FrameRoman XML Export Encoding: UTF-8 CSS2 Preferences: Generate CSS2: Disable

  3. Ensure that all your file versions are up to date!!!

Doing the conversion

  1. To receive the latest copy of the intermediate XML file, ask the Build Police for the latest build location ofinst/doc/PortalReference.xml.
  2. Browse the file from that location, and in the web browser do a File > Save As to save it with a useful name into your working portal directory (C:\doc\src\customization\portal).
  3. Open the file in a flat text editor (such a Notebook) (NOT in Word or FM).
  4. On the first line, between the <xml...> tag and the <documentation> tag, insert the doctype and DTD spec: 
    <!DOCTYPE documentation SYSTEM
    "C:\doc\src\customization\portal\app\portal.dtd">
  5. Immediately after the <documentation> tag and before the first <namespace...> tag, insert the following tags and text: 
    <intro>
       <head>Portal API reference</head>
       <section><para>This chapter provides a detailed reference for the
       factory-supplied APIs available to the operations portal. For an introduction
       to extending and customizing the portal, see the previous chapter.</para>
       </section>
</intro>
  6. The start of your file now looks something like this: 
    <?xml version="1.0" encoding="Windows-1252"?>
  <!DOCTYPE documentation SYSTEM
       "C:\doc\src\customization\portal\app\portal.dtd">
    <documentation>
       <intro>
         <head>Portal API reference</head>
         <section><para>This chapter provides a detailed reference for the
         factory-supplied APIs available to the operations portal. For an introduction
         to extending and customizing the portal, see the previous chapter.</para>
         </section>
       </intro>
       <namespace...
  7. Save the amended file.
  8. Open the amended file in Structured Framemaker.
    • Answer the question "Use structure application" (if asked) by picking "ManageSoft portal" from the pulldown list.

Post-processing

  1. Change the name of the previous version of this chapter, for example to "old_portal_reference.fm". You will use this to identify what has changed and needs review in the new version.
  2. Change the filename by doing a File > Save As. The filename must match the one used in the book for theCustomization and Extension manual. Currently the name is "06_portal_reference.fm".
  3. Update the book, including regenerating the table of contents.
  4. Hand tune the TOC by adding the Heading 1 no TOC title Contents, and adding forced line breaks in chapter titles that are too long for the format.
  5. Use FM's file differencing feature to flag what has changed in the new version by comparing it with the one you renamed at step 1. Review new material, provide feedback to the author-engineers, and loop.
  6. Save as PDF to provide an e-book copy for engineers (make sure that hyperjumps are turned on and the heading structure is sensibly indented!); or prepare the PDF for press version.
Support Admin -

Comments

Powered by Zendesk