#===========================================================================
#
#
#    djscript - A text formatter for the HP DeskJet500 (tm) printer.
#  
#    Version 1.3; Copyright (C) 1993, 1994 Joerg Bullmann
#
#    This program is free software; you can redistribute it and/or modify
#    it under the terms of the GNU General Public License as published by
#    the Free Software Foundation; either version 2 of the License, or
#    (at your option) any later version.
#
#    This program is distributed in the hope that it will be useful,
#    but WITHOUT ANY WARRANTY; without even the implied warranty of
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#    GNU General Public License for more details.
#
#    You should have received a copy of the GNU General Public License
#    along with this program; if not, write to the Free Software
#    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#
#
#===========================================================================

CONTENTS
========

  PART I   - Introduction
  PART II  - Preliminaries
  PART III - Choosing the different modes of the DJ500
  PART IV  - Additional features
  PART V   - Examples
  PART VI  - Compiling and installing
  PART VII - Bugs, Inconveniences, ToDo

PART I - Introduction
=====================

This package is released under GNU General Public License, but
it is not supported by the FSF (and I don't expect that it ever
will be).

Several people contacted me, suggested new faetures and described
bugs. Thanks to all of them.

The tool's purpose is to make better use of the HP DeskJet 500's
text modes. On one hand djscript enables the user to easily choose
the different text modes of the DJ500. On the other hand there are
some add-ons supposed to make some if these modes really useful.  

In detail that is:

  Use mono spaced fonts Courier and Letter Gothic.
  Use proportional spaced font CG Times (restricted).
  Use half width/height fonts.
  Select horizontal and vertical character spacing factors.
  Use italics font.
  Use landscape print mode.
  Select paper size and margins.
  Select character set.
  Switch from draft to letter quality printing.
  Produce multiple column output.
  Have many small logical pages on one physical page.
  Interpret Ctrl-L as formfeed and Ctrl-H as backspace.
  Logical/physical pagebreaks between files.
  Print selected pages of a file.

New since version 1.3:

  Optionally ignore Ctrl-L.
  Optionally draw horizontal and vertical lines
    between logical pages.

PART II - Preliminaries
=======================

Where djscript's output goes
============================

  djscript writes its output directly onto /dev/lp1 by default. To redirect
  djscript's output use option `-P<filename>' where <filename> is the name
  of the file to be printed to. Remember that any old contents of <filename>
  will be overwritten and thus lost. To make djscript write it's output to
  the standard output stream, use `-P-'.

  Using option `-P:<cmd>' pipes djscript's output into the command <cmd>.
  This is equivalent to `-P- | <cmd>'.

  Currently there are no features in djscript that allow connecting to a
  printer daemon like `lpd'. If it turns out that this is a severe drawback
  it has to be fixed. But I read about filter scripts in NEWS that several
  people use in connection with their customized printcap entries. I guess
  that it is no major problem to call djscript from somwhere there and pipe
  its output to the appropriate tools and thus to achieve the wanted.

  Examples:
	djscript file1
	djscript -Pprintfile file2
	djscript -P- file3 | cat /dev/lp1
	djscript -P:lpr file4

Options and filenames
=====================

  djscript recognices every command line argument starting in a `-' as an
  option and interprets all options before printing the given files. Thus
  even if a filname appears left to an option in the command line the option
  takes effect for that file too. If you want to print a file the name of
  which starts in a `-' you explicitly must tell djscript that it must not
  interpret the filename to be an option but print it. You can do that
  by preceding that filename by a single `-' in the commandline.

  Examples:
	djscript - -peculiarfilename
	djscript file1 -Pprintfile file2

Short help
==========

  Starting djscript with the option `-h' shows a short description of the
  available options and defaults.

PART III - Choosing the different modes of the DJ500
====================================================

Font choice
===========

  The option `-F<fontname>' allows you to choose the different built in
  fonts of the DJ500. Currently only the standard fonts are supported.
  Soft Fonts and optional Fonts are NOT supported.
  So the choice of <fontname> is:
	courier (default, monospaced),
	lettgoth (monospaced), and
	cgtimes (proportional).

  Attention: 	The CG Times font can be used only in portrait mode with
		logical pages disabled.

		In landscape mode the standard DJ500 offers font
		Courier Normal only. 	

Font sizes
==========

  All fonts have 12 point height by default. You can switch to 6 point
  fonts using the option `-low'. The monospaced fonts retain their
  width but can be narrowed to half their normal width using option
  `-nrw'. A shortcut for the combination `-low -nrw' is `-sml'.

