NFORenum README
Last updated:    2010-08-09
Release version: 4.0.0
------------------------------------------------------------------------


Table of Contents:
------------------
1) About
2) Contact
3) Installation
4) Running
5) Known issues
6) Compiling


1) About:
-- ------
NFORenum is a tool checking NFO code for errors, and for beautifying that
code -- inasmuch as NFO can be beautified :)

NFORenum is licensed under the GNU General Public License version 2, or at
your option, any later version. For more information, see 'COPYING.txt'
(GPL version 2), or later versions at <http://www.gnu.org/licenses/>.


2) Contact:
-- --------
Contact can be made via the issue tracker / source repository at
http://dev.openttdcoop.org/projects/nforenum or via IRC on the
#openttdcoop.devzone channel on OFTC.


3) Installation:
-- -------------
Installing NFORenum is fairly straightforward. Just copy the executable into
any directory. It is advised to put the executable in one of the directories
in your path so it can be easily found. For example when compiling OpenGFX.

NFORenum will (if necessary) create a .nforenum directory. All its data files
will be placed in that directory, and updated as needed.
It is not necessary to remove the .nforenum directory before upgrading.

To uninstall, delete the executable and any .nforenum directories.


4) Usage:
-- ------
To renumber NFO files (for example MyGRF1.NFO and MyGRF2.NFO), use

 > nforenum [options] MyGRF1 MyGRF2

(Run nforenum -? or nforenum --help for a list of command line options.)

This will correct sprite numbers, sprite sizes, and sprite 0, and do a
partial lint of the NFO. If a NFO header is not detected, one will be added.
If the file does not start with a digit, an asterisk, whitespace, or one of
the three comment characters (/, ;, #), and -f/--force was not specified,
the file will not be processed.

Sprite numbers are required on real sprites if the filename starts with a
digit, but are optional in all other cases.

Messages will be output to the console and to the NFO file.
For a detailed explanation of the sanity checker's messages,
see SANITY.en.txt.

Sprites that for some reason cannot be processed will be commented out, and
processing will continue.

NFORenum will look for the NFO in the following locations, in this order:
  <filename>
  <filename>.nfo
  sprites/<filename>
  sprites/<filename>.nfo

If no command-line arguments are specified, NFORenum will read from standard
input and write to standard output.

The default search paths for the .nforenum directory are as follows:
  .
  $HOME
  $HOMEDRIVE$HOMEPATH
If the .nforenum directory is not found in any of these locations, NFORenum will
attempt to create one in each location, starting from the bottom of the list
and working up. This can be overridden with the --data option.

The NFORenum will exit with one of the following error codes: (The highest
applicable code will be returned)
8: Fatal program error. (A can't-happen happened.)
7: Data file error. (Failure to create the data dir or open a file.)
6: NFO file error. (Failure to open a file or rename the temp file.)
5: NFO parse error. (Sprite with invalid chars/length, or version too high.)
4: Lint error. (Linter issued an error or fatal error.)
3: Lint warning. (Linter issued a warning.)
0: Successful run, NFO file is clean.

Codes 7 and 8 are supposed to be can't-happens; if they do, NFORenum will
send a message to the console and immediately die.
Codes 1 and 2 are reserved pending discussion; see http://tinyurl.com/acudt.


5) Known issues:
-- -------------
- An Action 6 modifying any checked sprite can cause erroneous sanity messages.
  Status: Low priority, hard to do correctly.
  Workaround: use the @@USEID2 and @@USESET commands to supress incorrect
    messages.
- @@VERSIONCHECK does not put its second action 9 in the correct place.
  Workaround: Manually move that action 9 after the action 8.


6) Compiling:
-- ----------
GCC/ICC:
  Just use "make", or on non-GNU systems "gmake".