***********************************
		*	    NTXT3 notes:	  *
		*      including source code	  *
		***********************************

This program owes its existence to the original Z80 version, TXT.COM, by
Simon Ewins (416) 484-9663 (EMX RCPM) and to the 8080 adaptation,
N-TXT.COM, by Harry Kaemmerer, CP/M-NET EAST (201) 249-0691 whose fuller
explanation may be found below.

PAGING added (and display routine changed) by Walt Wheeler (YOU) and
Justus Addiss (Sigma Xi), 12 June 84

------------------------------------------------------------------------

NTXT3.COM provides a means for creating a RUNNABLE document...that, for
making a document accessable to users unfamiliar with CP/M, or, in
another example provided by Simon Ewins,

	"We have used it to help on my RCPM with the problem
	of some users typing QUIT or LOGOFF etc. instead of BYE.

	"Instead of having to create an assembler filewith DB
	lines and write a routine to print a message that says
	"Please use BYE to log off this system......" (plus
	other info), and then assemble it and then load it, we
	simply follow the procedure outlined (below) and create
	an 'instant' .COM file with the editing capabilties of
	WordStar.

	"We have also used it to display help files in a busi-
	ness environment.  The operator simply types the name
	of the item she/he wishes to know more about and gets
	an instant listing."

The following instructions refer to use with WordStar, but could equally
well be implemented with any editor (including, ugh, ED) that is capable
of creating plain vanilla ASCII files.

	1.  Open a file using the NON-document mode, under the name you
want to use when the TEXT file is displayed, for example THISSYSTEM.COM.
(No, Virginia, WordStar will NOT balk at editing a file of type ".COM")

	2.  Use ^KR to read in the file NTXT3.COM as the initial part of
the new runnable file.	(The file NTXT3.COM amounts to a machine lang-
uage header which includes all the code necessary to display and page
the test you'll be adding.)

	3.  Locate the "?" and NUL ("^@") which delimit the beginning
and end of the text buffer in the "copy" you've just read in.  (They're
side by each, as distributed.)

======> NOTE: the "^@" in NTXT3.COM really is a NUL <======
======> and NOT -- again, NOT -- a CARET/AT_SIGN   <======

	4.  Now, use ^KR to read in a plain ASCII (but NOT a WordStar
document-mode)file which has been created previously, or use WordStar's
capabilities to insert text, graphics, or whatever,  between the delim-
iters.	(The closing NUL is included in the file because some systems in
common use -- including the Osborne and Otrona "Attache" have no direct
method of generating a NUL.)

	5.  If you wish to include notes which will NOT be displayed
when the file is run, add them after the final NUL.

	6.  WARNING:  If you somehow omit a closing NUL, undefined and
sometimes unpleasant results will occur.

------------------------------------------------------------------------

To use the paging function, insert a TILDE (07EH):

	EITHER immediately before the first character which you want to
have appear on the next screenful (after the <CR><LF> pair at the end of
any given page)

	OR  (together with a <CR><LF> pair as terminators) on an other-
wise blank line between the two pages of text in question.

	NOTE:	Putting the TILDE at the end of the final line
		of a page, before the <CR><LF> will cause the
		"Hit any key...." prompt to display WITHOUT
		any spaces or other breaks, immediately after
		the last character of your screenful.

If you follow the above suggestions a screenful (page) should not exceed
23 lines, as the "Hit any key..." does force a newline and thus will
force the first line of a 24 line page to scroll off screen, very pos-
sibly before the user has a chance to read it.

------------------------------------------------------------------------

KNOWN DEFICIENCIES, LIMITATTIONS:

