==========================================================================
                CDVIEW - Sixel CD-ROM Picture Door  (Win32 / DOOR32)
                            NewWave Software
==========================================================================

CDVIEW lets BBS callers browse picture CD-ROMs, folders and ZIP files,
view the pictures as DEC sixel graphics, read ANSI art and text files in
a scroller (with ANSI music), and download what they like with ZModem.

This is the full reference. HOWTO.TXT is the short step-by-step guide,
and every setting is also explained at the bottom of CDVIEW.CFG.

CONTENTS
   1  Files                         11  Viewing pictures
   2  Installing                    12  The ANSI / text scroller
   3  Launching from the BBS        13  ANSI music
   4  CDVIEW.CFG settings           14  ZIP archives
   5  Areas                         15  ZModem downloads
   6  The area menu                 16  The terminal check
   7  The file listing              17  JPEG XL (optional)
   8  Descriptions                  18  Log files
   9  File types                    19  Troubleshooting
  10  What a caller sees            

--------------------------------------------------------------------------
 1. FILES
--------------------------------------------------------------------------

  CDVIEW.EXE        the door (built from this package - section 20)
  CDVIEW.CFG        settings
  CDVIEW.TXT        this file
  HOWTO.TXT         the step-by-step guide
  FILE_ID.DIZ       description for file areas

  Optional:
  MAIN.ANS, MENU1.ANS ...  your own area menu art (section 6) - only if
                    you don't want the built-in menu
  JXL.DLL + its DLLs   JPEG XL support (section 17)
  FONTS\*.CHR       BGI stroke fonts for RIP pictures (section 11) -
                    recommended if you have any .RIP files

  Made by the door while it runs:
  CDVIEW.DBG        start-up trace (TRACE=YES)
  NODEn.LOG         what callers did (NODELOG=YES)
  CDVTEMP\N<node>\  scratch space for files unpacked from ZIPs; always
                    emptied again
  LASTVIEW.SIX      local mode only: the last picture's sixel data

  The opening screen and the built-in menu art are compiled into the
  door, so there are no other .ANS files to keep with it.

--------------------------------------------------------------------------
 2. INSTALLING
--------------------------------------------------------------------------

  1. Make a door folder (e.g. D:\CDVIEW) and copy CDVIEW.EXE and
     CDVIEW.CFG into it.
  2. Edit lines 1-4 of CDVIEW.CFG (section 4).
  3. Add an AREA= line for each CD-ROM or picture folder (section 5).
  4. Add the door to a BBS menu (section 3).
  5. Test it locally:  CDVIEW.EXE /L
     The Windows console can't draw sixel, so local mode shows each
     picture in a preview window instead - same size, palette and
     dithering a caller would get. Any key or click closes it.

--------------------------------------------------------------------------
 3. LAUNCHING FROM THE BBS
--------------------------------------------------------------------------

  CDVIEW is a 32-bit Windows DOOR32 door: it talks to the caller over the
  telnet socket the BBS hands it.

  Command line:
     /N<node>             node number          /N1  or  /N 1
     /P <drop file>       the drop file:  /P D:\BBS\TEMP1\DOOR32.SYS
                          or just its folder:  /P D:\BBS\TEMP1\
     /D <file>            NFU's form - the folder of <file> is used
     /SOCKET <handle>     the caller's live socket handle (NFU passes
                          this); always wins over the one in DOOR32.SYS
     /L                   local test, no caller

  Where the drop file comes from: the command line is tried FIRST. If
  no drop file is there, line 2 (folder) and line 1 (type) of
  CDVIEW.CFG are used instead - the .CFG is only the fallback. When /P
  names the file, its name also sets the type: DOOR32.SYS, DOOR.SYS,
  DORINFO#.DEF or VIVID#.SYS. CDVIEW.DBG logs which file was read.

  Renegade with NetFoss NFU (one line):
     d:\netfoss\nfu.exe ... "d:\cdview\cdview.exe /n 1
                    /d \bbs\temp1\door.sys /socket 420"
  A DOOR32 BBS (Mystic, Synchronet ...), using your BBS's own codes:
     D:\CDVIEW\CDVIEW.EXE /N%N /P %P\DOOR32.SYS

  On start-up the door checks the socket really is a live connection;
  if not, it says so on the local screen and in the logs (a DOOR32.SYS
  left over from an earlier call is the usual cause - section 19).

--------------------------------------------------------------------------
 4. CDVIEW.CFG SETTINGS
--------------------------------------------------------------------------

  Lines 1-4 are fixed, in this order:
     4                drop file type: 1 VIVID#.SYS  2 DORINFO#.DEF
                                      3 DOOR.SYS    4 DOOR32.SYS
     D:\BBS\TEMP1     folder of the drop file (the fallback - section 3)
     SysOp            sysop name
     Your BBS Name    BBS name

  After that, KEY=VALUE lines in any order. Unknown lines are ignored,
  so the help text at the bottom of the file does no harm.

  Areas and menu
     AREA=          one per area (section 5)
     MAINMENU       INTERNAL (built-in menu, default), a file name such
                    as MAIN.ANS (your own art), or NONE (plain list)
     MENUPAGES      name of your extra menu pages, # = page number
                    (default MENU#.ANS)
     IMAGEDIR       the one folder shown if there are no AREA lines
  Listings
     SCREENROWS     callers' screen height in text lines (default 24)
     DESCLINES      description lines per file, 0-15 (default 4)
     DESCFILES      description lists to read, in order (section 8)
     DIRSFILES      folder-description list name (default DIRS.TXT)
     DOWNLOADS      YES / NO - tagging and ZModem downloads
     ENTER          VIEW (default) or DOWNLOAD - what Enter does on a file
  Pictures
     MAXWIDTH       largest picture sent, pixels (default 800)
     MAXHEIGHT      (default 480); also limited by the caller's window
     PALETTE        ADAPTIVE (best 256 colours per picture) or CUBE
     COLORS         0 = ask the terminal, or force a number
     DITHER         YES = smooth gradients, NO = smaller transfers
  Terminal check
     SIXELCHECK     AUTO (ask if not reported), FORCE, STRICT
     PROBETIMEOUT   ms to wait for the terminal's answer (default 2000)
  ANSI / text
     LINESCROLL     YES = smooth line scrolling, NO = full redraws
     ANSIMUSIC      YES = send ANSI music to callers, NO = drop it
     MUSICLOCAL     AUTO (local mode only), YES, NO - play on this PC
  Other
     SPLASH         seconds to show the opening screen, 0 = none
     NODELOG        YES / NO - NODEn.LOG
     TRACE          YES / NO - CDVIEW.DBG

--------------------------------------------------------------------------
 5. AREAS
--------------------------------------------------------------------------

     AREA=Type|Name|Path [*]

     AREA=2|ANSI Archive|D:\CDVIEW\ANSI\ANSIA *
     AREA=1|Bart's GIF Pictures|D:\CDVIEW\CDROM\BART
     AREA=1|GIFs Galore|E:\

  Type     1 = CD-ROM, 2 = Collection - shown under the name on the
           built-in menu. Leave it off (AREA=Name|Path) for CD-ROM.
  Name     anything you like.
  Path     a whole CD drive (E:\) or any folder; relative paths are
           relative to the door folder.
  *        list EVERY file in this area, whatever its extension (see
           section 9) - for ANSI packs named after their group
           (ANSI.MEM, LOGO.8XT ...).

  Areas are numbered in the order of the AREA lines: the first is 1.
  Callers can open sub-folders inside an area but never get above its
  path; they never type a path at all, only pick from what the door
  lists, so input like ..\..\ can't reach anything. With only one AREA
  line the menu is skipped. If a CD isn't in the drive, callers get a
  polite message instead of an error.

--------------------------------------------------------------------------
 6. THE AREA MENU
--------------------------------------------------------------------------

  THE BUILT-IN MENU (MAINMENU=INTERNAL - the default)

  The door's own "CD-ROM / Collection Area" screen, filled in from the
  AREA lines: 5 areas down the left, 4 down the right, Quit at the
  bottom right - 9 areas per page. Under each name: "CD-ROM" or
  "Collection" (the area's type). Names are cut at 27 characters so
  they never run into the panel edge.

  With more than 9 areas there are more pages, and a centred line under
  the menu says:   (down arrow) for Next, or (up arrow) for Previous
  Down past the last entry (after Quit) goes to the next page; Up past
  the first goes back to the previous page's last area.

  YOUR OWN ART (MAINMENU=MAIN.ANS)

  Draw the menu in any ANSI editor, keep it within 80 x 24, put it in
  the door folder and name it on the MAINMENU line. CDVIEW finds the
  selectable entries by this pattern - a NUMBER, a VERTICAL BAR (the
  CP437 line character 179 or 186, or a T-join), then the LABEL:

       12| BBSmate Shareware
        Q| Quit & Exit!

  - The number is the AREA line it opens (1 = the first).
  - The label can say anything. The lightbar covers it, from its first
    character to the last one before a gap of two or more spaces, with
    one space of padding each side.
  - Q instead of a number is a Quit entry.
  - Numbers with no AREA line, and everything else, are just art.
  - If the art contains "::>", numbers typed by the caller appear there.
  - More pages: MENU1.ANS, MENU2.ANS ... in the same format, numbering
    on from the page before. They're read up to the first missing one.
    (Older MAIN2.ANS, MAIN3.ANS names still work if there's no MENU1.)
  - If the file named on MAINMENU is missing, the built-in menu is used.

  MAINMENU=NONE gives a plain two-column list of the area names.

  KEYS (all menus)
     arrows       move the bar - Up / Down stay in the same column and
                  carry on into the next column (5 -> 6) and page at the
                  end of one; Left / Right jump across columns
     Home / End   first / last entry
     Enter        open the area (or Quit, on the Quit entry)
     a number     open that area, even if it's on another page
     PgUp / PgDn  previous / next page
     ESC / Q      leave the door

  The bar is redrawn as one block, so it never flickers, and the cursor
  is hidden on every lightbar screen.

--------------------------------------------------------------------------
 7. THE FILE LISTING
--------------------------------------------------------------------------

     Bart's GIF Pictures  \DRAWN\
    ----------------------------------------------------------------
       1  CARS\            <DIR>  03-19-94  Car pictures
       2+ ASTRO.GIF        79155  03-02-94  An astronaut portrait from
                                            NASA, 640x480
    ----------------------------------------------------------------
              Page 1 of 3  (2 folders, 41 pictures)  Tagged: 1 (77 KB)
     arrows SPACE=Tag C=Clear Tags D=Download ENTER=View S=Search ESC=Quit

  Folders first, then files, each sorted by name. A + marks a tagged
  file. The status and help lines are centred.

  KEYS
     Up / Down       move the bar         PgUp / PgDn  page
     Home / End      first / last
     Enter, Right, V view the file / open the folder or ZIP
                     (ENTER=DOWNLOAD makes Enter download instead)
     Left, Backspace, U   up one folder
     ESC             back one level: out of a ZIP, up a folder, then to
                     the area menu
     Q               leave the area
     SPACE (or T)    tag / untag the file; the bar moves down, so
                     SPACE SPACE SPACE tags a run
     C               clear all tags
     D               download the tagged files - or, with nothing
                     tagged, the file under the bar
     X               download just the file under the bar (works, but
                     isn't shown - D covers it)
     S (or /)        search by name or part of a name
     a number        open that entry by its number

  Tags are kept across folders and areas until the files are
  downloaded. Going up a folder puts the bar back on the folder you
  came from; leaving a picture puts it on the last picture shown.
  Callers whose terminal sends no arrow keys can use numbers, Enter, U
  and Q. Arrow and page keys are understood in VT (ESC[A, ESC[5~),
  ANSI-BBS (ESC[V / ESC[U) and Renegade / RGTERM (ESC[r / ESC[q) forms.

--------------------------------------------------------------------------
 8. DESCRIPTIONS
--------------------------------------------------------------------------

  FILES - read from the lists CD-ROMs already carry, in each folder, in
  this order (the first list that actually describes a file wins):
     FILES.BBS          the usual BBS list
     DIR1 DIR2 ...      PCBoard lists, in number order (DIR# in DESCFILES)
     00_INDEX.TXT       Simtel / Walnut Creek index
     SF_FILES.BBS
     DESCRIPT.ION       4DOS / Windows descriptions
  Size, date, download-count and Simtel type columns are skipped;
  indented, | or + continuation lines are joined; PCBoard @X colour codes
  are removed; names match in any upper/lower case. A list that only
  names a file without describing it doesn't hide a later list's
  description. DESCFILES= changes the lists and their order.

  FOLDERS - from DIRS.TXT, as many CDs keep at their root:
     gifs/cars/      - cars, trucks and motorcycles
  It's found in the area folder or any folder above it, and matched
  even if the pictures were copied without the folder it names. Any
  folder further down can have its own DIRS.TXT for the folders inside
  it, with paths relative to that folder ("alpha/  - Alpha pictures");
  that one wins. A folder no DIRS.TXT mentions falls back to FILES.BBS
  and the others. You can write DIRS.TXT files yourself.

  Description lists are never shown as files. Control characters in
  descriptions and names are removed, so a disc can't send escape
  codes to callers.

--------------------------------------------------------------------------
 9. FILE TYPES
--------------------------------------------------------------------------

  Pictures (shown as sixel):
     .GIF .JPG .JPEG .PNG .BMP .PCX
     .TIF .TIFF   uncompressed, LZW, PackBits, Deflate; grey, palette,
                  RGB, RGBA, black & white (not JPEG-in-TIFF or fax)
     .TGA         also .VDA .ICB .VST; plain and RLE
     .JXL         only with JXL.DLL (section 17)
     .RIP         RIPscrip vector pictures, drawn by the door (see
                  "RIP pictures" in section 11)
  Text (shown in the scroller):
     .ANS         ANSI art
     .ASC .TXT .NFO   plain text
  Archives:
     .ZIP         opened like a folder (section 14)

  In an area marked with *, every file is listed. One whose name
  doesn't say what it is is shown as a picture if its first bytes say
  it's one (GIF, PNG, JPEG, BMP, PCX, TIFF, JXL), otherwise as ANSI.
  Pictures with the wrong extension are recognised the same way in any
  area. Everything after a Ctrl-Z in a text file is ignored, which
  also drops SAUCE records.

--------------------------------------------------------------------------
 10. WHAT A CALLER SEES
--------------------------------------------------------------------------

  1. The opening screen ("NewWave Software presents CD View") for up to
     SPLASH seconds - any key skips it.
  2. The terminal check (section 16).
  3. The area menu, then the file listing for the area chosen.

--------------------------------------------------------------------------
 11. VIEWING PICTURES
--------------------------------------------------------------------------

  Row 1 shows the name and details, e.g.
     Decoding BOUDIN.GIF (10 of 134) ... 526x261, 127 colours, 224 KB
  the picture is drawn below it, and the bottom row says [Any Key
  Aborts] while it's being sent. Pictures are scaled to fit between the
  two (and to MAXWIDTH / MAXHEIGHT), so the top line never scrolls away.
  When it's done the bottom row offers:
     N / Right / Down   next picture      P / Left / Up   previous
     T                  tag / untag       D (or X)        download it
     Enter              back to the listing

  RIP PICTURES: a .RIP file is drawn by the door itself - with the RIP
  renderer from RGTERM, on RIP's 640 x 350 EGA screen, stretched to
  640 x 480 so it keeps its shape - and then sent as sixel like any
  other picture. So RIP art shows on every sixel terminal, RIP-capable
  or not. Supported: lines, rectangles, bars, circles, ovals, arcs, pie
  slices, Bezier curves, polygons, flood fills, the 12 BGI fill patterns
  and user patterns, line styles and thickness, the EGA palette, text
  in the 8x8 font and the BGI stroke fonts, buttons and icons (.ICN
  files next to the .RIP). Files inside ZIPs work too.
  INSTALL THE BGI FONTS: copy TRIP.CHR LITT.CHR SANS.CHR GOTH.CHR
  SCRI.CHR SIMP.CHR TSCR.CHR LCOM.CHR EURO.CHR BOLD.CHR into a FONTS
  folder in the door folder (RGTERM keeps the same files in its own
  fonts folder). Without them, text in those fonts falls back to the
  8x8 font - and many RIP pictures outline their lettering and then
  flood-fill the inside of each letter, which then misses and spreads
  over the picture. CDVIEW.DBG notes it when fonts are missing.
  A .RIP with no drawing commands in it gets "no RIP graphics in this
  file". Mouse buttons in RIP menus are drawn but can't be clicked.

  PALETTE=ADAPTIVE (default) picks the best 256 colours for each
  picture, so photos come out smooth; CUBE uses one fixed 216-colour
  palette (smaller, grainier). Typical sizes for an 800x480 photo:
  adaptive 300-500 KB, cube 250-400 KB, flat artwork 2-60 KB - instant
  over telnet. On a real modem, lower MAXWIDTH / MAXHEIGHT or set
  DITHER=NO.

--------------------------------------------------------------------------
 12. THE ANSI / TEXT SCROLLER
--------------------------------------------------------------------------

  ANSI and text files are drawn into an 80-column virtual screen of any
  height first, so even art that moves the cursor around scrolls
  correctly. The bottom line shows the name, the lines on screen and
  the keys; it stays put and never flickers.
     Up / Down          one line          PgUp / PgDn, Space  a screen
     Home / End         top / bottom
     N / Right          next file         P / Left           previous
     T                  tag / untag       D (or X)           download
     ESC, Enter, Q      back to the listing

  Up / Down scroll the caller's screen by one line (ANSI insert / delete
  line inside a scroll region above the status line) and send only the
  new line. At the start of each call the door tests whether the
  terminal honours scroll regions (a one-line test with a cursor
  position report, done on the blank screen before the terminal check):
  if it does (RGTERM, SyncTERM ...) only the line numbers on the status
  line are rewritten while scrolling, so it never flashes; if it doesn't
  (fTelnet and other web terminals) the whole status line is put back
  after each move. If a caller's terminal can't scroll at all,
  LINESCROLL=NO redraws the whole screen instead. Plain text has tabs
  expanded, control codes removed and long lines wrapped at 80 columns.

--------------------------------------------------------------------------
 13. ANSI MUSIC
--------------------------------------------------------------------------

  ANSI files can carry music: ESC[M, a BASIC PLAY string (notes, tempo,
  octave ...) and a Ctrl-N. When such a file is opened, the music is
  sent on to the caller's terminal, which plays it - RGTERM, SyncTERM
  and other ANSI-music terminals do; others ignore it. The music never
  shows up as stray letters in the picture. (An ESC[M only counts as
  music if a Ctrl-N follows before the next ESC, CR or LF; otherwise
  it's the normal "delete line" code.)

  A tune plays once per opening - tagging the file doesn't restart it,
  leaving and coming back does. In local mode (/L) it also plays on the
  sysop's sound card, on a background thread, using the PLAY player
  from DRAW32; MUSICLOCAL=YES plays it locally during calls too, NO
  never. ANSIMUSIC=NO leaves music out altogether.

--------------------------------------------------------------------------
 14. ZIP ARCHIVES
--------------------------------------------------------------------------

  ZIP files are listed with the pictures (with their FILES.BBS
  description) and open like a folder with Enter. The pictures, ANSI
  and text inside are listed - those in folders inside the archive show
  that folder as their description - and can be viewed, stepped through
  with N / P, tagged and downloaded one by one. A whole ZIP can still
  be tagged and downloaded from the folder listing. Left / Backspace /
  ESC go back out.

  Packing methods: stored, shrunk and imploded (PKZIP 1.x - common on
  early CD-ROMs) and deflated (PKZIP 2 and everything since). "Reduced"
  (PKZIP 0.x), newer methods and password-protected files get a message
  saying why. Every unpacked file is CRC-checked, members over 32 MB are
  refused, and ZIPs inside ZIPs aren't opened. Members are unpacked one
  at a time into CDVTEMP\N<node>\ under a cleaned-up name (so a hostile
  archive's "..\..\" names go nowhere) and deleted straight after use.
  A downloaded member keeps its date from the archive.

--------------------------------------------------------------------------
 15. ZMODEM DOWNLOADS
--------------------------------------------------------------------------

  ZModem only. The caller sees the files and the total size and
  confirms; most terminals (RGTERM, SyncTERM, NetRunner, mTelnet ...)
  then start receiving by themselves. Ctrl-X a few times cancels, and
  so does ESC on the sysop's keyboard. Afterwards the caller gets a
  summary - sent (with the speed), skipped because they already had it,
  failed. Sent and skipped files are untagged; failed ones stay tagged
  so D tries again. Files go out with their original dates, and each
  one sent is written to the node log. DOWNLOADS=NO turns it all off.

--------------------------------------------------------------------------
 16. THE TERMINAL CHECK
--------------------------------------------------------------------------

  The door asks the caller's terminal what it can do (a Device
  Attributes query; sixel terminals report attribute 4), and from
  sixel terminals also the number of colour registers and the window
  size in pixels, so each picture is sized and coloured to fit. The
  "Sixel Terminal Check" box shows YES!, MAYBE (SyncTERM) or NO!.

  SIXELCHECK=AUTO   if the terminal doesn't report sixel, ask "Show
                    pictures anyway?" (Yes / No lightbar)
  SIXELCHECK=FORCE  never ask
  SIXELCHECK=STRICT turn such callers away

  Works with: RGTERM, SyncTERM (recent), MagiTerm, and also xterm
  (-ti vt340), mlterm, foot, WezTerm, Windows Terminal 1.22+, iTerm2,
  Konsole, contour.

--------------------------------------------------------------------------
 17. JPEG XL (OPTIONAL)
--------------------------------------------------------------------------

  Put a 32-bit (x86) JXL.DLL from libjxl 0.7 or newer in the door
  folder, with the DLLs it needs (BROTLICOMMON, BROTLIDEC, BROTLIENC,
  JXL_CMS for a shared build; a static build is one file). The BBS
  machine also needs the Microsoft Visual C++ 2015-2022 Redistributable
  (x86) - even on 64-bit Windows. The DLL is only loaded from the door
  folder; a 64-bit or broken one is detected and ignored.

  Without a usable JXL.DLL, .JXL files aren't listed; CDVIEW.DBG says
  why. Animated JXL shows its first frame; pictures over 24 megapixels
  are refused. Or convert instead:  djxl picture.jxl picture.png

--------------------------------------------------------------------------
 18. LOG FILES
--------------------------------------------------------------------------

  NODEn.LOG    areas entered, files viewed, downloads (NODELOG=YES)
  CDVIEW.DBG   one line per start-up step of every call - command line,
               drop file read, socket check, the terminal's answer,
               description lists read, how the door ended (exit code,
               or the source line of a crash) (TRACE=YES). Rolls over
               at 256 KB into CDVIEW.DBG.OLD.
  Both switches are read before anything else, so with NO neither file
  is ever touched.

--------------------------------------------------------------------------
 19. TROUBLESHOOTING
--------------------------------------------------------------------------

  The door doesn't start, or only works on the 2nd or 3rd try
     Set TRACE=YES and read CDVIEW.DBG. Usually it's a DOOR32.SYS from
     an earlier call: its socket number only works when Windows happens
     to reuse it. Point /P (or line 2 of CDVIEW.CFG) at the folder your
     BBS writes the drop file to for THIS call, or pass /SOCKET.

  "Your terminal didn't say it supports sixel graphics"
     The terminal didn't answer the check. If it really does sixel the
     caller can answer Yes; SIXELCHECK=FORCE skips the question.

  A menu entry can't be selected (your own MAIN.ANS)
     It must be  number + CP437 bar (179/186) + label,  and the number
     needs an AREA line. CDVIEW.DBG says how many selectable entries
     each menu page has.

  Descriptions don't show
     CDVIEW.DBG lists, per folder, which lists were read and how many
     folders DIRS.TXT described. Check the list is in the same folder
     as the files, and that DESCFILES isn't overridden by an old line.

  JXL files aren't listed
     CDVIEW.DBG says why: no JXL.DLL, not 32-bit, a missing DLL, or the
     Visual C++ runtime isn't installed.

  Scrolling ANSI looks wrong on some terminal
     LINESCROLL=NO.

  Odd characters on the sysop's screen
     The door switches the console to code page 437 while it runs; use
     a console font with the CP437 characters (raster font, Consolas).
