File	Date	Author	Commit
doc-src	14 hours ago	Bill Kendrick	[84dbc2] Mend bug in What's New re: ASCII Color Computer
po	14 hours ago	Bill Kendrick	[84dbc2] Mend bug in What's New re: ASCII Color Computer
.gitignore	2021-09-29	Bill Kendrick	[1eb07f] Migrating Magic tool docs to tuxpaint-docs
Makefile	2024-06-06	Bill Kendrick	[b91754] Make sure FAQ & README update if saved-files in...
README.txt	2024-05-10	Bill Kendrick	[3649d8] tp_magic_example.c - indent; transliterate loca...
TODO.txt	2023-07-14	Bill Kendrick	[f59c86] Bump dates in some of the main docs
copy-html-to-tuxpaint.sh	2022-10-18	Bill Kendrick	[d0d26c] Migrating "tp_magic_example.c" to tuxpaint-docs

Read Me

Tux Paint Docs
2024-05-10

About:
------
This repository contains documentation for Tux Paint as
a kind of 'source code' which can be more easily translated,
which is then merged into the main 'tuxpaint' repository.

Each piece of documentation is kept as a PHP source file,
which is the HTML for the page, with "gettext()" wrapped
around text that needs translating.

Translators submit PO files, which are converted to MO files
by the Makefile.  The Makefile then produces translated
versions of each documentation, as plain HTML (no PHP) by
invoking PHP against the documentation PHP source file,
with the appropriate locale set.

The main 'tuxpaint' repository will no longer be where
the documentation is maintained directly.  Instead,
a process (invoking the `copy-html-to-tuxpaint.sh` script)
will take place to copy the HTML files generated by the steps
described above, which then get committed to the main repo.

The objective is to avoid having translated documentation
files that are decades out-of-date, and/or maintained in
HTML files which are formatted (or worse yet, render) in ways
different from the core English version, and each other.

Requirements:
-------------
PHP (as a command-line tool, e.g., the `php-cli` package on Ubuntu),
a system for processing Makefiles (e.g., GNU Make), gettext, and
some other basic shell tools are required.

Note: The `gettext` module in PHP only supports languages and language
identifiers that are installed on your system.  Check the available
locales by calling `locale -a` on the command line.

Install missing locales with `locale-gen <language>`,
or on Debian and Ubuntu, using the menu system provided by
`/usr/sbin/dpkg-reconfigure locales`.

php-intl (https://www.php.net/manual/en/intl.setup.php),
which provides the Transliterator class
(https://www.php.net/manual/en/class.transliterator.php)
that's used to convert any localized variable names in the
example Magic tool source (`tp_magic_example.c`) to ASCII A-Z
(e.g., "size" in Icelandic is "stærð", but when used in a
variable name it will be transliterated to "staerd").

Usage:
------
Run "make" to generate the HTML files; they will be placed in the
"doc-out" directory.

Run the included "copy-html-to-tuxpaint.sh" shell script to copy the
resulting files to the directory containing the main "Tux Paint" program,
as checked-out from the "tuxpaint" Git repository of the program's
SourceForge project.  (The "TUXPAINT" variable set within the script
contains the destination, and defaults to "../tuxpaint".)

Then, go to that directory, run "git diff" to confirm that the files
are in a suitable state, and then "git add" the changed (or new) files,
and "git commit" them back to the "tuxpaint" repository, and "git push"
to push them up.  (This assumes you have developer privileges on the
Git repository.  See http://tuxpaint.org/download/source/git/)

Modifying the Documentation:
----------------------------
Make changes to the documentation (the "source", in English) in the
PHP files found in the "doc-src" directory.

Run "make" (as described above) to confirm that the PHP files are
successfully being generated into HTML files.

In the "po" subdirectory, run the "update-po.sh" shell-script to
update the gettext catalog ("tuxpaint-docs.pot").  Ensure no errors
occurred, and observe the 'sanity-check' output displayed at the end.

The sanity-checking output helps you to ensure that:

 * no gettext()-wrapped text is split across multiple lines in the PHP
   source, which would cause the "msgid" strings in the gettext catalog
   to contain "\n"'s.

 * no sprintf()'d formatting strings contain multiple un-enumerated "%s";
   in other words,

   + don't do:
     <?= sprintf(gettext("The \"%s\" will %s."),
             gettext("screen"), gettext("flash")) ?>

   + do this instead:
     <?= sprintf(gettext("The \"%1\$s\" will %2\$s."),
             gettext("screen"), gettext("flash")) ?>

Use "git add <filenames>", "git commit" and "git push" to commit
both your updated PHP file, AND the gettext catalog files
(both the "tuxpaint-docs.pot" and the various "*.po" files),
which almost certainly will have been updated as well.

Then of course see the instructions under "Usage", above, that
explain how to 'deploy' the updated documentation files into the
main "tuxpaint" repository.

Note: If your changes are significant and noteworthy, please mention
them in the main "tuxpaint" repository's "doc/CHANGES.txt" file
(under the forthcoming version's list of changes, found at the top
of the file; place it under a "Documentation updates"; add one if
necessary).

Adding New Documentation Files:
-------------------------------
This will likely be a rare occurrence.  When adding any new documentation
files, be sure to:

 * add the new PHP file to the list found in "po/POTFILES.in"

 * add a process to the "Makefile" to convert the new file from PHP
   to HTML

 * if appropriate, link to the new file within the main README,
   "doc-src/README.php", under the "Further Reading" heading

Follow the "Modifying the Documentation" instructions above, but of
course also include all of the other files described here as part
of committing your changes back to the Git repository.

-bill!