Go to the first, previous, next, last section, table of contents.

Using text2g3

text2g3 Overview

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.

QFAX font

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.

Changing QFAX font

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

text2g3 formatting

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.

~# width_code page_code

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.

~P

Start a new page.

~I filename

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

~C filename

Chains to the file defined by `filename'. QFAX will not return to the calling text file.

~S screen_dump

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

position
Defines a offset from the left edge of the page in G3 pixel units (note left text margin is offset by ten characters which is 160 pixel units, the G3 page widths are show in section Fax Page Sizes. text2g3 will prevent you from placing graphics so they do not fit on the page. The position value has a granularity of eight pixels.
magnification
May take values of 1,2,3 and is a linear magnification of the image. If the magnification is negative, then it has special significance. This tells text2g3 to ignore the position argument and centre the image on the screen in that magnification.
invert
Makes a negative image. Zero means do not invert, any other value means invert.
square
Ignores the aspect ratio and copies the image verbatim. Zero means compensate for video distortion, any other value signifies the original image is square (4).
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.

fsPIC dithering options

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

~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 & ~s Image

~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 & ~b pbm_file

~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

~d, ~D Date Formatting

text2g3 can automatically include the current date in the body of a fax. The flags are ~d and ~D, formatted as:

~d
day month year
~D
weekday, day month year

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 :

~E
Emphasis (Bold) on
~e
Emphasis (Bold) off
~U
Underline on
~u
Underline off
~O
Oblique (Italics) on
~o
Oblique (Italics) on

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

~F & ~0 ... ~9 User defined Fonts

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.

~m Macros

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

Recursion

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

Example Macro Files

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.

~X Include Fax

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.

Other text2g3 Examples

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.

Running text2g3

text2g3 is invoked as:

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
defines an alternative font file
-v
invokes verbose mode
-x
suppresses the c68 `Any key to exit' message
-o
defines a device /directory for the G3 file. The default is `ram2_'.
-r
defines the resolution, 0 for normal low res, 1 for fine high If you don't give this parameter, the value from `qfax_dat' is used.
-u
defines the stem name for the output file.

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
defines a macro file
-2
use 2-D encoding.
-w
defines the width (as CCITT code 0,1,2).
-h
defines the width (as CCITT code 0,1,2).
-l
defines the left margin in fax pixels.
-a
Checks the name in QFAX_PHONE for encoding method (1 or 2D).
-M
By default, text2g3 produces lsb format files (the default for Class 2 modems), -M forces MSB files.

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

T2G3INI

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_

Go to the first, previous, next, last section, table of contents.