Italics fonts
=============

  In portrait mode the italics versions of all fonts can be selected
  via option `-itl'. 

Landscape print mode
====================

  The DJ500 allows landscape printing. Choose this using the option
  `-ls'. In landscape mode only the font Courier Normal (Non-Italics)
  is available.

  ATTENTION:	When printing in landscape mode, the DJ500 can start
		to print out a page not before he knows that the page
		is full. So in worst case, the whole page is in the
		DJ500's builtin buffer, when the printing begins.
		When working with small fonts (option `-sml' above),
		on a landscape page fit up to 266 columns by 96 lines
		which makes exactly 25536 bytes of data. As the DJ500
		has only 16K builtin buffer, there seems to be some
		difficulty, if pages are nearly full.
		As I discovered, the DJ500 is safe about that: when
		the buffer gets too full, the printer prints the page
		with double line spacing. Still, sometimes the printer
		enters `error status' and must be switched off and on.
		(Mistakes in this calculation? Clues are welcome!)

Select paper size
=================

  The DJ500 supports several paper sizes: here the sizes DIN A4, US Legal,
  and US Letter are supported. They are selected by option `-S<size>'
  where <size> is one of dina4, uslegal, or usletter. To see the exact
  character resolution of a specific paper size - font - point size -
  spacing factor combination use option `-sg'.

Select spacing factors
======================

  Using the commandline option `-sf[hv]F' you can set horizontal/vertical
  character spacing factors. The factor F is a positive floating number.
  If the option is given, a single character takes F units of horizontal/
  vertical space (instead of 1 unit without the option). The number
  of columns/lines that fit on a physical page is thus divided by F.

  Examples:
	djscript -sfv1.5 file_n (produces a line distance of 1.5 times the
				 height of the current character set)
	djscript -sfh1.1 file_m (yields a horizontal character distance of
				 110% of the current character set's width)

Set margins
===========

  Margins on left/right/top/bottom of physical pages can be given using
  option `-m[lrtb]M' where M gives the margin in multiples of the
  selected character size. The upper left corner of the page has text
  coordinates (0, 0). Right and bottom margins are measured from the left
  respective top when they are positive numbers. When they are negative
  numbers, the are measured from the right or bottom. Left and top margins
  are always measured from the left/top.

  Examples:
	djscript -Fcourier -mr-5 file1     \ These two margin specs are
	djscript -Fcourier -mr75 file2     / equivalent if output is 80
					     columns wide (Font courier).
	djscript -mt5 -ml-4 file3

Select character sets
=====================

  The DJ500 supports a wide variety of builtin character sets. Some
  of them can be selected using the commend line option `-C<charset>'.
  Here <charset> is one out of:

	ascii	: ANSI ASCII character set
	ansi	:          -"-
	ecma    : ECMA-94 Latin 1
	pc8	: PC-8
	pc850	: PC-850
	hpr8	: HP Roman 8
	hpl	: HP Legal

Letter quality output
=====================

  To invoke letter quality output use option `-lq'.

PART IV - Additional features
=============================

Multicolumn output
==================

  Using small fonts makes sense only when you can use the resulting long
  lines. The option `-cnX' allows you to produce output of X text columns
  which are grouped side by side. The text columns are separated by one
  space character each. The text column width is computed as large as
  possible.
  Option `-cwY' is used to produce text columns of at least Y characters
  width each. These too are separated by a single space character. Here
  the number of text columns is computed from page width and text column
  width.

  Examples:
	djscript -sml -cn2 hiho.C
	djscript -ls -sml -cn3 tables
	djscript -sml -cw46 results

Logical pages
=============

  The logical page height defaults to the physical page height. It can be
  reduced with the option `-lphN' where N is the new logical page height.
  If the logical page height is so small that more than one logical pages
  fit in height on one physical page, there are printed as much logical
  pages above on another as possible. In that case they are separated by
  single blank lines.

  When printing in small fonts and portrait mode there fit 2 by 2 logical
  pages (of 79 characters by 66 lines each) on one physical page when using
  DIN A4 or US Legal paper. Therefore we have the shortcut option `-7966'
  which is equivalent to `-cw79 -lph66'. This geometry seems to be useful
  to print manpages (in rare cases the width of 79 characters is exceeded).

  Examples:
	djscript -sml -cn2 -lph40 anyones_file
	man rcsintro | djscript -sml -lq -7966

Separation of logical pages
===========================

  By default logical pages are separated by single blank characters in each
  direction. That's sufficient, if you e.g. print man pages for In that case
  your eye easily determines the logical pages. If it is not that clear, you
  can use option `-sp' to separate logical pages by horizontal and vertical
  lines made up by `|' and `-' characters.

Interpretation of Ctrl-H and Ctrl-L
===================================

  Formatted manpages implement underlined and bold typefaces using the
  backspace character and reprinting on the same pasition. An underlined
  L can be achieved by L<backspace>_ or a bold B can be done by
  B<backspace>B. Backspace characters are handled by djscript so that
  underlined and/or bold text should be no problem.

  The Ctrl-L character is used to produce page breaks in the text. djscript
  switches to the next logical page upon encounter of a Ctrl-L.

  Option `-il' lets djscript ignore the Ctrl-L characters it finds
  in it's input.

Inter-file-pagebreaks
=====================

  When prining more than one file at once djscript offers the choice of
  taking a new sheet of paper for each file or switching to the next logical
  page and start printing the next file there. The latter behaviour is default.
  Use option `-pp' to have each file starting on its own sheet of paper
  (physical page). 

Print selected pages of a file
==============================

  If you do not want to print a whole file but only some of its pages, you
  can tell djscript about that using the pagerange option `-prR' where R
  denotes the logical pages that are to be printed. R consists of a comma
  separated list of page specifications like i, -i, i-j, i-. i and j denote
  logical page numbers here. Logical page numbers start with 1.

  Examples:
	djscript -pr13 funfile
	djscript -pr1,7,12-18 myfile
	djscript -pr-5,30-,11-16 herfile

PART V - Examples
=================

Print listings
==============

  To print out program listings I consider convenient the following
  combination of options:

		djscript -sml -cn2 file1

  Thus you have two text columns of 79 character columns and more than 130
  lines (the exact number depends on chosen paper size) each. This gives you
  an extraordinary overview even of larger procedures. Besides you use up
  only a quarter of paper in comparison to normal printing.
 
Print manpages
==============

  Sometimes it is useful to have printouts of manpages. The options

		djscript -sml -7966 

  produce output of 4 logical pages on one physical page when you use paper
  size DIN A4 or US Legal. Most of the manpages I tried out fit in the raster
  perfectly. If the manpages to print are too wide for this, try

		djscript -sml -cn2 -Flettgoth -lph66

  which uses the narrower font Letter Gothic instead of the standard font
  Courier.

PART VI - Compiling and installing
==================================

  To compile your favourite defaults for paper size, font, and output file
  name into djscript, set the make-variable DEFAULTS to the appropriate
  value. See in the makefile. Should be self explanatory.

  To install djscript in the place you like, adjust the make-variable
  PATH_PREFIX.

PART VII - Bugs, Inconveniences, ToDo
=====================================

  Standard options could be read from an environment variable.

  Currently page headings are not supported.

  There's no manpage yet. Still, the Makefile is already prepared ;-)

  The 16 1/6 cpi courier character size is not supported yet.

  Double sided output.

  Landscape printing is a problem: in DJ500/DJ510 the printer buffer is too
  small to hold a full printed page when small fonts are used. So these
  printers refuse to work, if the printing data is `inappropriate'.
  Besides the DJ500 here really takes his time to figure out how to print
  things. Sometimes it even goes into error state: all LEDs on the contol
  panel are blinking synchronously.
  Switch it off and on again in such a case.

===============================

Bug reports, ideas, suggestions, etc. are welcome.
   (and postcards! remember the NEWS discussion?)

Joerg Bullmann
Klosterweg 28, O-205
76131 Karlsruhe
Germany

(bullmann@fzi.de)