philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn-r9348]

Browse Source 
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.
This commit is contained in:
Frank Baker
2004-09-30 14:04:06 -05:00
parent dcbf89a021
commit bb24f1844e
1 changed files with 183 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

296
doc/html/PSandPDF/process.txt
View File

@@ -1,148 +1,218 @@
========================================================================
Process for Creating PDF/PS Versions of HDF5 docs from HTML Source Files
========================================================================
==============================================================================
Process for Creating PDF Versions of the HDF5 RM and UG from HTML Source Files
==============================================================================
Last modified: 19 Nov 1999
Last modified: 24 Sep 2004
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.)
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.
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.
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 Start the file off with the DocSet frontmatter.
2. In the ed_libs directory:
3 Open each HTML file and copy it, placing it in proper order, into the
repository file.
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.
3a Insert Glossary. (For R1.2, it was appended to UG and to RM.
Alternatively, it could be inserted as a separate document.)
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.
3b Insert Copyright page after each title page, including after
DocSet title page.
3. In RM_H5P.html:
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.)
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).
5 Create a trial PDF to make sure all of the images have been imported.
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
4a Print the compiled document, selecting "Print to file".
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
4b Change the .prn suffix on the output file to .ps.
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'
4c Convert that PostScript file to PDF with Distiller.
g) The PDF tab:
PDF Version: 1.3
Page Mode: Document
Page Layout: Single
Page Effect: None
Options: Check 'Include Links'
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.)
h) The Security tab:
Encryption: No
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.
i) The Options tab:
HTML Editor: Point to Dreamweaver (recommended)
Browser Width: 680
GUI Option: Check all 3
8 Repeat 4 and 5, with variations on 6, as necessary.
j) Save the book file.
k) Verify that the output file (H5_RM_body.pdf) is not open.
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.
l) Generate the document.
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.
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.
11 Add section break at the title page and the first page of text for
each document.
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.
12 Set page numbering and finalize headers and footers (h/f).
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.
12a Unset "Different first page" on text section h/f.
6. Open RM_TOC.html
12b Set text section page numbering to start at 1.
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.)
12c Set frontmatter page numbering to start at i. (R1.2 did not
set page numbering in frontmatter.)
b) Save.
13 Reset headers and footers for each document (from the initial generic
setting).
7. Using HTMLdoc:
14 Check hyperlinks.
a) Open PDF_RM_front.book
14a Where reasonable (e.g., not appropriate to leave as internal link
for user instalation), set link as external with full DNS address.
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
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.)
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
15 Check and adjust pagination throughout.
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'
15a Each chapter (and, in some cases, major sections) begins on an
odd page.
g) The PDF tab:
PDF Version: 1.3
Page Mode: Document
Page Layout: Single
Page Effect: None
Options: Check 'Include Links'
15b Watch for widows and orphans, examples and sections that start
embarrassingly close to the bottom of the page, etc.
h) The Security tab:
Encryption: No
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.
i) The Options tab:
HTML Editor: Point to Dreamweaver (recommended)
Browser Width: 680
GUI Options: Check all 3
16 Insert a TOC into each document as appropriate. (R1.2 went 3 or 4
levels deep, depending on the document.)
j) Save the book file.
k) Verify that the output file (H5_RM_front.pdf) is not open.
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. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
l) Generate the document.