docs/userguide/editing.md

# 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

*Endianness 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.