Languages Around The World

Editing the ICU User Guide

Overview

The native source for the ICU user guide is Open Office Writer documents.  All writing and editing is done in Open Office, and the HTML and PDF versions are generated from the Open Office documents.

Document Structure

The ICU userguide is organized as an Open Office “Master Document” that includes a series of individual chapter documents.

In addition to including the chapter files, the master document provides common style definitions, the table of contents, the index, etc.

There is a one-to-one correspondence between OO chapter files and  pages in the HTML version of the userguide.  

Here is the directory structure for the user guide files

Directory or FileDescription

userguide/

The top level directory

userguide/OO/

Directory containing all of the user guide source (.sxw) files.

userguide/OO/images/

Sources (.gif, .png, etc) for images used.

userguide/OODTD/

Open Office XML DTD files.  Required by the Open Office to html conversion tool.

userguide/html/

Directory into which the generated html files are built

userguide/html-template/

Directory containing a html template file and css style sheet file.   These are input files to the Open Office to html conversion.

userguide/UGtoHtml/

Directory containing the Java tool for converting the .sxw files to html.

All of the userguide source files are kept  in the public ICU cvs system.   The path to the userguide is icu/icuhtml/userguide.  See http://ibm.com/software/globalization/icu/repository.jsp for information on accessing ICU's cvs system.

All normal editing of userguide content is done on the individual chapter files.  Just open and edit as if they were stand-alone open office files.

Opening userguide.sxg loads the complete, entire user guide.  All chapters are visible, but  no editing of the content of the chapters is possible.  Export to PDF or printing of the complete document are done from this view.

Generating HTML

The HTML for the user guide is generated by a UGtoHtml, a Java tool.

Java JDK 1.4 or newer is required.

To build the UGtoHtml tool,

    cd userguide\UGtoHtml\src

    javac UGtoHtml.java

To convert a single chapter,

    cd userguide

    java -cp UGtoHtml/src UGtoHtml file-name.sxw

To convert the entire user guide,

    java -cp UGtoHtml/src UGtoHtml

In either case, the resulting html file(s) will be placed in the userguide/html directory.

The html files can be tested by simply loading them into a web browser as files.  There are no server dependencies – no SSI or dynamic server interactions that would cause different behavior when the userguide is accessed through a web server.

HTML formatting (pretty printing):  if you want to view the generated html, the format can be improved by enabling XML pretty printing in Open Office.

From the menus  choose  Tools -> Options -> Load/Save -> General

   Uncheck the box   “Size optimization for XML format (no pretty printing).”

Generating the PDF

Open Office makes generating the PDF easy.

Open the complete userguide file, userguide.sxg, in Open Office.

From the File menu choose Export as PDF... and specify a destination file name.

Simple Formatting

Bold, italic, underline, Strike through, superscript and subscript can all be used directly, in any combination, and will convert correctly to html.  Superscript, subscript and strike through are in the character style dialog.

Custom Styles

Use only paragraph styles with names of the form icu-XXX  that appear in the Custom Styles category in Open Office's Stylist window.  (F11 to open the Stylist window)

