summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>2004-09-30 19:04:06 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>2004-09-30 19:04:06 (GMT)
commitbb24f1844ef0803e152088faa650bd75ec4240d5 (patch)
tree84836685bdb1b67783caa3fbaa9c81785da93129
parentdcbf89a021fafe48b17ec1c8879241d243a74b48 (diff)
downloadhdf5-bb24f1844ef0803e152088faa650bd75ec4240d5.zip
hdf5-bb24f1844ef0803e152088faa650bd75ec4240d5.tar.gz
hdf5-bb24f1844ef0803e152088faa650bd75ec4240d5.tar.bz2
[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.
-rw-r--r--doc/html/PSandPDF/process.txt362
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 '&nbsp;' in the 3 aforementioned _Null libraries) drop the code
+ from the actual library into it's respective Null lib, replacing
+ the &nbsp;.
+ (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 &nbsp;.
+
+ 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.