Conference tnpubs::nacleaf

84.0. "Interleaf -> SDML -> Bookreader Procedure" by ISOISA::HAKKARAINEN (All the benefits of garlic...) Wed Mar 17 1993 15:15

From:	TNPUBS::GOVONI "DTN 226-7222 - For Duty and Humanity!  13-Mar-1993 2056" 13-MAR-1993 20:58:10.37
To:	JOHN,MICK,OWEN
CC:	GOVONI
Subj:	Interleaf to Bookreader procedure - ready for anyone who wants it!


		Interleaf -> SDML -> Bookreader Procedure

3/12/93

The Interleaf to SDML converter searches and marks Interleaf documents for 
indexes, chapter heads, head 1, figures, exhibits, list elements, glossary 
terms, and glossary definitions.  It then uses the Interleaf to ASCII 
converter (with no intervention on your part) to create an ASCII document.  
It finishes by creating an SDML document with many tags in place.

This procedure describes how to run the converter, clean the SDML files,
and capture all graphics with the RAGS tool.




PREREQUISITES:

1.  Verify that your Interleaf desktop has the Interleaf to ASCII filter by
    selecting a document, then Custom -> Misc -> Filter -> Interleaf-to-
    ASCII.  If the Interleaf-to-ASCII filter does not appear as a selectable
    item from Filters, you need to add this filter as per Karl Hakkarainen's
    instructions.
    
2.  Copy your book(s) to your desktop and save all Interleaf files as ASCII.  
    Saving as ASCII -> Forced works best.  Normally, you should have the final 
    Interleaf version of your book stored in the appropriate drawer in the 
    Comm cabinet.

NOTE:  If any of your files has a lot of complex art, you can delete each 
figure (but not the figure title).  This will save you possible converter
errors and cleanup time.

3.  Create a directory in your TNPUBS account for each book that you plan
    to convert.

4.  Copy John's converter to your iws5desktop directory.
    John's converter is located in:
	USER$662:[HARRISON.PUBLIC]*.*

5.  Make sure you can run RAGS.  What I do is:

   a.  Create a 2nd TNPUBS account.
   b.  Type RAGS.
   c.  The system comes back with a command to set display back to your node.
       Copy the command and use your workstation name as the node name.
   d.  Type RAGS again and the RAGS windows appear.

6.  Have a hard copy of your book available for reference.  You'll need it when
    cleaning up the SDML files.

WARNING:  There is a Bookreader bug that involves 75 and 100 dpi workstations.
Bookreader files created on either of these workstations is not compatible
with the other.  All our 3100s are 75 dpi, while the VXT 2000 are 100 dpi.  
Because of the nature of the bug, I and others recommend that you only create 
Bookreader files from 75 dpi workstations.  In particular, do not screen 
capture graphics on the 100 dpi machines.  They will not show up correctly on 
75 dpi machines.


OVERVIEW:

Here is a quick overview of the conversion process:
 
1.  Copy the book to your desktop.
 
2.  Delete the cover, index, and TOC files as well as backmatter files 
    (backcover, reader comments, mailer, and order page).  

3.  Save all files as ASCII.

4.  Screen capture all graphics using RAGS.  Export files as Bookreader and 
    SDML.

5.  At DCL prompt in your desktop directory, type RUN CONV.  Convert all
    your files except the title and copyright pages. 

6.  When the program prompts you for an output file name, specify the directory 
    pathname that you created for this book, as well as a file name.

7.  If you received any errors during the conversion process, check each 
    SDML file for completeness.  

8.  Clean up the .SDML files.

9.  Create a profile, then process the document as a Bookreader file.



DETAILED PROCESS:

This process is divided into three sections:  Capturing Screens, Converting
to SDML, and Cleaning SDML files.

First, make sure all prerequisites are done, then delete the Cover, blanks, 
mailer, reader's comments, back cover, TOC, and index files.




Capturing Screens:


1.  Start up RAGS.  Two screens appear: the left screen contains lots of 
    information, the right screen is blank except for the menu bar.  Iconify 
    the left screen.  You will need the other screen for screen captures.

2.  Set the RAGS screen to one side of the Interleaf screen.  You will need 
    to reduce the width of the RAGS screen in order to see the complete 
    Interleaf figure when you open the file.