For character styles, Default and icu-code (for fixed pitch font) are both acceptable, meaning that the OO to HTML conversion will work correctly. Changing the font to a fixed pitch font by hand will not work; you must use the icu-code character style. (If you forget and manually change the font or set some other character styles, select the whole paragraph, change its character style to Default, and then apply the icu-code style where you want it.

Do not define any new custom styles, or use other built-in Open Office styles.  These will not be handled by the html converter.

Images

Images (figures or illustrations) are handled separately for Open Office/PDF and for the html userguide.

For native Open Office and PDF, the image is inserted or pasted directly into the OO document.  These images are ignored by the html conversion.

For the HTML conversion, an annotation in the OO document (a Note) specifies the image file to be inserted.

There are two reasons for this admittedly awkward scheme:

To insert a .gif, .png or .jpg image into a OO Writer file:

Insert Menu -> Graphics -> from file -> browse to your file.

To insert a .sxd Open Office Draw image, copy and paste it from the Draw  program.  This will insert the graphic in vector form, which gives the best printed results.  From the draw program, also export a .gif or .png screen resolution version of the image for use in the html page.

HTML image file name To insert the name of the image file to be used in the html page,

Open Office Notes  not beginning with the text “html image name:” are ignored during the OO to html conversion.

An “html image name:” note is required even when the same image file has been inserted into the Open Office document.

Open Office Template

Explain where the common ICU paragraph styles come from, and how they can be updated.

TO DO.

Adding a Chapter to the User Guide

Here are the steps for adding a new chapter to the ICU user guide.

  1. Save an existing userguide chapter file (.sxw file) as the new chapter file.  Creating the new chapter in this way will include all of the ICU specific styles and template in the Open Office document.

  2. Replace the original content with your new chapter content, and save.

  3. Open the complete userguide (userguide.sxg).  Answer “yes” to the “Update all Links question that will pop up when opening.

  4. Open the Open Office document navigator (F5, or the TODO: symbol in the toolbar.)

  5. In the OO navigator, select the position to insert the new chapter in the list of user guide chapter files.  Select the chapter that should  follow the new chapter, right-click it, and choose  insert -> file  from the pop up menu.  Choose the new chapter file from the file open dialog that will appear.

    To change a chapter's position within the userguide, select and drag it in the navigator window.

  6. Update the table of contents.  Scroll to the top of the complete userguide, right click anywhere in the table of contents area, and choose Update Index /Table.

  7. Save the userguide.sxg document.

  8. Add the new chapter to the html navigation sidebar.

    • In a plain text editor, open the file userguide/html-template/ugtemplate.html

    • The html for the side bar is under <div class="sidebar">, and is fairly obvious – it is the biggest part of the file.  Copy and paste one of the existing chapter entries, and edit it to refer to the new chapter.  Keep the text for the link short, so that it does not exceed the width of the navigation bar in the html page.

    • Regenerate the user guide html, and test the new navigation bar entry.

  9. Put  the new and/or changed files back into cvs.

    • New-chapter.sxw

    • userguide.sxg

    • ugtemplate.html

    • any graphics files

ICU Version Number

To Do.

The ICU version number wants to appear on the title page, on the page header or footer somewhere, and somewhere in the html version.

These need to come from a single common place.

Fonts

Do not override the default fonts for the ICU styles in Open Office unless they do not support the characters needed.

Font choices made in Open Office are not propagated into the html files.  The html display font is controlled by a combination of the CSS style sheet and browser strategy for locating fonts that will display the characters encountered

For program identifiers or code fragments that are embedded within user guide text, choose the character style “icu-code.”  This will result in a fixed width font in the html output.

For Japanese, Chinese and Korean characters, and anything else that doesn't display  in Times New Roman, use the font Gulim if it works.  This choice is subject to change, but we need to be consistent throughout the userguide, both for stylistic reasons and to avoid an explosion of embedded fonts in the PDF file.

Bookmarks & Links

To link to an external html destination, like this ,

To link to a location within the ICU userguide,

Note that bookmarks to other user guide chapters are relative, even though the display shows a full path.  

When converting the userguide to html, all links to Open Office documents are assumed to be to some other part of the user guide, and are translated to normal html links.

To insert a bookmark (an anchor),

Diffing Open Office Documents

Open Office includes a document compare function.  Changes are highlighted in red, with change bars in the margin.  Additions are underlined, deletions are  lined out, and a list summarizes the changes with an option to keep or discard each.

To compare a chapter with a different or conflicting version of the same file,



Copyright (c) 2000 - 2005 IBM and Others - PDF Version - Feedback: http://icu.sourceforge.net/contacts.html

User Guide for ICU v3.4 Generated 2005-07-27.