agent

README

Virtual 1403
============

https://github.com/racingmars/virtual1403

This is the Virtual 1403 Agent, which connects to Hercules to receive print
jobs from mainframe operating systems and either generates PDFs in a local
output directory, or sends the print jobs to an online service to email you
PDFs.

To use Virtual 1403, edit the config.yaml file to point to your Hercules
sockdev printer and configure choose local or online mode. If using online
mode, create and log in to your account to retrieve the correct configuration
settings for your account.

After your configuration file is correct, simply run the virtual1403
executable and print to the sockdev printer device from your mainframe.

For more information about configuring, see
https://1403.bitnet.systems/docs/setup

Printing Local Text Files
-------------------------

Instead of connecting to Hercules and processing print jobs, the agent also
supports printing local text files. These are *not* processed as Hercules
output: they are assumed to be UTF-8 encoded (compatible with US-ASCII), and
do not support carriage control features such as overstrike (we just support
standard CRLF Windows line endings or LF Unix line endings -- FF still starts
a new page). No attempt is made at job separation: the entire text file will
be converted to a single PDF file.

Local file printing uses the output configuration in config.yaml, so you may
send files to the online service or create PDFs locally.

To print local files, use:

`./agent -printfile filename.txt`

To use an output configuration other than the default, use:

`./agent -printfile filename.txt -output my-output-name`

You may also use `-` as the filename, which will cause the agent to read from
stdin:

`./agent -printfile - < filename.txt`

This could be used to combine multiple text files into one PDF, for example:

`cat file1.txt file2.txt file3.txt | ./agent -printfile -`

If your local file uses ASA carriage control characters in the first byte of
each line, you may use the `-asa` flag in conjunction with `-printfile`. In
this case, page breaks ("1"), overstrike ("+"), and multiple line skipping
("0" and "-") will be controlled by the first character of the line in the
input file. Regular lines must start with a single space character (" ").
Handling of ASCII FF is disabled in -asa mode. The ASA characters 2–9, A, B,
and C are not supported (these typically position to vertical tab stops).

Acknowledgements
----------------

virtual1403 is developed in collaboration with Moshix
(https://github.com/moshix/), and the greenbar paper design is based on photos
he provided of real 1403 printouts he has.

Includes the IBM1403 font from
<http://ibm-1401.info/Sched2008December.html#1403-Font>,
which the author(s) believe to be in the public domain or otherwise available
to embed in this application.

Font conversion notes
---------------------

If you receive error messages when trying to load your custom font, you can
try to convert it to a format supported by the PDF library using FontForge. If
you are a Linux or Mac user, ensure the fontforge command is available on your
system, and create the following script
(<http://www.stuermer.ch/blog/convert-otf-to-ttf-font-on-ubuntu.html>):


    #!/usr/bin/fontforge
    # Quick and dirty hack: converts a font to truetype (.ttf)
    Print("Opening "+$1);
    Open($1);
    Print("Saving "+$1:r+".out.ttf");
    Generate($1:r+".out.ttf");
    Quit(0);

Make the script executable (chmod +x convertfont.sh), and run it on the font
file (./convertfont.sh my-font-file.otf) to create a TrueType version that
should work.

License
-------

    Copyright 2021 Matthew R. Wilson <mwilson@mattwilson.org>

    This file is part of virtual1403
    <https://github.com/racingmars/virtual1403>.

    virtual1403 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 3 of the License, or
    (at your option) any later version.

    virtual1403 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 virtual1403. If not, see <https://www.gnu.org/licenses/>.

The source code for virtual1403 is available at:
https://github.com/racingmars/virtual1403