organicmaps/icu
13
Fork 0
mirror of https://github.com/unicode-org/icu.git synced 2025-04-04 13:05:31 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions 7

ICU-21310 replacement User Guide main index page

Browse source 
...and nav_order and link fixes from Elango. See #1680
This commit is contained in:
Elango Cheran 2021-04-01 23:23:14 +00:00 • committed by Markus Scherer
parent f5d8b57d01
commit 75c58211c0
21 changed files with 67 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/favicon.ico Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.6 KiB

2
docs/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: ICU Documentation
nav_order: 1
nav_order: 100
description: ICU Documentation
---

2
docs/userguide/boundaryanalysis/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Boundary Analysis
nav_order: 12
nav_order: 1300
has_children: true
---
<!--

2
docs/userguide/collation/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Collation
nav_order: 11
nav_order: 1200
has_children: true
---
<!--

2
docs/userguide/conversion/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Conversion
nav_order: 6
nav_order: 700
has_children: true
---
<!--

2
docs/userguide/datetime/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Date/Time
nav_order: 8
nav_order: 900
has_children: true
---
<!--

2
docs/userguide/dev/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Contributors
nav_order: 17
nav_order: 1800
has_children: true
---
<!--

2
docs/userguide/format_parse/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Formatting
nav_order: 9
nav_order: 1000
has_children: true
---
<!--

2
docs/userguide/icu/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: ICU
nav_order: 2
nav_order: 300
has_children: true
---
<!--

4
docs/userguide/icu4c/build.md
View file

