Notes for developers and translators
====================================

The following "`configure`" options will be of interest to developers and
translators:

 * `--enable-debugging` - build in debugging support
 * `--enable-profiling` - build in support for profiling

These "`make`" targets are available:

 * `make analyse` - run _splint_ and _flawfinder_ on all C source files


Debugging and profiling support
-------------------------------

When "`./configure --enable-debugging`" is used, the "`pv`" produced by
"`make`" will support an extra option, "`--debug FILE`", which will cause
debugging output to be written to *FILE*.  This is not recommended for
production builds due to the extra processing it introduces, and the
potential size of the output.

Within the code, "`debug()`" is used in a similar way to "`printf()`".  It
will automatically include the calling function, source file, and line
number, so they don't need to be included in the parameters.  When debugging
support is not enabled, it evaluates to a null statement.

This does mean that if you call "`debug()`", make sure it has no side
effects, as they won't be present in builds without debugging support.

Builds produced after "`./configure --enable-profiling`" will write profile
data when run, to be used with _gprof_.  See "`man gprof`" for details. 
Please note that the memory safety checks will fail with profiling enabled.


Source code analysis
--------------------

Running "`make analyse`" runs _splint_ and _flawfinder_ on all C sources,
writing the output of both programs to files named "`*.e`" for each "`*.c`".

There are no dependency rules set up for these "`.e`" files, so if a header
file is altered, manually remove the relevant "`.e`" files, or update the
timestamp of the relevant "`.c`" files, before running "`make analyse`"
again.

The eventual goal is for all C source files to generate zero warnings from
either tool.


Translation notes
-----------------

The message catalogues used to translate program messages into other
languages are in the "`po/`" directory, named "`xx.po`", where "`xx`"
is the ISO 639-1 2-letter language code, such as "`fr`" for French.

Each of these files contains lines like this:

    #: src/pv/cursor.c:85
    msgid "failed to get terminal name"
    msgstr "erro ao ler o nome do terminal"

The comment line, starting "`#`", shows the source filename and line number
at which this message can be found.  The "`msgid`" is the original message
in the program, in English.  The "`msgstr`" is the translated text.

It is the "`msgstr`" lines which need to be updated by translators.

Message catalogue files should all be encoded as UTF-8.

_FIXME: The test below doesn't work on Debian with only en_GB installed, and
also it looks like the compiled-in LOCALEDIR is overriding LOCPATH._

After making a change to a "`.po`" file, test it by compiling it and installing
to a temporary location, like this:

    make install DESTDIR=/tmp/yourtest
    localedef -f UTF-8 -i de_DE /tmp/yourtest/usr/local/share/locale/de_DE.UTF-8
    LOCPATH=/tmp/yourtest/usr/local/share/locale \
    LC_ALL=de_DE.UTF-8 ./pv --help

Replace "`--help`" with whatever is appropriate for your test.  In this
example, the language being tested is "`de`" (German), on a system which is
running with UTF-8 support.

To add a new language, create the new message catalogue file under "`po/`"
by copying "`po/pv.pot`" to "`po/xx.po`", where "`xx`" is the language code,
and adjusting it.  The "`.pot`" file is generated automatically by "`make`".

Next, add the language code to "`po/LINGUAS`" - this is a list of the
2-letter codes of the supported languages.

Finally, run "`./config.status`" and "`make -C po update-po`".

When the source code is updated, running "`make -C po update-po`" will
update the "`pv.pot`" file so that it lists where all the messages are in
the source.  It will also use _msgmerge_ to update all of the "`.po`" files
from the updated "`pv.pot`" file.  After doing this, look for missing
translations (empty "`msgstr`" lines) or translations marked as "fuzzy", as
these will need to be corrected by translators.