Because the paging routine uses BDOS Function 6 (for good and sufficient
reason (determining that reason is left as an exercise for the reader)
and because our ambition gave out before implementing the usual methods
of aborting a program or halting the display, ^C, ^S (and sometimes ^Z)
DO NOT WORK.  As the British have it, "in for a penny, in for a pound."

Should someone add the necessary code to do that, we'd be pleased ...and
pleased to see same.  Bug reports, too, please.
					- Walt Wheeler

	SOURCE CODE:


;--------------------------------------------------------------------
;	NTXT3.ASM  adapted from:
;
; The original z80 TXT.COM version by Simon Ewins (416) 484-9663 (EMX
; RCPM)
;
; The 8080 source for the first two lines or so of N-TXT.COM message
; utility January 1 1984 by Harry Kaemmerer CP/M-NET EAST (201) 249-0691
;
; Added PAGING, allowing the creator of a file to implement paging, by
; inserting a tilde ("~") in the source text file, to halt CONOUT until
; the reader strikes a key.  Suggest including a tilde not less often
; than every 22nd line.
;
;	CF:  The main display functions used here, with those
;	     of the earlier versions.  No claim is made for any
;	     improvement - these simply happen to be different.
;
; Walt Wheeler, Yankee Osborne Users (YOU) 06/12/.84 and Justus Addiss,
; Sigma Xi
;---------------------------------------------------------------------
;
BDOS	EQU	5		; System call entry point
CONOUT	EQU	2		; Print string to console
DCIO	EQU	6		; Direct Console I/O, no echo to screen
CR	EQU	0DH		; Carriage return
LF	EQU	0AH		; Line feed
TILDE	EQU	07EH		; Tilde
;
;--------------------------------------------------------------------
;
	ORG	100H

START:	LXI	H,0
	DAD	SP		; Get old stack pointer
	SHLD	OLSTACK 	; Let's save it for later
	LXI	SP,STACK	; Set up a new stack pointer
	LXI	H,BUFFER	; Point to text
	CALL	COMSG
;
EXIT:	LHLD	OLSTACK 	; Get the old stack pointer back
	SPHL			; Restore it, as it has the pgm rtn adrs
	RET			; And go to the program return address
;
; Get msg pointed to by HL, test for NUL or TILDE
;
COMSG:	MOV	A,M		; Get a character
	ORA	A		; Test for match w/Nul (zero)
	RZ			; And return if it is
	CPI	TILDE		; Else test for tilde (marks page break)
	CZ	PGBRK		; If its a pgbrk marker, go to that routine
	CALL	CO		; Else spit it out to console using CO
	INX	H		; Point to next char...
	JMP	COMSG		; And loop
;
; If nor NUL OR tilde, send charlacter to CON: (screen)
;
CO:	PUSH	B		; \
	PUSH	D		; Ssave registers
	PUSH	H		; /
	MVI	C,CONOUT	; Put read funct in C register
	MOV	E,A		; Move the char in A to E
	CALL	BDOS		; Send to screen (CON: device)
	POP	H		; \
	POP	D		; Restore registers
	POP	B		; /
	RET			; and go back to calling routine
;				 ;
; If character in A is a tilde, halt output to CON: until user strikes a
; key.	Note that ^C,^S will NOT interrupt.
;
PGBRK:	PUSH B			; Save the registers
	PUSH D			; In what is partly an excess
	PUSH H			;   of caution.
	LXI	H,WMSG		; Put address of page break msg in HL
	CALL	COMSG		; Spit the "hit any key" msg out to CON:
;
WAIT:	MVI	E,0FFH		; Set the flag for DCIO, which halts till
	MVI	C,DCIO		; It gets a char from CON:, setup for BDOS 6
	CALL	BDOS		; Do it
	ORA	A		; Test for match w/00
	JZ	WAIT		; Loop
	MVI	A,0H		; Lose the char typed by user
	POP H			; Restore the registers
	POP D
	POP B
	RET			; Go back to calling routine
;
; Wait message
;
WMSG:	DB	'Hit any key to continue',CR,LF,0
;
;-----------------------------------------------------------------------
;
;   STACK AREA
;
; A portion of OLSTACK will be overwritten when this program executes.
; That is of no consqeunce, since the "Insert your text..." message is
; NOT needed at runtime.  This incidently saves some TPA.
;
OLSTACK:DB	'-->> Insert your Text between' ; Save old stack here
	DB	' the "?" and the "^@"',CR,LF	; And make room for the
;				; New stack, starting here
STACK	EQU	$		; Start of buffer marker
;
	DB	'?'
;
BUFFER	EQU	$		; Buffer used by WordStar
;
;-----------------------------------------------------------------------
; Message space starts here, and is as large as your TPA -512 bytes
;-----------------------------------------------------------------------
;
	DB	0,26		; Force a NULL and an END of file marker
				;   to keep the WordStar file clean
	END

;----------------------------- end -------------------------------------