============================================================================== Process for Creating PDF Versions of the HDF5 Reference Manual (RM) from HTML Source Files ============================================================================== Last modified: 12 November 2010 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, DreamWeaver (an HTML editing environment) and HTMLdoc (a PDF conversion tool). This document describes the process in detail for the RM; the process for the UG is very similar and is described in a separate document. Complete the process first for either the RM or UG, then for the other. The HDF5 Reference Manual ------------------------- 1. Skip this step if you have already done it for the UG; you can use the same working copy for both tasks. Check out a fresh working copy of the minor release branch specifically for this task. For example: svn checkout https://svn.hdfgroup.uiuc.edu/hdf5doc/branches/hdf5_1_8_4 \ hdf5_1_8_4-PDFs Using Macromedia Dreamweaver, define a site that contains all the documents within the subdirectory html/, including the .html, image, DreamWeaver library (in ed_libs/), and .book files. 2. Working in DreamWeaver... In the ed_libs directory: a) Assuming your libraries are set up for electronic viewing (to verify, check that there is nothing more than a commented note and an ' ' in the ed_libs/*_Null.lbi libraries), move the code from the relevant library files into the respective _Null library files, replacing the  . For example, take all the code from Footer.lbi and insert it into Footer_Null.lbi, taking care not to remove the commented note. You can ignore any file in ed_libs/ that does not have a corresponding _Null file. b) In the now empty library file, add an  . c) Save the libraries and their respective Null files. d) With a library still open (not a Null one) choose Modify>Templates>Update Pages... In 'Look in:', select 'Entire Site'. In 'Update:', select 'Library Items' and deselect 'Templates'. Click on the 'Start' button. 3a. In RM_H5P.html: a) RM_H5P.html contains two versions of the 'C Interfaces' function list; one is for print use (in PDFs) and one is for electronic use (on the website). One version should be visible and one should be commented out. Make sure that the sections bracketed with are commented out (by removing the trailing '>' character from the first of each pair of labels). Make sure that the sections bracketed with are visible (by adding a trailing '>' character to the first of each pair of labels). The same convention is used in a scattering of additional files. You can locate them with a 'grep' across the doc tree. 3b. Do the same with RM_H5Front.html 4. Building the section files (H5, H5A, H5D, ... Tools): a) Add any new tools to the concatenate_entries script. b) Using the script RM/concatenate_entries assemble files in each of the following directories into a single file: RM/H5/ RM/H5?/ RM/Tools/ NOTE that RM/H5/* and RM/H5?/* files are assembled alphabetically while RM/Tools/* files are called in a theoretically logical order. c) Insert the concatenated file in place of the server-side include commands in the following files: RM_H5.html RM_H5?.html (i.e., RM_H5A.html, , RM_H5D.html, RM_H5E.html, etc) Tools.html Some files will list additional "_topic/" files that must be included individually. d) Make a pass though the resulting copies of: RM_H5.html RM_H5?.html Tools.html and in: fortran/FortranFlags.html to bring in the Fortran 'php include' files. [ This REALLY needs to be automated!!! Perhaps it could be built ] [ into a Perl script, maybe iven along with the functionality of ] [ 'RM/concatenate_entries'. ] e) Review the resulting files in a browser to ensure that everything has meshed well. 5. 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_H5L.html (new in Release 1.8) RM_H5O.html (new in Release 1.8) RM_H5P.html RM_H5R.html RM_H5S.html RM_H5T.html RM_H5Z.html Tools.html PredefDTypes.html F90Flags.html APICompatMacros.html (new in Release 1.8) [might get moved to "Advanced/"] CollectiveCalls.html (new in Release 1.8.5) Glossary.html Logo Image: none Title File/Image: none c) The Output tab: Output To: File Output Path: HDF5_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' *** These links are relative and will work only in *** *** limited circumstances. Consider turning them *** *** off for future versions. *** 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 (HDF5_RM_body.pdf) is not open. l) Generate the document. 5. Open HDF5_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, swapped comment markup, or swapped DW library content. b) Scan through again looking only for places where page breaks need to be added, removed, or relocated. c) Correct pagination and formatting errors as needed and regenerate. Make all corrections to be saved for future releases in two places: -- In your PDF working copy -- In a clean working copy (i.e., one that has not been modified for this PDF-generation process) REPEAT AS NEEDED. d) When all the pagination is correct (don't forget to start each 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 exception to the recto-rule.) b) Save. 7. Open RM_Title.html a) Update release and date tags. b) Save. 8. Using HTMLdoc: a) Open PDF_RM_FRONT.book b) The Input tab: Document Type: Web Page Input Files: RM_Title.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' *** These links are relative and will work only in *** *** limited circumstances. Consider turning them *** *** off for future versions. *** 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. 9. Following a procedure virtually identical to that outlined in (7) above, use the file PDF_C_and_L.book to generate a 1-page copyright and license statement. This page can be generated once and used in both the RM and UG PDFs. Adjust the font size if the copyright and license statement does not initially fit on one page. To do this, open PDF_C_and_L.book in HTMLdoc; font control is under the "Fonts" tab in the HTMLdoc application window. 10. Using Adobe Acrobat Pro: a) Insert the Copyright page into the frontmatter file and remove any blank pages that prevent the TOC or any subsequent material from appearing on a recto. The resulting page order should be as follows: Title page (recto) Copyright page (on the back of the title page) TOC (starts on a recto; may be several pages) additional material (starts on a recto; may be several pages) The resulting file is your final frontmatter file. b) Insert the frontmatter file at the front of the previously-generated body file. Acrobat can be finicky. -- Save the file and quit Acrobat after each "Insert pages" or "Delete pages" operation. -- If you get an error, try doing things in a different order; e.g., if you get an error inserting the body at the end of the frontmatter, try inserting the frontmatter to the beginning of the body. NOTE OF 10 November 2011 The following order of operations worked today: -- Quit and restart Adobe Acrobat Pro for each of the following steps. -- Remove the blank title page verso. -- Remove the blank copyright and license page (C&L) recto. -- With the frontmatter file open, insert the C&L following the title page. -- With the frontmatter file open, insert the RM body following the last frontmatter page. c) Update the PDF bookmarks. You will be correcting two problems: First, the default text for the automatically-generated bookmarks is generally inadequate; replace them with more descriptive text. Second, the process of trinmming and merging files scrambles the bookmarks pretty badly. d) Name the resulting file consistently with the names of UG and RM PDFs from prior releases. For history, one copy of the RM PDF file will be in the format: HDF5_RM_r188.pdf To enable links that always point to an up-to-date version, a second copy of the RM PDF file will be in the format: HDF5_RefManual.PDF 11. Update this 'process.txt' file. 12. Commit the updated 'process.txt' and all of the edits mentioned in step 5 (see 5c). Final UG and RM PDFs Pagination and other changes in the content files Updates to the HTMLdoc .book files. Any other changes for this process that should be saved for future use Make sure all commits are merged, as appropriate, to other branches and to the repository trunk.