[svn-r9348]

Purpose:
    This version updates the procedure for creating PDF versions of
    HDF5 documents to reflect the use of Macromedia DreamWeaver and
    HTMLdoc.  process.txt describes the current RM process in detail;
    the very similar UG process will be described later.

1 files changed, 216 insertions, 146 deletions

diff --git a/doc/html/PSandPDF/process.txt b/doc/html/PSandPDF/process.txt
index a034a6f..92fe2e6 100644
--- a/doc/html/PSandPDF/process.txt
+++ b/doc/html/PSandPDF/process.txt
@@ -1,148 +1,218 @@
 
-========================================================================
-Process for Creating PDF/PS Versions of HDF5 docs from HTML Source Files
-========================================================================
-
-                                              Last modified: 19 Nov 1999
-
-The PDF/PS versions of the HDF5 docs are created from scratch at each 
-release from the primary version of the documentation which is 
-maintained in HTML.  (Assuming, of course, that we continue to produce 
-PDF/PS versions.)
-
-
-1  Using MS Word (Framemaker might work even better, but I have not 
-   tried it yet), open a master file that will serve as the repository 
-   for gathering the document set.  This file will contain all of the 
-   documents to be converted to PDF/PS.
-
-2  Start the file off with the DocSet frontmatter.
-
-3  Open each HTML file and copy it, placing it in proper order, into the 
-   repository file.
-
-   3a Insert Glossary.  (For R1.2, it was appended to UG and to RM.
-      Alternatively, it could be inserted as a separate document.)
-
-   3b Insert Copyright page after each title page, including after 
-      DocSet title page.
-
-4  Adjust the Styles so that type faces and font sizes are appropriate.
-   (I used 10 pt New Times Roman with 9 and 10 pt supplementary fonts
-   in Release 1.2.  I am considering Garamond or New Century Schoolbook
-   for the next release.)
-
-5  Create a trial PDF to make sure all of the images have been imported.
-
-   4a Print the compiled document, selecting "Print to file".
-
-   4b Change the .prn suffix on the output file to .ps.
-
-   4c Convert that PostScript file to PDF with Distiller.
-
-6  Scan the output PDF file for images.  (A visual test of the compiled 
-   MS Word file online is insufficient as an image's presence on the 
-   screen does not guarantee its presence in the PDF file.)
-
-7  If any images are missing, open the appropriate HTML file in Internet
-   Explorer (Netscape at the time of R1.2, did not provide this 'copy' 
-   capability), right click on the image, select copy, select the 
-   offending image or its placeholder in the MS Word file, and paste
-   the image in.
-
-8  Repeat 4 and 5, with variations on 6, as necessary.
-
-9  Add headers, footers, and page numbers in the consolidated file.
-   (NCSA and UIUC on inside of facing footers with page numbers on the 
-   outside, release # and doc title place holder on outside of facing 
-   headers.  "Different first page" so that title page can be header 
-   and footer free.  
-
-10 Once you are sure that
-   -- all of the images are securely showing up in the PDF and
-   -- all of the styles are as you want them,
-   separate the consolidated file into separate files for each document 
-   and for the DocSet frontmatter.
-
-11 Add section break at the title page and the first page of text for 
-   each document.
-
-12 Set page numbering and finalize headers and footers (h/f).
-
-   12a Unset "Different first page" on text section h/f.
-
-   12b Set text section page numbering to start at 1.
-
-   12c Set frontmatter page numbering to start at i.  (R1.2 did not
-       set page numbering in frontmatter.)
-
-13 Reset headers and footers for each document (from the initial generic 
-   setting).
-
-14 Check hyperlinks.
-
-   14a Where reasonable (e.g., not appropriate to leave as internal link 
-       for user instalation), set link as external with full DNS address.
-
-   14b Remove internal links; reword as necessary, giving user sufficient
-       clues to find info in printed docs.  (The links themselves do not
-       survive the Word->PDF translation, so removing a link is generally
-       as simple as removing the color/underline properties.)
-
-15 Check and adjust pagination throughout.
-
-   15a Each chapter (and, in some cases, major sections) begins on an 
-       odd page.
-
-   15b Watch for widows and orphans, examples and sections that start
-       embarrassingly close to the bottom of the page, etc.
-
-   15c Add enough blank pages (with no h/f) so that each document is
-       printed with one completely blank sheet of paper at the back.
-
-16 Insert a TOC into each document as appropriate.  (R1.2 went 3 or 4 
-   levels deep, depending on the document.) 
-
-17 Change Tutorial "Indes of Examples" to point to directory of Tutorial 
-   examples (instead of individual links).  Keep list?
-
-18 Do a visual scan of all docs to ensure that "everything is as it 
-   should be."  (Something has probably been left out of this process 
-   description!)
-
-19 Create PDFs of each document and the DocSet frontmatter.  
-   (See above.)
-
-20 Do a visual scan of all PDFs to ensure that "everything is as it
-   should be." 
-
-21 Create a consolidated DocSet file for those who want a single file 
-   containing all of the doucuments.
-
-22 Correct errors and repeat steps as necessary.  ;>
-
-23 Create distributable PS files by printing the PDFs "to a file"
-   from Adobe Acrobat Exchange.  (This results in mush smaller PS 
-   files than those generated in the above MS Word -> PS process.)
-
-24 Post and distribute PS and PDF copies of
-   -- each document and
-   -- the consolidated set.
-
-
-
-
-  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-  * Copyright by the Board of Trustees of the University of Illinois.         *
-  * All rights reserved.                                                      *
-  *                                                                           *
-  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
-  * terms governing use, modification, and redistribution, is contained in    *
-  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
-  * of the source code distribution tree; Copyright.html can be found at the  *
-  * root level of an installed copy of the electronic HDF5 document set and   *
-  * is linked from the top-level documents page.  It can also be found at     *
-  * http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html.  If you do not have     *
-  * access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
-  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+==============================================================================
+Process for Creating PDF Versions of the HDF5 RM and UG from HTML Source Files
+==============================================================================
+
+                                                    Last modified: 24 Sep 2004
+
+PDF versions of the HDF5 Reference Manual (RM) and the new HDF5 User's Guide 
+(UG) are created from the HTML source at each release of the HDF5 Library.  
+The process is managed through two application environments, Macromedia 
+DreamWeaver (an HTML editing environment) and HTML doc (a conversion tool).  
+This document describes the process in detail for the RM; the process for the 
+UG is very similar and will be described in a subsequent update.
+
+
+The HDF5 Reference Manual
+-------------------------
+1.  Using Macromedia Dreamweaver, define a site that contains all the 
+    documents within doc/html, including html, image, DreamWeaver library and 
+    .book files.
+
+2.  In the ed_libs directory:
+
+      a) Assuming you have your libraries set up for electronic viewing (to
+         verify, check that there is nothing more than a commented note and
+         an ' ' in the 3 aforementioned _Null libraries) drop the code
+         from the actual library into it's respective Null lib, replacing 
+         the  .
+           (EXAMPLE: Take all the code from Footer.lbi and insert it into
+            Footer_Null.lbi, taking care not to remove the commented note.)
+     
+      b) In the now empty library file, add an  .
+      
+      c) Save the libraries and thier respective Null files.
+
+      d) With a library still open (not a Null one) choose 
+          Modify>Library>Update Pages...
+         Look in: Entire Site
+         Check 'Library Items' in the 'Update:' selection.
+         Hit start.
+
+3.  In RM_H5P.html:
+
+      a) RM_H5P.html contains two versions of the 'C Interfaces' function 
+         list.  One is for print use and one is for electronic use.  
+         One should be visible and one should be commented out.  
+         Make sure that the section labelled with 
+         <!-- FOR USE WITH ELECTRONIC VERSION ---> is commented out.
+         (by removing the >s).
+ 
+
+4.  Using HTMLdoc:  
+      
+      a) Open PDF_RM_body.book 
+      
+      b) The Input tab:
+           Document Type: Web Page
+           Input Files:
+             RM_H5Front.html
+             RM_H5.html
+             RM_H5A.html
+             RM_H5D.html
+             RM_H5E.html
+             RM_H5F.html
+             RM_H5G.html
+             RM_H5I.html
+             RM_H5P.html
+             RM_H5R.html
+             RM_H5S.html
+             RM_H5T.html
+             RM_H5Z.html
+             Tools.html
+             PredefDTypes.html
+             Glossary.html
+           Logo Image: none
+           Title File/Image: none
+
+      c) The Output tab:
+           Output To: File
+           Output Path: H5_RM_body.pdf
+           Output Format: PDF
+           Output Options: JPEG Big Images
+           Compression (not critical, change at will): Slider right above 'Fast'
+           JPEG Quality (not critical, change at will): 60
+  
+      d) The Page tab:
+           Page Size: Letter, 2-Sided
+             Top: 0.50in, Left: 1.00in, Right: 0.50in, Bottom: 0.50in
+           Header: Blank, Blank, Blank
+           Footer: Blank, Blank, 1,2,3,...
+           Number Up: 1
+
+      e) The Colors tab:
+           Everything Blank
+           Link Style: Plain
+    
+      f) The Fonts tab:
+           Base Font Size: 11.0
+           Line Spacing: 1.2
+           Body Typeface: Times
+           Heading Typeface: Helvetica
+           Header/Footer Size: 10.0
+           Header/Footer Font: Helvetica
+           Character Set: iso-8859-1
+           Options: Do Not Check 'Embed Fonts'
+
+      g) The PDF tab:
+           PDF Version: 1.3
+           Page Mode: Document
+           Page Layout: Single
+           Page Effect: None
+           Options: Check 'Include Links'
+
+      h) The Security tab:
+           Encryption: No
+
+      i) The Options tab:
+           HTML Editor: Point to Dreamweaver (recommended)
+           Browser Width: 680
+           GUI Option: Check all 3
+
+      j) Save the book file.
+     
+      k) Verify that the output file (H5_RM_body.pdf) is not open.
+
+      l) Generate the document.
+
+5.  Open H5_RM_body.pdf
+    
+      a) Scan through the document page by page to verify that there are no 
+         elements that should have been eliminated via javascripts or swapped 
+         library contents.
+
+      b) Scan through again looking only for places where page breaks need to 
+         be added, removed, or relocated.  I have found that re-generating the 
+         document after every pagination correction actually saves time in the 
+         long run.  This is because some pagination corrections that must be 
+         made may create other problems further down in the document.  
+         Re-generating the document ensures that every problem you focus on 
+         won't have to be re-done.
+
+      c) When you are sure all the pagination is correct (don't forget to 
+         start each of the sections included in the Table of Contents on a 
+         recto) note page numbers for the beginning of each section in the TOC.
+
+6.  Open RM_TOC.html
+
+      a) Edit page numbers accordingly. 
+         (Note: Assuming the general format of RM_H5Front remains the same, 
+          the 'Overview' listing in the TOC should always be on pg. 1, and 
+          the 'Fortran90 and C++ APIs' listing should be on pg. 2, an 
+          exepction to the recto-rule.)
+
+      b) Save.
+
+7.  Using HTMLdoc:
+
+      a) Open PDF_RM_front.book
+
+      b) The Input tab:
+           Document Type: Web Page
+           Input Files:
+             RM_Title.html
+             Copyright.html
+             RM_TOC.html
+           Logo Image: none
+           Title File/Image: none
+
+      c) The Output tab:
+           Output To: File
+           Output Path: H5_RM_front.pdf
+           Output Format: PDF
+           Output Options: JPEG Big Images
+           Compression (not critical, change at will): Slider right above 'Fast'
+           JPEG Quality (not critical, change at will): 60
+  
+      d) The Page tab:
+           Page Size: Letter, 2-Sided
+             Top: 0.50in, Left: 1.00in, Right: 0.50in, Bottom: 0.50in
+           Header: Blank, Blank, Blank
+           Footer: Blank, Blank, Blank
+           Number Up: 1
+
+      e) The Colors tab:
+           Everything Blank
+           Link Style: Plain
+    
+      f) The Fonts tab:
+           Base Font Size: 11.0
+           Line Spacing: 1.2
+           Body Typeface: Times
+           Heading Typeface: Helvetica
+           Header/Footer Size: 10.0
+           Header/Footer Font: Helvetica
+           Character Set: iso-8859-1
+           Options: Do Not Check 'Embed Fonts'
+
+      g) The PDF tab:
+           PDF Version: 1.3
+           Page Mode: Document
+           Page Layout: Single
+           Page Effect: None
+           Options: Check 'Include Links'
+
+      h) The Security tab:
+           Encryption: No
+
+      i) The Options tab:
+           HTML Editor: Point to Dreamweaver (recommended)
+           Browser Width: 680
+           GUI Options: Check all 3
+
+      j) Save the book file.
+     
+      k) Verify that the output file (H5_RM_front.pdf) is not open.
+
+      l) Generate the document.