Doc fixes.

parent d683facf
......@@ -2,43 +2,11 @@
Copyright (C) 2011-2017 Simon Josefsson
See the end for copying conditions.
This file contains instructions for developers and advanced users that
wants to build from version controlled sources. You need to have
several tools installed, including:
* [Make](https://www.gnu.org/software/make/)
* [Automake](https://www.gnu.org/software/automake/)
* [Autoconf](https://www.gnu.org/software/autoconf/)
* [Libtool](https://www.gnu.org/software/libtool/)
* [Gettext](https://www.gnu.org/software/gettext/)
* [Texinfo](https://www.gnu.org/software/texinfo/)
* [Gperf](https://www.gnu.org/software/gperf/)
* [help2man](https://www.gnu.org/software/help2man/)
* [Gengetopt](https://www.gnu.org/software/gengetopt/)
* [Tar](https://www.gnu.org/software/tar/)
* [Gzip](https://www.gnu.org/software/gzip/)
* [Texlive & epsf](https://www.tug.org/texlive/) (for PDF manual)
* [GTK-DOC](https://www.gtk.org/gtk-doc/) (for API manual)
* [Git](https://git-scm.com/)
* [Perl](https://www.cpan.org/) (HTTPS: www.cpan.org uses an invalid security certificate)
* [Valgrind](http://valgrind.org/) (optional) (No HTTPS at all)
* [libunistring](https://www.gnu.org/software/libunistring/)
* [abi-compliance-checker]
* [ronn](https://rtomayko.github.io/ronn/)
This file contains instructions for developers and advanced users.
See README for the additional tools you need to have installed.
## Obtaining sources
The required software is typically distributed with your operating
system, and the instructions for installing them differ. Here are
some hints.
gNewSense/Debian/Ubuntu:
```
apt-get install git autoconf automake libtool texinfo gperf git2cl
apt-get install libunistring-dev gtk-doc-tools valgrind gengetopt
apt-get install abi-compliance-checker ruby-ronn
```
Download the version controlled sources:
```
$ git clone https://gitlab.com/libidn/libidn2.git
......@@ -77,7 +45,7 @@ changes to pass the automated test suite.
The release process consists of:
* Make sure version number is updated in configure.ac and idn2.h.in.
* Make sure version number is updated in configure.ac.
* Make sure library version is updated in configure.ac.
* Prepare NEWS.
* Do 'make release'
......
......@@ -18,22 +18,31 @@ The library contains functionality to convert internationalized domain names
to and from ASCII Compatible Encoding (ACE), following the IDNA2008 and TR46
standards.
The API consists of two main functions, ```idn2_to_ascii_8z``` for converting data
from UTF-8 to ASCII Compatible Encoding (ACE), and ```idna_to_unicode_8z8z``` to convert
ACE names into UTF-8 format. There are several variations of these main
functions, which accept UTF-32, or input in the local system encoding. All
functions assume zero-terminated strings.
This library is backwards (API) compatible with the [libidn library](https://www.gnu.org/software/libidn/).
Replacing the ```idna.h``` header with ```idn2.h``` into a program is
sufficient to switch the application from IDNA2003 to IDNA2008 as supported
by this library.
The API consists of two main functions, ```idn2_to_ascii_8z``` for
converting data from UTF-8 to ASCII Compatible Encoding (ACE), and
```idna_to_unicode_8z8z``` to convert ACE names into UTF-8
format. There are several variations of these main functions, which
accept UTF-32, or input in the local system encoding. All functions
assume zero-terminated strings.
This library is backwards (API) compatible with the [libidn
library](https://www.gnu.org/software/libidn/). Replacing the
```idna.h``` header with ```idn2.h``` into a program is sufficient to
switch the application from IDNA2003 to IDNA2008 as supported by this
library.
Libidn2 is believed to be a complete IDNA2008 and TR46 implementation,
it contains an extensive test-suite, and is included in the continuous
fuzzing project [OSS-Fuzz](https://bugs.chromium.org/p/oss-fuzz/issues/list?q=libidn2).
# License
The installed C library libidn2 is dual-licensed under LGPLv3+|GPLv2+,
while the rest of the package is GPLv3+. See the file
[COPYING](COPYING) for detailed information.
# Online docs
[API reference](https://libidn.gitlab.io/libidn2/reference/api-index-full.html)
......@@ -54,15 +63,60 @@ and there is [an issue tracker for reporting bugs](https://gitlab.com/libidn/lib
# Dependencies
Libidn2 uses GNU libunistring for Unicode processing and GNU libiconv
for character set conversion. See the following links for more
information on these packages:
To build Libidn2 you will need a POSIX shell to run ./configure and
the Unix make tool.
* [Bash](https://www.gnu.org/software/bash/)
* [Make](https://www.gnu.org/software/make/)
The shared libidn2 library uses GNU libunistring for Unicode
processing and GNU libiconv for character set conversion. You should
install them before building and installing libidn2. See the
following links for more information on these packages:
* [Unistring](https://www.gnu.org/software/libunistring/)
* [iconv](https://www.gnu.org/software/libiconv/)
Note that the iconv dependency is optional, and required only for the
functions involving locale to UTF conversions.
Note that the iconv dependency is optional -- it is required for the
functions involving locale to UTF conversions -- but is recommended.
If you wish to build the project from version controlled sources,
rebuild all generated files (e.g., run autoreconf), or modify some
source code files, you will need to have additional tools installed.
None of the following tools are necessary if you build Libidn2 in the
usual way (i.e., ./configure && make).
* [Automake](https://www.gnu.org/software/automake/)
* [Autoconf](https://www.gnu.org/software/autoconf/)
* [Libtool](https://www.gnu.org/software/libtool/)
* [Gettext](https://www.gnu.org/software/gettext/)
* [Texinfo](https://www.gnu.org/software/texinfo/)
* [Gperf](https://www.gnu.org/software/gperf/)
* [Gengetopt](https://www.gnu.org/software/gengetopt/)
* [Tar](https://www.gnu.org/software/tar/)
* [Gzip](https://www.gnu.org/software/gzip/)
* [Texlive & epsf](https://www.tug.org/texlive/) (for PDF manual)
* [GTK-DOC](https://www.gtk.org/gtk-doc/) (for API manual)
* [Git](https://git-scm.com/)
* [Perl](https://www.cpan.org/) (HTTPS: www.cpan.org uses an invalid security certificate)
* [Valgrind](http://valgrind.org/) (optional) (No HTTPS at all)
* [abi-compliance-checker]
* [ronn](https://rtomayko.github.io/ronn/)
The software is typically distributed with your operating system, and
the instructions for installing them differ. Here are some hints.
gNewSense/Debian/Ubuntu:
```
apt-get install git autoconf automake libtool texinfo gperf git2cl
apt-get install libunistring-dev gtk-doc-tools valgrind gengetopt
apt-get install abi-compliance-checker ruby-ronn
```
# Contributing
See [the contributing document](CONTRIBUTING.md).
# Estimating code coverage
......@@ -81,26 +135,14 @@ The current coverage report can be found [here](https://libidn.gitlab.io/libidn2
# Cross-compiling
It is possible to cross-compile libidn2. It is expected your cross compiler
toolchain to have a specific prefix to the target host. For example
compiling for Windows with mingw64 (with prefix ```i686-w64-mingw32```)
can be done the following way:
It is possible to cross-compile libidn2. It is expected your cross
compiler toolchain to have a specific prefix to the target host. For
example compiling for Windows with mingw64 (with prefix
```i686-w64-mingw32```) can be done the following way:
```
./configure --host=i686-w64-mingw32 && make
```
After `./bootstrap`ing you find the `INSTALL` file in the main
project directory including generic instructions about cross-compilation.
# Contributing
See [the contributing document](CONTRIBUTING.md).
# License
The installed C library libidn2 is dual-licensed under LGPLv3+|GPLv2+,
while the rest of the package is GPLv3+. See the file [COPYING](COPYING)
for detailed information.
After `./bootstrap`ing you find the `INSTALL` file in the main project
directory including generic instructions about cross-compilation.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment