VU-R Browser
============

As I was a bit fed up with doing HTML, I thought that I'd write
a Spectrum program with which to read some of the new Your
Spectrum programming articles I'm adding on YRUA?. This is a
summary of how it all works.

* The article is prepared in a text file with a name of the form
  YRii_pp.TXT (where ii=issue and pp=page). The browser supports
  four character pitches: 32, 48, 64 and 42; so each change of
  pitch within the text is marked by a line starting:
    !0 or !1 or !2 or !3
  respectively. The end of article text is marked by a line
  starting !$ (this allows extra text to be added afterwards
  which will be ignored by the browser file builder program).

  Lines using standard 32-pitch characters may include print
  controls (or any other characters) anywhere in the lines,
  specified in the form:
    \Hxx	where xx is a 2-character lower case hex number
    \Dnnn	where nnn is a 3-digit decimal number

  Lines using non-standard pitch characters (PrintPR/64/42)
  may only include print controls which apply to the whole line.
  These are specified using the same syntax as above, but on a
  separate line starting !P, which should immediately follow the
  font marker line; eg.
    !2			= "use Print64 font"
    !P\H11\H07\H10\H02	= "use white Paper and red Ink"
    text ...
  These global print controls apply until the next font marker
  occurs. Regular characters appearing in GPC lines will be
  discarded. GPC entries are set to a fixed length of 10 bytes;
  longer entries will be truncated; shorter entries will be
  padded with 15h01h (OVER 1).

  A third type of special marker is !S; this indicates that a
  screen-shot is to be loaded at that point, the SCREEN$ file
  name being defined immediately following; eg.
    !SYR19_26A

  The fourth type of special marker is !B; this requires no
  additional parameters, and is used to mark section breaks
  within the text, for use with the Section skip option.

  See the "Sprite High, No Limit" article in YR19_26 for 
  examples of all of these print controls.

* The program ARTICLE.SH is run to prepare a data file named
  YRii_pp.DD0, containing four data segments:
	section markers (two bytes per section)
  	article text; all markers & line breaks removed
  	article line pitches (one byte per line)
  	article line lengths (one byte per line)
  Each data segment is terminated with a FFh or 80h byte,
  depending upon whether or not there are any FFh entries in
  the segment which need resetting to 00h (the Unix tools will
  not handle NULL bytes, so they have to be stored as FFh and
  reset later by ARTICLE.Z80 below).

* The batch file ARTICLE.BAT is run, which runs the programs
  CONVERT.EXE and ARTICLE.Z80 to create the browser data file
  YRii_pp.TAP. CONVERT.EXE converts the YRii_pp.DD0 file to a
  YRii_pp.CC0 file, which is in a form which can be read by the
  LOAD *"b" command in the Spectrum emulator, which is then
  loaded by ARTICLE.Z80 and saved as CODE blocks in the TAP
  file. The data files saved are:
  ArticleHDR	DATA: string array recording the size and base file
  		name (YRii_pp) of the following files
  YRii_pp.cL	CODE: article line lengths (one byte per line)
  YRii_pp.cF	CODE: article line pitches (one byte per line)
  YRii_pp.cD	CODE: article text; all markers & line breaks removed
  YRii_pp.cC	CODE: cumulative line lengths (two bytes per line)
  YRii_pp.cB	CODE: section markers (two bytes per section)

  (CONVERT.EXE is one of the utilities supplied with the
  registered version of the Z80 Spectrum emulator, so it is not
  included in this archive.)

* The resultant YRii_pp.TAP file can then be loaded and read via
  the VU-R program BROWSER.Z80; instructions are displayed at the
  start. In addition, I add to the TAP file the code segments from
  the article, so that these can be run as a separate demo.


Notes on the machine code routines in BROWSER.Z80
=================================================

The pre-loaded CODE block is located at 63234,2134.
PrintPR is variable-pitch; the others are fixed-pitch.

a) The Print42 routine
----------------------
First, located at 63234,456, is the Print42 routine, from the
article "42 and 64" by Paul Wardle in Your Sinclair #78
(Jun.1992). All I've changed in this code is to relocate it
higher in memory.

The characters to be printed just need to be assigned to the
string variable z$ (which should be a regular string, not a
one-dimensional array, otherwise the routine won't find it),
which can be as long as you like.

Print42 recognises these special characters in z$:
CHR$ 22 + y-pos + x-pos: "PRINT AT" control (line+column)
CHR$ 13: "ENTER" (positions to next line, column 0)

b) The PrintPR character set
----------------------------
Second, at 63690,768, is my "neatset" alternate character set
which I designed to be used by the PrintPR routine. This
actually allows 48 characters to be easily fitted on each screen
line of normal English (PrintPR was written assuming the regular
Spectrum character set might be used, which is fatter). You can
load any character set in here, or use the regular Spectrum one
by changing bytes 64460+64461 to point to the one in the ROM.

NOTE: I've formatted PrintPR sections of VU-R articles
assuming that my "neatset" is being used (ie. with 48-column
lines), so using a different character set for viewing them
might become messy if it's not as compact, as some of the lines
might not fit across the screen.

c) The PrintPR routine
----------------------
Third, located at 64458,185, is the PrintPR routine, based on
code from the article "Arcade Antics" by David McCandless in
Your Sinclair #29 (May.1988). The printed routine contained
redundant code; had the last byte chopped off, so that the last
routine jumped into the middle of the token table; had some
unnecessary jumping around; was located in a daft place stuck in
the middle of RAM; and the instructions given for using it were
incorrect - so I tidied it up and relocated it in high memory
to use here. 

NOTE: The USR address for calling PrintPR is 64462, as the
first four bytes hold:
	64458	POKE X pixel offset
	64459	POKE Y line offset
	64460+1	POKE character set location (-256)
The VU-R browser uses my built-in "neatset" by default.

The characters to be printed can be located anywhere in memory,
although VU-R uses a one-dimensional string array i$(),
and uses the sub-routine at 2000 to find where it is. Bytes
64464+64465 must be poked with the start address of the first
character to be printed; the characters must end with a 00h
character. These other control codes may be used in the string:
22 = PRINT AT; followed by: Y line offset, X pixel offset.
13 = RETURN; to make the string continue on the next line down.

NOTE: PrintPR doesn't do anything clever at the end of the
line, just printing right up to the edge and then onto the next
line when it's full, even if it's in the middle of a character;
so it's best to ensure that the characters to be printed will
fit into a width of 256 pixels; eg. by setting some likely
maximum number of characters, based on the character set being used.

d) The Print64 routine
----------------------
Fourth, located at 64643,725, is the Print64 routine, from the
article "Pro Ace Word" by Paul Brookes in Sinclair User #57
(Dec.1986). The print position is entered thus:
	65368	POKE X pixel offset
	65369	POKE Y pixel offset
The characters from 20h to 8Fh (112 chars) are defined from
65032-65367 (336 bytes), with each pair of characters being
defined in 6 bytes; the 1st using the LH 4 bits and the 2nd
the RH 4 bits in each of the 6 bytes - thus 29 lines can be
fitted into the main part of the screen, rather than the
regular 22 lines.

The characters to be printed just need to be assigned to the
string variable z$ (which should be a regular string, not a
one-dimensional array, otherwise the routine won't find it),
which should be no more than 64 characters long.

NOTE: Print64 used the first four bytes of the 48k Spectrum
printer buffer starting at 23296 for workspace, but this won't
work in 128k mode as this area is used for extra system variables.
So I changed the routine to use the next four bytes immediately
following the end of the Print64 character set definitions
(65368-65371); ie. what is usually the first four bytes of UDG "A"
- so that character gets corrupted, but is restored when "Quit"
is selected. I've also redefined several of the characters.


--
Another Fine Product from:
Jim Grimwood, Weardale, England; home of:
Your Spectrum Unofficial Archive (YRUA?)
Spectrum Oracle on Trumpton (SPOT*On) magazine index
The Type Fantastic (TTFn) magazine type-ins archive
http://www.users.globalnet.co.uk/~jg27paw4/
--
