diff options
| -rw-r--r-- | doc/html/PSandPDF/process.txt | 362 |
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. |