#===========================================================================
#
#
#    djscript - A text formatter for the HP DeskJet500 (tm) printer.
#  
#    Version 1.0; Copyright (C) 1993 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

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

This 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:

  1. Use mono spaced fonts Courier and Letter Gothic.
  2. Use proportional spaced font CG Times (restricted).
  3. Use half width/height fonts.
  4. Use italics font.
  5. Use landscape print mode.
  6. Select paper size.
  7. Switch from draft to letter quality printing.
  8. Produce multiple column output.
  9. Have many small logical pages on one physical page.
 10. Interpret Ctrl-L as formfeed and Ctrl-H as backspace.
 11. Pagebreaks between files.
 12. Print selected pages of a file.

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-'.

  Currently there are no features in djscript that allow connecting to a
  printer deamon 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- file4 | lpr

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 lansdscape 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 220 columns by 96 lines which
		makes exactly 21120 bytes of data. As the DJ500 has
		only 16K builtin buffer, there seems to be some
		difficulty. As I discovered, the DJ500 is safe about
		that: when the buffer gets too full, the printer prints
		the page with double line spacing.
		(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
  combination use option `-s'.

  ATTENTION:	The information in the User's Guide to the DeskJet 500
		(German version) on character resolutions of the
		different fonts/sizes on different paper sizes
		seems at least partially erroneous to me. E.g. by trying
		I found out that on every paper size printing in small
		font and landscape mode yields 220 columns by 96 lines.
		In the User's guide different numbers are given.
		(There could be bugs in the sequence of initialisation
		of the DJ500. Again clues are welcome.)
		   
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 also 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

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.

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
===============================

  I'm not sure that the page geometries are computed correctly in every case
  (see above the words about errors in the User's Guide).

  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 set is not supported yet.

  When printing in landscape mode, multiple column output seems not to be
  100% reliable. (could this be a DJ500 design error?) 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.

Joerg Bullmann, bullmann@fzi.de