# Developing programs utilizing libenca
* Look at libenca API documentation in devel-docs/html.
* Look into enca source how it uses libenca. Note enca is quite a simple
application (practically all libenca interaction is in `src/enca.c`). It's
single-threaded and uses one language and one analyser all the time.
Provided each thread has its own analyser, libenca should be thread-safe
(untested).
* Take names starting with `ENCA`, `Enca`, `enca`, `_ENCA`, `_Enca`, and
`_enca` as reserved.
* pkgconfig is supported, you can use `PKG_CHECK_MODULES` to check for libenca
in your configure scripts
# How to add a new charset/encoding
(optional steps are marked _[optional]_):
* `iconvcap.c`:
* Add a new test (even if you are 100% sure iconv will never support it),
please see top of `iconvcap.c` for some documentation how it works.
* `tools/encodings.dat`:
* Add a new entry.
* Use `@ICONV_NAME_<name>@` (as it will appear in iconvcap output) for
iconv names.
* `tools/iconvenc.null`:
* Add it (with NULL)
Specifically, for regular 8bit (language dependent) charsets:
* `lib/unicodemap.c`:
* Add a new map to Unicode (UCS-2) `unicode_map_...[]`.
* Add a new `UNICODE_MAP[]` entry.
* `lib/filters.c`: _[optional]_
* Create a new filter or make an alias of an existing filter.
* `lib/lang_??.c`:
* Add the new encoding to some existing language(s).
* Add appropriate filters or hooks _[optional]_.
* `data/maps/??.map`:
* Add a new map to Unicode (UCS-2)
Specifically, for multibyte encodings:
* `lib/multibyte.c`:
* Create a new check function.
* Put it into appropriate ascii/8bit/binary test group
`ENCA_MULTIBYTE_TESTS_ASCII[]`, `ENCA_MULTIBYTE_TESTS_8BIT[]`,
`ENCA_MULTIBYTE_TESTS_BINARY[]`.
* Put strict tests (i.e. test which may fail) first, looks-like tests
last.
# How to add a new surface
* Try to ask the author what to do, since this may be complicated, or
* Hack, basically it must be added to `lib/enca.h` `EncaSurface enum`, to
`lib/encnames.c` `SURFACE_INFO[]` a detection method must be added to
`lib/guess.c` and now the most complicated part: this new method must be used
in the right places in `lib/guess.c` `make_guess()`.
# How to add a new language
* Create a new language file:
* Create new `lib/lang_....c` files by copying some existing (use locale
code for names)
* Fill all encoding and occurence data, create filters and hooks (see
`filters.c` too). You can do it manually, but look how it's done for
existing languages in `data/*` and read `data/README`.
* `lib/internal.h`:
* Add new `ENCA_LANGUAGE_....`
* `src/lang.c`:
* Add a new `LANGUAGE_LIST[]` entry pointing to the `ENCA_LANGUAGE_....`
# Automake, autoconf, libtool, ... note
If you run `./autogen.sh` and it finishes OK, you are lucky and can expect
things to work.
You have to give `--enable-maintainer-mode` to `./configure` (or `./autogen`)
to build dists and/or the strange stuff in `tools/`, `data/`, `tests/`, and
`devel-docs/`.
# Repository and continuous integration
The git repository is located at GitHub:
http://github.com/nijel/enca
There is also continuous integration on Travis:
https://travis-ci.org/nijel/enca