3.  In Interleaf, open the first file and go to 1st figure, graphic, or table.


NOTE:  To save time, you could open the book files in the Comm Cabinet, which
are not saved in ASCII.  Opening files saved in ASCII takes longer than 
opening normal Interleaf files.

NOTE:  You can capture complex tables and any type of graphic.  It is a lot
quicker to capture tables than to code them.  You can use the online popup
tags (described in the Cleaning the SDML Files procedure) to display any tables 
and graphics that do not have figure titles.

4.  Select View (in Interleaf) and turn all markers off.  

5.  Use View -> zoom -> numeric to increase screen size.  (Larry Cook 
    discovered that the figures should be increased in size for them to 
    be readable in Bookreader.)  Using 1.2 (120%) seems to work best for the 
    DECmcc figures and examples.  You might need to use a different percentage.

6.  Center the figure on the screen and make sure that the cursor is not in 
    the figure.

7.  In RAGS, select View: Screen Capture.

8.  While still in the RAGS screen, press return to make the cursor an X.

9.  Move the cursor to the upper left corner of the figure.  Do not include 
    the figure title or the figure rule.  Click and hold MB1, then drag the 
    cursor to the bottom right corner of the figure. A box surrounds the whole 
    figure.  Let go of MB1.

10. Move the cursor over to RAGS screen.  You will see a box with a top, 
    middle, and bottom horizontal line.  Center this box as much as possible.
    Click MB1 to release the figure.

11. In RAGS, select File: Export.  Configure the export screen to have 
    Bookreader and SDML output.  Turn off EPS output.

12. At the top of the exporter screen, type in your pathname and file name.  
    The pathname should be the directory name that you created for the SDML 
    files.  For the file name, I have been using the convention Cx_y, where 
    x is the chapter number (or appendix letter) and y is the figure number.
    For example, C2_4 is figure 2-4.

13. Click on OK.  The files are created in your directory.  This happens 
    quickly.

14. In the RAGS screen, select Edit: Delete ALL to remove the figure.  A dialog
    box asks you for confirmation.  Select yes.

15. Repeat for all figures.  For structured doc, I strongly suggest capturing 
    all exhibits whether or not they are illustrations or word examples.

NOTE:  After capturing the first screen, you can capture screens at the rate of 
       1 every 30 seconds.

16. When you are done with an Interleaf file, I suggest closing it without 
    saving any changes.



Converting to SDML:

You can either convert one or all your files at once.  I believe that it is 
easier to convert all your files at once.

NOTE:  Do not convert the title page and copyright page.  Instead, you need to 
       create a frontmatter SDML file.  I have a template for the DECmcc title,
       copyright, and preface pages.


1.  At the DCL prompt (in your desktop directory), type RUN CONV.  Follow the 
    prompts.  Be sure to enter the full pathname for each file.

                 ex. (from iws5desktop directory):

                        file: [.use_boo]filename.doc

2.  Follow the prompts.  

3.  When the program prompts you for an output file name, specify the directory 
    pathname that you created for this book, as well as a file name.  The 
    converter will place the files in your specified directory and it will
    add a number and the SDML extension to each file.

    For example:

		[govoni.use]ch

    The converter will place in [govoni.use] the files ch_0.sdml, ch_1.sdml,
    ch_2.sdml, etc.

4.  If an error appeared during the conversion, you will have missing text.  
    Check the end of the file for completeness.  Usually, this is caused by 
    a complex figure.  Go back to the Interleaf file, delete the figure 
    (but not the figure title), then rerun the converter.

    Also, check for ### or NNNN.  These extra characters denote places where 
    text is missing.


Here is the probable status of the SDML files after conversion:

  o  The output file contains DOCUMENT template information such as <p>, 
     <le>, <head1>, etc. markings.

  o  The <list>(unnumbered), <list>(numbered), and <endlist> tags are not
     in the files.  For lists, all bullets were replaced with w and all
     numbers in a list still remain.

  o  The head and chapter tags are missing the closing parentheses.

  o  All exhibits are marked with:

	<Figure>(Exhibit x-x
	Title of the Figure
	<figure_attributes>(keep)
	<figure_file>(Bookreader\filename.brf\?)
	<endfigure>
	The text within the figure follows the <endfigure> tag, unless you
	deleted the figure from the Interleaf file.

  o  All index hits are marked with an <x>, but closing parentheses and any 
     <XS> tags are missing.

  o  All tags requiring symbols are missing the symbol.

  o  All graphics in text, such as arrows and trademarks, are missing.
 
  o  Text that was bold or italic is now normal text.

  o  Interleaf components not recognized by the converter do not have any 
     tag associated with the text.  For example, the converter does not 
     recognize Head2 or Head3.



Cleaning SDML Files:


The following lists a number of shortcuts I found to automate the cleanup 
process:

  o  Verify that the complete file was converted before cleaning the file.
     Do this by checking the end of the file and the last page of that section
     in the hard copy document to verify that they match.

  o  For chapter and head tags:

     1.  At the beginning of the file, after the first set of tags, delete
         the chapter number.

     2.  Close all parentheses on all head and figure tags.  

     3.  Create a symbol for each of these tags.  To do this, you can type 
         each symbol, or use the following command to generate symbols 
	 automatically:

	  $DOCUMENT/GENERATE_SYM/PREFIX=xxx

   	  xxx is anything you choose.  I use the letters hd.  The program 
 	  places the symbol in all chapter and head tags along with a number.
	  For example, the first tag would be hd1, then hd2, etc.

         I found that this command gave me an error, but worked fine anyway.

     4.  For structured documentation, we sometimes use a 2nd level head.  This 
         converts over as a line of text with no tag.  Add a <p> tag, along 
	 with an emphasis tag to make it bold.  For example:

	 <p>
	 <emphasis>(When Performing this with the FCL Interface\bold)



   o  For indexes:

      For those not familiar with SDML, here is the format of using index tags:

      <x>(entry)
      <x>(Primary entry<xs>subentry)
      <y>(entry<xs><emphasis>(See) other entry)
      <y>(entry<xs><emphasis>(See also) another entry)

      Here are some substitutions you can use.  I use the word "space" in these 
      examples to denote one space:

      1.  Substitute:  space space space <x>(space"   
          For:   <x>(    
           - do this globally.

          If there are index hits within text, three spaces are added.  This 
	  substitution removes those extra spaces.

      2.  Substitute:  <x>(space"   
          For:   <x>(     
	  - do this globally.

          Because of word wrapping, not all the index tags are caught 
	  in step 1.

      3.  Substitute:   ",space"   
          For:  <xs>       
	  - do this one at a time.

      4.  Substitute:  ">    
          For:   )               
	  - do this one at a time

      5.  Index hits within figure titles are not changed to an <X> tag by the 
          converter.  
	  Substitute:   !Index,space"   
	  For:   <x>(   
	  - do this globally.
 
      6.  Because of word wrappings, not all instances of the above are caught.
          You need to search for all <x> tags and verify the syntax.

      7.  Look for a "see" or "to named" in each index hit.  If you find a 
          "see," you need to change the <x> tag to a <y> tag.  Also, the 
	  converter will always print "see" and never "see also."  You 
	  need to check your hardcopy index to verify which you should use.

      8.  If you find a "to named," this index hit spans more than one page.
          Determine where the index hit ends, then use the following syntax:

  	  At the index hit, use:  <x>(entry<xs>subentry\begin)
	  Where the index hit ends, add:  <x>(entry<xs>subentry\end) 

  o  For figures and references:

     1.  Change all references to figures and tables to <reference> tags, so 
         that Bookreader will see them as hot spots.  For example:

         Substitute:   Exhibit 1- 
	 With:         <reference>(EX1_

         In this case Exhibits 1-1 and 1-2 become <reference>(ex1_1 and 
         <reference>(ex1_2

         Go back and close the parantheses on all reference tags.

     2.  Search for <FIGURE> tags.  You need to find the figure title (usually 
         below this tag) and move it to the right of <Figure>(

     3.  Because you replaced all Exhibit text with reference tags, it should 
	 look like this:

	 <FIGURE>(Title of Figure\<reference>(EX1_2)

	 Delete "<reference>(" to make it look like:

         <FIGURE>(Title of Figure\EX1_2)


     4.  Fill in the figure filename in this tag:


	 <figure_file>(bookreader\filename.brf\??)

	 Replace filename.brf with the figure filename.brf.  For example,
	 (if you used the conventions I suggested when capturing screens) the 
	 following shows the filename for Figure 1-2:

	 <figure_file>(bookreader\C1_2.brf\?)


     5.  Replace ? with a figure size.  Go to to the SDML output of this 
         figure (for example, C2_4.SDML) and look for the first figure_file
	 tag that has bookreader after it.  For example:

	 <FIGURE_FILE>(BOOKREADER\[GOVONI.ALARMS]C2_10.BRF\23.2)

         In this example, copy the number 23.2 to your tag and delete the 
	 question marks).

     6.  The convertor converts all text from each figure and leaves it in the 
	 SDML file.  You need to delete all this text, which starts after the 
	 <endfigure> tag.  BEWARE: Some index hits might be inside those 
	 examples labelled as figures.

     7.  For graphics and tables without figure titles, you need to create 
         an online popup, as follows:

	<online_popup>(Brief Description)
	<Figure>
	<figure_attributes>(keep)
	<figure_file>(Bookreader\filename.brf\?)
	<endfigure>
	<endonline_popup>	

	The Bookreader file will create a hot spot that looks like this:

		BRIEF DESCRIPTION: Click on here to see Brief Description.

	The location of the <online_popup> tags determine where this sentence
	appears.


  o  For syntax:

     Use <code_example> before the command line, and <endcode_example> after 
     the command line.

     The converter creates <display>(keep) tags for some examples.  I find
     that the <code_example> tag is more flexible.  For example, it allows
     you to use the <emphasis> tag to create italics for syntax variables.

     During the conversion, the spacing of examples changes. Therefore,
     insert spaces so that the examples line up.



  o  Lists:

     1.  Search for <LE> tags.  Using your hardcopy manual, determine the 
         beginning and end of the list.  Start the list (before the first <le> 
	 tag) with <list>(unumbered) for unnumbered lists, <list>(numbered) 
	 for numbered lists, or <list>(alphabetic) for alphabetical lists.  

     2.  End all lists with an <endlist> tag.

         Sometimes there are paragraphs in a list, which is indented and tagged 
	 in Interleaf as a list:para. Make sure that the <endlist> tag comes 
	 after these paragraphs.

     3.  All bullets in Interleaf are converted to w's.  Delete these w's.

     4.  Delete all numbers in the numbered lists.



  o  Bold and Italic text:

     You need to read your manual to find any bold and italic text.  To 
     make text italic:

	<emphasis>(your text)

     To bold text:

        <emphasis>(your text\bold)



  o  Hyphens:

     Replace # with - where appropriate.   


  o  Notes, Cautions, Warnings

     These will appear as text with no tags.  You need to add the <note> tag.

  o  Conversion to Bookreader

     1.  As you complete each SDML file, use the following command to 
         process it to a Bookreader format.  This will verify that all 
	 your coding is correct:

	  $ DOC filename.sdml cup.online bookreader

     2.  Once completed with all files, you need to create a profile file,
         then delete the following tags from the beginning of each SDML 
	 file (copy one set of these tags to the profile):

	 <front_matter>
	 <title_page>
	 <title>(test)
	 <endtitle_page>(this is a test)
	 <endfront_matter>

  o  Glossaries

     The converter provides the <gterm> and <gdef> tags, but not the 
     opening and closing parentheses.  It might be faster to globally
     substitute:  <gterm> 
     For:         <gterm>( 

     and
     Substitute:  <gdef>
     For:         <gdef>(

     Afterwards, simply add the closing parentheses.



PROBLEMS:

  Sometimes you'll get an extra set of figure tags.  Just delete them.


  If you get an incomplete SDML file, go back to the Interleaf file and delete
  the last figure that appeared in the SDML file.  Run the converter again.

  
  If a reference is at the beginning of the sentence, it will not appear
  in the SDML file.  For example:

	Exhibit 1-1 shows you ...

	   will appears as:

	 shows you ...



   The converter does not pick up and Head tags other than head1. For all 
   head2s and lower, the text remains but it has no accompanying tag. 


   Tables come over as straight text and need to be coded.