===============================================================
 .FONT  -  esxDOS dot-command for ZX Spectrum and compatibles
===============================================================

Installer of fonts and user-defined graphics. Updates the
BASIC system variables CHARS and UDG so the new set is
active immediately.

Build: v0.5  (SCjoe / eZX-MB)


-SYNTAX--------------------------------------------------------

  .font file addr
  .font [option] file
  .font -s   show installed
  .font -v   file preview only
  .font -b   restore basic defaults
  .font -p [path1],[path2],[path3]
            view or set search path(s)

"file" must be exactly 768 B (font) or 168 B (UDG); any
other size returns "Bad size.

The extension is a HINT only:
  .FNT, .CHR  -> must be 768 B (font)
  .UDG        -> must be 168 B (UDG)
  other / none  -> size decides
A mismatch between extension and size is refused. With no
extension, .FONT searches <name>, then <name>.FNT, .CHR,
.UDG (first match).

"addr" is 0..65535 in decimal OR hex; see ADDRESS NOTATION.

When file load_addr < $6000 (= 24576), .FONT asks
"Address below 24576. Overwrite system? Y/N".

On success the command reports installation:
  Font: NAME.EXT 768B at 60000
(or "Udg:" for UDG files).


-EXAMPLES------------------------------------------------------

  .font myfont.fnt 50000     load font, set CHARS=49744
  .font glyphs.udg 65000     load UDG, set UDG=65000
  .font myfont.fnt $C350     hex addr ($C350 = 50000)
  .font myfont 50000 -s      load + show CHARS & UDG
  .font -r myfont.fnt        place above (RAMTOP)
  .font -e myfont.fnt        last byte at (P_RAMT)
  .font -n second.fnt        chain above current font
  .font -v showcase.fnt      preview only, do not keep
  .font -b                   restore CHARS / UDG defaults
  .font -p                   view configured paths
  .font -p /fonts,/usr/f     set PATH1, PATH2; clear PATH3
  .font                      print help banner


-ADDRESS NOTATION----------------------------------------------

  decimal      61440
  hex prefix   #F000   $F000   &F000   HF000   hF000
  hex suffix   F000#   F000$   F000&   F000H   F000h


-SWITCHES------------------------------------------------------

Switches are case-insensitive. <addr> is REQUIRED for the
basic form and for the bare "-s" load. <addr> is FORBIDDEN
with -r / -e / -n / -v / -b (the switch itself provides the
address, or there is no load). Extra numbers on the cmdline
are silently ignored.

  -s   After load, list both the CHARS set (codes 32-127,
       96 chars) and the UDG set (codes 144-164, 21
       glyphs) on the screen. Without a file, just shows
       the current state of CHARS and UDG.

  -r   load_addr = (RAMTOP) + 1
       First byte above the area protected by CLEAR.
       If load runs past (P_RAMT) -> "RAMTOP too high".

  -e   load_addr = (P_RAMT) - file_size + 1
       Last byte exactly on (P_RAMT). If the area between
       (RAMTOP) and (P_RAMT) is too small -> "RAMTOP too
       high".

  -n   load_addr = (CHARS) + 1024
       Directly above the standard 768 B font slot. For
       pre-loading a second font that can later be
       activated via the CHARS sysvar.

  -v   Preview a font/UDG file: display its glyphs on
       screen, but do NOT keep it - state is restored on
       exit. Uses a fixed work buffer at $6000.

  -b   Restore CHARS = $3C00 and UDG = (P_RAMT) - 167
       (BASIC defaults). No file is loaded.


-PATH MANAGEMENT (-p)------------------------------------------

The PATH list lets .FONT look up filenames that have no '/'
prefix in up to three additional directories on the current
drive. Stored in:

  /SYS/CONFIG/DOTFONT.CFG

Usage:

  .font -p                       view current paths
  .font -p /fonts                set PATH1, clear 2/3
  .font -p /a,/b,/c              set PATH1, PATH2, PATH3
  .font -p /a /b                 spaces work too

Each path must start with '/' and contain only letters,
digits, '/', '.', '_' or '-'. Max 24 chars per path.
Errors: "Invalid path", "Path too long",
"DOTFONT.CFG not found".

Lookup order for a file argument that does not start with
'/' (= relative name):
  1) current directory
  2) PATH1
  3) PATH2
  4) PATH3
For each directory the extension search above is repeated
(when no extension was given). First match wins. A file
name starting with '/' is absolute - the PATH list is not
consulted.


-COMBINATIONS / PRECEDENCE-------------------------------------

If multiple address-source switches appear, this fixed
precedence applies (later are ignored):

  -v     wins everything    (preview always at $6000)
  -e     wins over -r, -n   (works at top of RAM)
  -n     wins over -r       (chain above current font)
  -r     wins over <addr>   (cmdline address ignored)

-s can be combined with anything that loads a file.


-ERRORS--------------------------------------------------------

  Unknown switch
       Letter after '-' is not s / r / e / n / v / b / p.

  Filename too long
       Filename + extension exceeds 131 characters.

  Number =<65535 expected
       Address missing, invalid, or > 65535.

  Cancelled by user
       Non-Y key at the "Overwrite system?" prompt.

  Cannot open file
       esxDOS could not open the file in any searched
       directory (no such file, drive error, etc.).

  File read error
       esxDOS I/O error during read.

  Empty file
       File is 0 bytes.

  Bad size, expected 768B or 168B
       File is not exactly 768 (font) or 168 (UDG), or
       size disagrees with the extension hint.

  File too big (max 2048 bytes)
       Fail-safe: file exceeds the internal max buffer.
       (Triggered before "Bad size" for huge files.)

  RAMTOP too high
       -r or -e cannot place the file safely. Lower
       RAMTOP with CLEAR <addr> first.

  DOTFONT.CFG not found
       -p without args could not open the config; or -p
       with args could not create it.

  Invalid path
       A path argument to -p contains a forbidden char,
       or does not start with '/'.

  Path too long
       A path argument to -p exceeds 24 characters.


-MEMORY LAYOUT NOTES-------------------------------------------

  - CHARS area  = 768 B  (96 chars * 8 px)
  - UDG area    = 168 B  (21 glyphs * 8 px)
  - (CHARS) points 256 B BELOW the data, so ROM lookup
    LD A,c / LD H,$3D / LD L,A*8 works for codes 32..127.
  - (UDG) points directly at the first UDG byte.


-LOWERING RAMTOP-----------------------------------------------

To use -r or -e safely, lower RAMTOP first in BASIC:

  CLEAR 49999            : REM frees 50000..65535
  .font -r myfont.fnt    : REM loads at 50000

CLEAR <addr> is preferred over POKE 23730,... because it
also moves the BASIC stack.

===============================================================
end of manual