@ -96,7 +96,7 @@ Depending on the platform and the type of installation, we recommend a small num
> :point_right: **Note**: The ICU test suites _can_ be compiled with this setting.
* **.dat file:** By default, the ICU data is built into a shared library (DLL). This is convenient because it requires no install-time or runtime configuration, but the library is platform-specific and cannot be modified. A .dat package file makes the opposite trade-off: Platform-portable (except for endianness and charset family, which can be changed with the icupkg tool) and modifiable (also with the icupkg tool). If a path is set, then single data files (e.g., .res files) can be copied to that location to provide new locale data or conversion tables etc.
The only drawback with a .dat package file is that the application needs to provide ICU with the file system path to the package file (e.g., by calling `u_setDataDirectory()`) or with a pointer to the data (`udata_setCommonData()`) before other ICU API calls. This is usually easy if ICU is used from an application where `main()` takes care of such initialization. It may be hard if ICU is shipped with another shared library (such as the Xerces-C++ XML parser) which does not control `main()`.
See the [User Guide ICU Data](https://unicode-org.github.io/icu/userguide/icudata) chapter for more details.
See the [User Guide ICU Data](../icu_data) chapter for more details.
If possible, we recommend building the .dat package. Specify `--with-data-packaging=archive` on the configure command line, as in
`runConfigureICU Linux --with-data-packaging=archive`
(Read the configure script's output for further instructions. On Windows, the Visual Studio build generates both the .dat package and the data DLL.)
@ -116,7 +116,7 @@ Depending on the platform and the type of installation, we recommend a small num
### ICU as a System-Level Library
If ICU is installed as a system-level library, there are further opportunities and restrictions to consider. For details, see the _Using ICU as an Operating System Level Library_ section of the [User Guide ICU Architectural Design](https://unicode-org.github.io/icu/userguide/design) chapter.
If ICU is installed as a system-level library, there are further opportunities and restrictions to consider. For details, see the _Using ICU as an Operating System Level Library_ section of the [User Guide ICU Architectural Design](../icu/design) chapter.
* **Data path:** For a system-level library, it is best to load ICU data from the .dat package file because the file system path to the .dat package file can be hardcoded. ICU will automatically set the path to the final install location using `U_ICU_DATA_DEFAULT_DIR`. Alternatively, you can set `-DICU_DATA_DIR=/path/to/icu/data` when building the ICU code. (Used by source/common/putil.c.)
Consider also setting `-DICU_NO_USER_DATA_OVERRIDE` if you do not want the `ICU_DATA` environment variable to be used. (An application can still override the data path via `u_setDataDirectory()` or `udata_setCommonData()`.

10
docs/userguide/icu4c/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: ICU4C
nav_order: 3
nav_order: 400
has_children: true
---
<!--
@ -50,7 +50,7 @@ The ICU homepage also links to related information about writing internationaliz
| ICU FAQ - Frequently Asked Questions about ICU | <https://unicode-org.github.io/icu/userguide/icu4c/faq> |
| ICU4J FAQ - Frequently Asked Questions about ICU4J | <https://unicode-org.github.io/icu/userguide/icu4j/faq> |
| ICU User's Guide | <https://unicode-org.github.io/icu/> |
| How To Use ICU | <https://unicode-org.github.io/icu/userguide/howtouseicu> |
| How To Use ICU | <https://unicode-org.github.io/icu/userguide/icu/howtouseicu> |
| Download ICU Releases | <http://site.icu-project.org/download> |
| ICU4C API Documentation Online | <http://icu-project.org/apiref/icu4c/> |
| Online ICU Demos | <http://demo.icu-project.org/icu-bin/icudemos> |
@ -82,7 +82,7 @@ There are two ways to download ICU releases:
## ICU Source Code Organization
In the descriptions below, `<ICU>` is the full path name of the ICU4C directory (the top level directory from the distribution archives) in your file system. You can also view the [ICU Architectural Design](design.md) section of the User's Guide to see which libraries you need for your software product. You need at least the data (`[lib]icudt`) and the common (`[lib]icuuc`) libraries in order to use ICU.
In the descriptions below, `<ICU>` is the full path name of the ICU4C directory (the top level directory from the distribution archives) in your file system. You can also view the [ICU Architectural Design](../icu/design.md) section of the User's Guide to see which libraries you need for your software product. You need at least the data (`[lib]icudt`) and the common (`[lib]icuuc`) libraries in order to use ICU.
**The following files describe the code drop.**
@ -215,7 +215,7 @@ In the descriptions below, `<ICU>` is the full path name of the ICU4C directory
environment variable to the out/ or the out/build/ directories, but
this is generally discouraged because most people set it incorrectly.
You can view the <a href=
"https://unicode-org.github.io/icu/userguide/icudata">ICU Data
"https://unicode-org.github.io/icu/userguide/icu_data">ICU Data
Management</a> section of the ICU User's Guide for details.</p>
</td>
</tr>
@ -405,7 +405,7 @@ If you are using ICU's Makefiles to build ICU on a new platform, there are a few
For some people, it may not be necessary for completely build ICU. Most of the makefiles and build targets are for tools that are used for building ICU's data, and an application's data (when an application uses ICU resource bundles for its data).
Data files can be built on a different platform when both platforms share the same endianness and the same charset family. This assertion does not include platform dependent DLLs/shared/static libraries. For details see the User Guide [ICU Data](https://unicode-org.github.io/icu/userguide/icudata) chapter.
Data files can be built on a different platform when both platforms share the same endianness and the same charset family. This assertion does not include platform dependent DLLs/shared/static libraries. For details see the User Guide [ICU Data](../icu_data) chapter.
ICU 3.6 removes the requirement that ICU be completely built in the native operating environment. It adds the icupkg tool which can be run on any platform to turn binary ICU data files from any one of the three formats into any one of the other data formats. This allows a application to use ICU data built anywhere to be used for any other target platform.

4
docs/userguide/icu4c/packaging.md
View file

@ -39,7 +39,7 @@ Following these guidelines prevents other applications that use a standard ICU
distribution from conflicting with any libraries that you need. On operating systems
that do not have a standard C++ ABI (name mangling) for compilers, it is recommended to
do this special packaging anyway. More details on customizing ICU are available in the
[User's Guide](https://unicode-org.github.io/icu/userguide/).
[User Guide](../).
The [ICU Source Code Organization](./index/#icu-source-code-organization) section of
the ICU4C gives a more complete description of the libraries.
@ -47,7 +47,7 @@ ICU has several libraries for you to use. Here is an example of libraries that a
| Library Name | Windows Filename | Linux Filename | Comment |
|-------------------------------------|------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Data Library | icudtXYl.dll | libicudata.so.XY.Z | Data required by the Common and I18n libraries. There are many ways to package and [customize this data](https://unicode-org.github.io/icu/userguide/icudata), but by default this is all you need. |
| Data Library | icudtXYl.dll | libicudata.so.XY.Z | Data required by the Common and I18n libraries. There are many ways to package and [customize this data](../icu_data), but by default this is all you need. |
| Common Library | icuucXY.dll | libicuuc.so.XY.Z | Base library required by all other ICU libraries. |
| Internationalization (i18n) Library | icuinXY.dll | libicui18n.so.XY.Z | A library that contains many locale based internationalization (i18n) functions. |
| Layout Extensions Engine | iculxXY.dll | libiculx.so.XY.Z | An optional engine for doing paragraph layout that uses parts of ICU. HarfBuzz is required. |

28
docs/userguide/icu4j/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: ICU4J
nav_order: 4
nav_order: 500
has_children: true
---
<!--
@ -28,27 +28,27 @@ Java provides a strong foundation for global programs, and IBM and the ICU team
ICU4J is an add-on to the regular JRE that provides:
* [Collation](https://unicode-org.github.io/icu/userguide/collation) – rule-based, up-to-date Unicode Collation Algorithm (UCA) sorting order
* [Collation](../collation) – rule-based, up-to-date Unicode Collation Algorithm (UCA) sorting order
    For fast multilingual string comparison; faster and more complete than the J2SE implementation
* [Charset Detection](https://unicode-org.github.io/icu/userguide/conversion/detection) – Recognition of various single and multibyte charsets
* [Charset Detection](../conversion/detection) – Recognition of various single and multibyte charsets
    Useful for recognizing untagged text data
* [UnicodeSet](https://unicode-org.github.io/icu/userguide/strings/unicodeset) – standard set operations optimized for sets of Unicode characters
* [UnicodeSet](../strings/unicodeset) – standard set operations optimized for sets of Unicode characters
    UnicodeSets can be built from string patterns using any Unicode properties.
* [Transforms](https://unicode-org.github.io/icu/userguide/transforms) – a flexible mechanism for Unicode text conversions
* [Transforms](../transforms) – a flexible mechanism for Unicode text conversions
    Including Full/Halfwidth conversions, Normalization, Case conversions, Hex conversions, and transliterations between scripts (50+ pairs)
* [Unicode Normalization](https://unicode-org.github.io/icu/userguide/transforms/normalization) – NFC, NFD, NFKD, NFKC
* [Unicode Normalization](../transforms/normalization) – NFC, NFD, NFKD, NFKC
    For canonical text representations, needed for XML and the net
* [International Calendars](https://unicode-org.github.io/icu/userguide/datetime/calendar) – Arabic, Buddhist, Chinese, Hebrew, Japanese, Ethiopic, Islamic, Coptic and other calendars
* [International Calendars](../datetime/calendar) – Arabic, Buddhist, Chinese, Hebrew, Japanese, Ethiopic, Islamic, Coptic and other calendars
    Required for correct presentation of dates in certain countries
* [Date Format Enhancements](https://unicode-org.github.io/icu/userguide/format_parse/datetime) – Date/time pattern generator, Relative date formatting, etc.
* [Date Format Enhancements](../format_parse/datetime) – Date/time pattern generator, Relative date formatting, etc.
    Enhancements to the normal Java date formatting.
* [Number Format Enhancements](https://unicode-org.github.io/icu/userguide/format_parse/numbers) – Scientific Notation, Spelled-out, Compact decimal format, etc.
* [Number Format Enhancements](../format_parse/numbers) – Scientific Notation, Spelled-out, Compact decimal format, etc.
    Enhancements to the normal Java number formatting. The spell-out format is used for checks and similar documents
* [Enhanced Word-Break Detection](https://unicode-org.github.io/icu/userguide/boundaryanalysis) – Rule-based, supports Thai, Khmer, Chinese, etc.
* [Enhanced Word-Break Detection](../boundaryanalysis) – Rule-based, supports Thai, Khmer, Chinese, etc.
    Required for correct support of Thai
* [Unicode Text Compression](https://unicode-org.github.io/icu/userguide/conversion/compression) – Standard compression of Unicode text
* [Unicode Text Compression](../conversion/compression) – Standard compression of Unicode text
    Suitable for large numbers of small fields, where LZW and similar schemes do not apply
* [Charset Conversion](https://unicode-org.github.io/icu/userguide/conversion) – Conversion to and from different charsets.
* [Charset Conversion](../conversion) – Conversion to and from different charsets.
    Plugs into Java CharsetProvider Service Provider Interface (SPI)
> :point_right: **Note:** We continue to provide assistance to Java, and in some cases, ICU4J support has been rolled into a later release of Java. For example, BCP47 language tag support including Unicode locale extensions is now in Java 7\. However, the most current and complete version is always found in ICU4J.
@ -163,7 +163,7 @@ Below, all directory paths are relative to the directory where the ICU4J source
## Where to get Documentation
The [ICU user's guide](https://unicode-org.github.io/icu/userguide/) contains lots of general information about ICU, in its C, C++, and Java incarnations.
The [ICU User Guide](../) contains lots of general information about ICU, in its C, C++, and Java incarnations.
The complete API documentation for ICU4J (javadoc) is available on the ICU4J web site, and can be built from the sources:
@ -417,7 +417,7 @@ ICU4J data is built by ICU4C tools. Please see [ICU Data Build Tool](../icu_data
## About ICU4J Time Zone
ICU4J library includes the latest time zone data, as of the release date. However, time zone data is frequently updated in response to changes made by local governments around the world. If you need to update the time zone data, please refer the ICU user guide topic [Updating the Time Zone Data](https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data).
ICU4J library includes the latest time zone data, as of the release date. However, time zone data is frequently updated in response to changes made by local governments around the world. If you need to update the time zone data, please refer the ICU user guide topic [Updating the Time Zone Data](../datetime/timezone#updating-the-time-zone-data).
You can optionally configure ICU4J date and time service classes to use underlying JDK TimeZone implementation (see the ICU4J API reference [TimeZone](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/util/TimeZone.html) for the details). When this configuration is enabled, ICU's own time zone data won't be used and you have to get time zone data patches from the JRE vendor.

16
docs/userguide/icu_data/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: ICU Data
nav_order: 15
nav_order: 1600
has_children: true
---
<!--
@ -132,16 +132,16 @@ happens only once per process, at the time an ICU data item is first requested.
3. Dynamically load (memory map, typically) a common format (.dat) file
containing the default ICU data. Loading is described in the section
[How Data Loading Works](icudata#how-data-loading-works). The path to
[How Data Loading Works](#how-data-loading-works). The path to
the data is of the form "icudt\<version\>\<flag\>", where \<version\> is
the two-digit ICU version number, and \<flag\> is a letter indicating the
internal format of the file (see the
[Sharing ICU Data Between Platforms](icudata#sharing-icu-data-between-platforms)
[Sharing ICU Data Between Platforms](#sharing-icu-data-between-platforms)
section).
Once the default ICU data has been located, loading of individual data items
proceeds as described in the section
[How Data Loading Works](icudata#how-data-loading-works).
[How Data Loading Works](#how-data-loading-works).
## Building and Linking against ICU data
@ -252,7 +252,7 @@ and set with `udata_setCommonData()` or `udata_setAppData()`, or they must be
in a known location that is included in the ICU data directory string. This
requires the application installer, or the application itself at runtime, to
locate the ICU and/or application data by setting the ICU data directory (see
the [ICU Data Directory](icudata#icu-data-directory) section above) or by
the [ICU Data Directory](#icu-data-directory) section above) or by
loading the data and providing it to one of the `udata_setXYZData()` functions.
Unlike shared libraries, .dat package files can be taken apart into separate
@ -261,7 +261,7 @@ modification of a package file. The `gencmn` and `pkgdata` ICU tools can then be
used to reassemble the .dat package file.
For more information about .dat package files see the section [Sharing ICU Data
Between Platforms](icudata#sharing-icu-data-between-platforms) below.
Between Platforms](#sharing-icu-data-between-platforms) below.
### Data Overriding vs. Loading Performance
@ -275,7 +275,7 @@ all directories and matching .dat files mentioned before checking in
already-loaded package files. This allows overriding of packaged data items with
single files after installation but costs some time for filesystem accesses.
This is usually done only once per data item; see
[User Data Caching](icudata#user-data-caching) below.
[User Data Caching](#user-data-caching) below.
### Single Data Files vs. Packages
@ -311,7 +311,7 @@ are not handled here.)
> :point_right: **Note**: The ICU data directory string itself may
contain multiple directories and path/filenames to .dat package files. See the
[ICU Data Directory](icudata#icu-data-directory) section.
[ICU Data Directory](#icu-data-directory) section.
It is recommended to not include the directory in the path argument but to make
sure via setting the application data or the ICU data directory string that the

22
docs/userguide/index.md Normal file
View file

@ -0,0 +1,22 @@
---
layout: default
title: ICU User Guide
nav_order: 200
description: ICU User Guide
---
<!--
© 2020 and later: Unicode, Inc. and others.
License & terms of use: http://www.unicode.org/copyright.html
-->
# ICU User Guide
[![ICU logo](https://github.com/unicode-org/icu-docs/raw/main/img/iculogo_64.png)](http://site.icu-project.org/)
This User Guide provides information on i18n topics for which ICU has services, and
includes details that go beyond the C, C++, and Java API docs (and avoids some duplication between them).
You may want to start with the [Introduction to ICU](./icu) or browse the navigation bar for a specific topic.
This is the new home of the User Guide (since 2020 August).

2
docs/userguide/io/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: IO
nav_order: 13
nav_order: 1400
has_children: true
---
<!--

2
docs/userguide/layoutengine/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Layout Engine
nav_order: 14
nav_order: 1500
has_children: true
---
<!--

2
docs/userguide/locale/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Locales and Resources
nav_order: 7
nav_order: 800
has_children: true
---
<!--

2
docs/userguide/strings/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Chars and Strings
nav_order: 5
nav_order: 600
has_children: true
---
<!--

2
docs/userguide/transforms/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Transforms
nav_order: 10
nav_order: 1100
has_children: true
---
<!--

2
docs/userguide/usefrom/index.md
View file

@ -1,7 +1,7 @@
---
layout: default
title: Use From...
nav_order: 16
nav_order: 1700
has_children: true
---
<!--