text2g3
takes an ASCII text file (prepared by a standard text
editor such as MicroEmacs, QED, Ed, QD etc) and converts it into a G3
format file (with a QFAX header).
It is also possible to use QUILL or similar word processor to produce
formatted faxes and use underline, bold, and italics. User
defined fonts are also supported.
Text is converted using one of the QFAX fonts. text2g3
expects to find these in the default data directory, as directly defined
or in the directory described by the PATHFONT key.
The QFAX fonts include both monospaced and proportional fonts. QFAX imposes a 20mm left margin, and allows 85 characters per line (in A4) with the smaller fonts and around 42 characters per line with `qfaxbig_font'. You can define the left margin (section LEFTMARGIN keyword).
The default font (QFAX_FONT) has 256 characters, some of the control
characters print out as graphics symbols; the upper half of the
character set is an IBM character set. You can use text2g3
and qfv
or printfax
to see what this looks like by
processing the example file `Qfont_txt'. A utility is provided to
edit monospaced fonts, section Changing QFAX font.
Many of the other fonts contain less than the full ASCII character set. The qfxfnt utility currently only works with monospaced fonts. A list of fonts is supplied, section QFAX Supplied Fonts.
ex text2g3;'flp2_qfont_txt -o ram1_' ex printfax;'-o ser1hr -t eps-24 ram1_qfont_fax_001'
See the later descriptions for the parameters to the programs.
A QFAX Utility program qfxfnt
allows you to remap to
`qfax_font' and other monospaced qfax fonts to the SMS/QDOS
keyboard and design your own characters. The qfxfnt
documentation
gives examples for German and Norwegian character sets and some example
replacement characters (phone symbol and check box).
You can include a number of special commands in the text file that
instruct text2g3
to take special actions. The special actions are
flagged by a tilde "~" character at the start of the line. The tilde
commands supported by text2g3
are:
These commands ~; and ~: define comments, ~: comments are displayed on the screen.
This command may be used in a fax to define the width and page length parameters for the fax. It must occur before any text or graphics to be encoded. It may be included in the fax from a ~I(nclude) file. The code values must be in the range 0-2.
Includes the file defined by `filename'. Include files may be nested up to a depth of seven (i.e. include files may include other include files that may contain tilde command sequences (or even include files), see ~I parameter).
Chains to the file defined by `filename'. QFAX will not return to the calling text file.
~S screen_dump [position] [magnification] [invert] [square]
This command includes a SMS/QDOS screen image as a graphic in your
fax. The command assumes that the image is based on a screen width of
128 bytes (i.e. the 512 pixel width format), but does not restrict you
to a 256 line image, the program just reads 128 byte screen lines until
it hits end of file. The screen is distorted (pixels are extended
vertically), so text2g3
repeats some screen lines to give images
that are about 98% square on paper.
text2g3
will prevent you from placing graphics so they do not fit on the
page. The position value has a granularity of eight pixels.
text2g3
to ignore the position argument and centre the
image on the screen in that magnification.
Here is a SMS/QDOS screen graphic: ~S flp1_worm_scn 0 -2 It's centred and double size (also not inverted and not square so we compensate for video distortion) ~S flp2_test_scn 160 1 1 This one is starts on the text margin and is not magnified (512 pixels across), but it's inverted (assumed not square).
text2g3
employs a very simple algorithm for including
SMS/QDOS screens, any black screen pixel will be black on the
paper and other colour will be white. In you use inverse, then any black
screen pixel will be white and anything else will be black. An example
is supplied, `worm_scn'. I suggest you display this on the monitor
lbytes worm_scn, hex("20000") : REMark on a QL
then print it out using text2g3
and printfax
to see
the differences. (It's included as `eg_test_fax').
Note that the solid red and green areas are white on paper, but the
stipples used to shade the `mountains' are reproduced as a grey pattern
they mix black and a colour. If you want stippled patterns in the fax,
then use black/colour stipple patterns on the screen. I found
`worm_scn' on an old disk somewhere; it's a good example, I
hope I have not offended the copyright holder.
The QFAX utility program fsPIC
will dither PIC images to give
a simulated grey scale. The pbm
images produced by this program
may be included in faxes using text2g3
and give much more
detailed images. Try it on the worm image and see.
~Q PIC_Image [position] [magnification] [invert] [square]
This option allows the inclusion of graphics in the PIC format. This format has a header to the screen image that defines the x and y pixel dimensions of the image. QFAX does not restrict such images to the any given size, and the image does not have to be a standard screen size. The header format is described in the QPTR manual. The QFAX package includes four such images, (PIC format). They have been converted from other (PD) sources and are square, so they can be used as follows:
~Q HeadTms_pic 0 -1 0 1 @l{The} "Facsimile Message" @l{graphic in} Times-Roman @l{font.} ~Q HeadHlv_pic 0 -1 0 1 The @l{"Facsimile Message"} graphic in @l{Helvetica} font. ~Q QFax1_pic 0 -1 0 1 The QFAX logo on one line (note this is about 1400 pixels across). ~Q QFax2_pic 0 -1 0 1 The QFAX logo on two lines.
The worm_pic graphic is the worm_scn graphic in PIC format, it has graphic distortion (i.e. non-square pixels) so it does not have the 'square' argument.
~Q worm_pic 160 2
~q PIC_Image [position] [magnification] [invert] [square] ~s SCN_Image [position] [magnification] [invert] [square]
These additional commands allow you to overlay text and graphics in the same horizontal area. By combining the position parameter and spaces in the text, it is possible to surround a graphic with text. The example files `test_txt' and `test_fax' show the results that can be obtained using these commands. It isn't desktop publishing, but the results are quite good. When calculating screen positions, use the following sizes for the default qfax_font:
Character width = 17 pixels (inc char spacing) Character height = 34 pixels (inc line spacing)
The graphic features may allow you to create (semi-)professional looking faxes without access to DTP programs.
~b pbm_file [position] ~B pbm_file [position]
It is also possible to include bitmaps in pbm
(Portable Bitmap)
format. QFAX/text2g3
supports the raw
, P4, (that is
monochrome binary variation) of pbm
. This is included as a aid to
importing black and white graphics that have been generated from
external sources without the trouble of using native screen formats with
the inherent overhead of extra size and video scaling. An example of an
external source might be a utility to convert Epson printer dumps to
pbm
. The ~B command inserts and ~b command overlays.
The example `test_txt' has been changed from QFAX v1.5 to
include a pbm
file. Note that this image is half the size of the
PIC format `frog_pic' in earlier versions.
~b frog_pbm 560 ; overlay frog
text2g3 can automatically include the current date in the body of a fax. The flags are ~d and ~D, formatted as:
So, if today is 27th September, for the two flags, the results would be:
~d 27 September 1994 ~D Tuesday, 27 September 1994
QFAX allows you to define the textual names for the months and days
in a `qfax_dat', so, a non-English user does not have to have
English dates in a native language fax. The `qfax_dat' key words
are MONTHS
and DAYS
. The equivalents supplied for these
keywords are a comma separated list. Do not surround the text with
quotation marks.
For example, to use three character month and day names:
MONTHS = Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec DAYS = Sun,Mon,Tue,Wed,Thu,Fri,Sat DAYS=dimanche,lundi,mardi,mecredi,jeudi,vendredi,samedi
text2g3 supports bold, underline and italic by the following ~ switches that may appear anywhere on a line. A tilde "~" may be included by specifying it twice "~~". The commands are :
~O had previously been used an alternative code for Overlay PIC format graphic. The ONLY codes for PIC graphics now are:
~Q parameters : Insert PIC graphic ~q parameters : Overlay PIC graphic
Example QUILL / XCHANGE files are included in the archive as `quillfax_doc' and `quillfax_txt'. The example (XCHANGE) print driver is `xchange_dat_qfax'.
The `xchange_dat_qfax' file was constructed using the following criteria:
The output device is set to alternate (none). Lines/page are set to 60 (this depends on your use of graphics in the fax). Char/line is set to 82 Continuous forms set to Yes EOL set to LF Emphasis On ~E Emphasis Off ~e Underline On ~U Underline Off ~u SubScript On ~O ) for Italics SubScript Off ~o )
In QUILL, use Design to set the top and bottom margins to a suitable value (zero), and set the left and indent margins to zero and the right margin to 80. The footer was set to none. The interaction between page size in QUILL, page length in the driver and what you actually get depends on your usage of graphics in the fax, which QUILL does not know about.
For output, F3 P(rint) to a file, and use text2g3
to process
the file into a fax.
This method should work with any word processor that allows you to define escape sequences for bold, underline etc. You can add additional features using the 'user defined font' feature. If you wish to generate flush right margin faxes, you now have a means to do so.
QFAX/text2g3
supports user defined fonts. Fonts must be
conform to the QFAX font format specification.
text2g3
allows any number of fonts in a document. These fonts are
referred to below as font0
to font9
. If you do not define
any fonts, then font0 is defined by text2g3
as the normal
`qfax_font' font. It is recommended that font 0 is a monospaced font
of similar dimensions to qfax_dat in order to maintain the format of the
fax header inserted by text2g3.
A font is defined for subsequent use using ~F, with parameters of font file and font number. So given font0 is the standard QFAX font, we could define font1 and font99 as:
~F flp2_afont_font 1 ~F flp2_bfont_font 99
where the files `flp2_afont_font' and `flp2_bfont_font' are user defined font files. We can then use these fonts in a fax using the ~N notation, where N is the font number (for example) ~1 switches to font1. ~0 switches to the default font (`qfax_font' if you haven't redefined it).
~F flp2_afont_font 1 ~F flp2_bfont_font 99 This is an example of ~1font one~0 and ~99font two~0. OK ??
=> This is an example of font one and @l{font two}. OK ??
The text would start in the normal font, the phrase font one
is
encoded using the font from the file `flp2_afont_font', the `
and ' is back in the `qfax_font', and phrase font two
is
encoded using the font from the file `flp2_bfont_font', and the
last part is back in `qfax_font'. The fax header is always in
font 0, usually the `qfax_font' default, but you can define
your own default font if you want, either using FONT =
in
`QFAX_DAT', -f on the text2g3
command line or ~F
filename 0 in a text file.
The Bold, Underline and Italic commands may be applied to user defined fonts.
The ~number command to indicate a change of font is terminated by the first non-numeric character. If you want to change the font and then print a numeric character immediately, then you can put a exclamation mark after the number. This is ignored.
~12!1234567890 (change to font 12, output "1234567890") ~13!!He exclaimed (change to font 13, output "!He exclaimed")
Font numbering does not have to be sequential.
text2g3
supports up to 16 user defined macros. This means you
can, for example, prepare a text file with macro markers in it, then,
using a macro file, send the same file to a number of respondents, each
one personally addressed.
The macros are indicated in the text file using ~mN where N is a
hexadecimal digit in the range (0 - f), for example, ~m0 ~m9 ~ma
~mf.
The macro expansions are defined in another file, in the format
N:text
; where N is the macro number and text is the macro
text. You pass the name of the macro file to text2g3
with the
-m flag.
So, to put this all together:
=> In the text file: To: ~m0 Dear ~m1, ... ~m3, ~m2 => in a file macros_bc 0:Bill Clinton 1:Mr President 2:Jonathan Hudson 3:Yours faithfully then ex text2g3;'-m macros_bc test_txt' => In the fax To: Bill Clinton Dear Mr President, ... Yours faithfully, Jonathan Hudson => in a second macros_gg file 0:Graham Goodwin, Fur~EST~e Ltd. 1:Graham 2:Jonathan 3:Best Regards then ex text2g3;'-m macros_gg test_txt' => In the fax To: Graham Goodwin, FurST Limited (note ST in BOLD) Dear Graham, ... Best Regards, Jonathan
A macro may contain a reference to a macro (which may contain ... etc), see section Recursion.
0:this is a macro 1:Also, ~m0 as well
Then, in a fax, ~m1 will expand to "Also, this is a macro as well".
A macro may contain references to other formatting (~) commands, including those that are only recognised at the start of a line, such as ~Q to include graphics. Where such a reference is made, then the reference must be at the start of the line.
0:~Q mysignature_pic 160 1 1 1
then ~m0 at the start of a line, will cause the graphic to be included.
In the above example, I could have had a fifth macro, ~m4, defined in
macros_bc as 4:~Q jrhsig_pic
, which a formal signature
("Jonathan Hudson"), while in macros_gg, 4:~Q jsig_pic
, which
is an informal "Jonathan".
Two BASIC example programs are provided to further illustrate the
usage of text2g3
macros. The files are `demofax_bas' and
`demofax1_bas'. These examples are very similar, they take a text
file, `demofax_txt' and write out a personalised fax message to a
number of people, which is then sent using qfax
.
`demofax_bas' uses the qfaxServer
mode and can retry on
busy, `demofax1_bas' runs a standalone qfax
for each fax and
will break the BASIC program on error.
In the example, the data is taken from DATA statements in the program; a more practical example might read an EXPORT file from Archive, or data extracted by some means obvious to users of DataDesign or DBAS.
Note that the examples may generate quite a long command line.
text2g3
can include existing fax files in a fax. A special case
of "~X" without a filename instructs text2g3 to finishing processing.
This can be used to prevent extraneous blank lines from being included
after including an old fax file. Included fax files start on a new page,
and any new material after an included fax file will also start a new
page. text2g3 headers will not be added to included pages, for various
technical reasons (i.e. it's difficult).
Included fax do not need to be of the same coding, resolution or length as the new fax.
given the existing files demo1_fax demo2_fax if the file new_txt contains ~X demo1_fax ~X demo2_fax ~X Never gets here then 'ex text2g3;"new_txt"'
will create a fax file 'new_fax' that incorporates the existing fax files demo1_fax and demo2_fax.
if the file newer_txt contains Let's go. ... This is a fax file. This is the first page ~X new_fax This is a fax file. This is the last page ... The end then 'ex text2g3;"newer_txt"' will create a fax file 'newer_fax'.
The file "newer_fax" will contain an initial page from the text starting "Let's go", then the included pages of the existing fax "new_fax" (itself made from the old "demo1_fax" and "demo2_fax" files), then a final page ending "The end". The page starting "Let's go" will have a new headline with the current time/date (and P.001/002), the final page will also have the the current time/date (and P.002/002). Included files retain their original header line.
Included pages will have the bit order of the current coding environment.
QFAX includes an example in both text and QFAX G3 format
`test_txt', `test_fax'). You can display or print the
`test_fax' file using qfv
or printfax
You can create
`test_fax' from `test_txt' using text2g3
. Note that the
fax image has been created in low res `-r0' to minimise the archive
size.
ex text2g3;'[-f fontfile] [-v] [-x] [-r res] [-o outdir] [-2] [-w N] [-h N] [-l N] [-m macrofile] [-u stemname] [-a name] [-M] file1 ... fileN'
where:
-f
-v
-x
-o
-r
-u
ex text2g3;`-m macro_fred -u fred faxmerge_txt'
=> fred_fax_001
ex text2g3;`-m macro_bill -u bill faxmerge_txt'
=> bill_fax_001
-m
-2
-w
-h
-l
-a
-M
file1 ... fileN defines the files to process, wildcards are supported. for example:
ex text2g3;`-r 0 -f flp1_qfax_font -o ram3_G3_ flp2_*_txt'
The output file has the extension `_fax'.
ex text2g3;`-r 0 -o ram3_G3_ flp2_test_txt'
gives a files ram3_G3_test_fax
.
text2g3
includes a header on the top line of each page giving the
SIGNATURE and ID fields from your `qfax_dat' file and a time
stamp. This is a legal requirement is some countries (i.e. USA). Other
encoding programs (for example the gs
fax driver) may not do
this. This line is of the form
Jonathan Hudson +968-699407 19/01/94 19:05 P. 001/001 SIGNATURE ID TIME STAMP Page counts
The T2G3INI keyword in the `qfax_dat' file can preset command arguments for text2g3, for example, if you always wanted immediate exit (no Press any key message, and an output directory of, say, `win1_fax_output_', then you might use:
T2G3INI = -x -o win1_fax_output_