Editing the ICU User Guide

Overview

This version of the ICU User Guide is maintained via Google Sites. The Site address is http://sites.google.com/site/icuprojectuserguide/

Editors are also usually ICU committers. Edit rights are granted by other Site owners and collaborators.

The change from editing of Open Office Writer documents and generating HTML and PDF to editing a Google Site simplifies the User Guide maintenance and encourages us to keep it more up to date than before, at the cost of not being able to easily generate a single PDF document with the entire contents.

Document Structure

Major chapters have Introduction pages, and further sections in a chapter are subpages of that main chapter page. The navigation bar is a manually edited sidebar accessible (if you are logged in and have edit rights) from Site settings/Change appearance.

Page URLs should use lowercase letters and no hyphens.

See the sitemap linked from the bottom of the navigation bar.

Most pages have an automatic Table of contents. On a new page, after entering some contents, return to the very top of the page contents, select Insert/Table of contents, save, then change it to Right-aligned and turn on Wrap.

Common Styles

We want to use common styles for code samples, notes and such. Since Google Sites does not offer a site-wide CSS style sheet, please copy special items from here, paste and modify their text, rather than creating them from scratch.

For headings, and for standard text styles like bold, italic, strike-through, ... please use standard headings styles from Sites.

Code

New: Use the Format menu styles for Code (inline) and Blockquote Code (multi-line).

Obsolete:

For inline class/type/function/constant names and similar use Sites' Courier New font which is close enough to the Courier font we used to use.

For a block of code, please copy/paste the following and edit its contents:

U16_NEXT(s, i, length, c)
U16_PREV(s, start, i, c)
U16_APPEND(s, i, length, c, isError)

Notes

NoteEndianness is not an issue on this level because the interpretation of an integer is fixed within any given platform.


Bookmarks & Links

For internal links, please select the Sites page as a destination rather than specifying the full URL as a generic web link.

Unfortunately, Sites makes it hard to define an anchor on a page and create a link to that specific anchor (whether from the same page or another one).
  • For links to a specific section on the same page, please remove the link, underline the former link text, and put "(§)" right after it.
  • For links to a specific section on another page, just link to the page and name the section. Please also put "(§)" right after it.
If and when Sites offers a reasonable way of defining anchors and linking to them, we can search our pages for "(§)" and fix the links.
Comments