LXRTF Version 1.1
(c) 2003 by Daniel Hertrich

Create MS-WORD compatible documents  with a simple text editor, 
anytime, anywhere!

LXRTF is a tool to create RTF files using plain text input with 
simple formatting control.

..............................................................

CONTENTS:
=========

1.  Required
2.  Usage
3.  Basic concept
4.  Formatting control in the input file (*-commands)
5.  Special Characters (\-commands)
6.  Newline handling
7.  Customization
8.  Tips and Tricks
9.  Example input files
10. Future plans / known problems
11. Support
12. Thanks
..............................................................


1. Required:
============

* SED, the stream editor, for MS-DOS     (included)
* XGREP, a Grep program for MS-DOS       (included)
* CHOICE, not part of HPLX's ROM-DOS     (included)
* A text editor of your choice       (not included)

..............................................................

2. Usage: 
=========

...is simple:
Create an input text file, for example INPUT.rtx. Then call

LXRTF.BAT INPUT.rtx OUTPUT.RTF

This creates OUTPUT.RTF, which can be directly loaded by MS WORD 
or other word processors which can read the RTF format.

The file 0refcard.txt is a reference card of LXRTF commands.
You can use it to find the needed command tag quickly, without
scrolling through this 0readme.txt file.

..............................................................


3. Basic Concept:
=================

RTF is a text-based document formatting "language", similar to
HTML, for example.
However, to write RTF documents directly is complicated and a
lot of work. Just write a few words with MS-Word and save the
file as RTF. Then open the RTF file in a text editor and have a
look at the plain RTF file. You will find very much overhead
for just the few words of text you entered into MS Word.

LXRTF reduces the overhead needed to create an RTF file
containing formatted text.

It does this by simplifying the way for input of formatted 
text and then converting the simple input to more 
complicated RTF format. This process is called "compiling".

This compiling is mainly done by replacing simple commands with
RTF commands. 

..............................................................


4. Formatting control in the input file (*-commands):
=====================================================

You can convert almost any plain text file to RTF using LXRTF. 
Text formatting (paragraphs, line breaks, empty lines, spaces) 
will be kept. However, there may be sequences of characters which
are interpreted by LXRTF as formatting tags. See below. If
that's the case, you'll have to edit the text file a little.

If you want to take control over additional format settings like
font, font size, aligning etc., use formatting tags in the input file.
Each formatting tag consists of an asterisk (*), followed by a 
character. Some tags need a numerical parameter.
The tags are CASE SENSITIVE!

Following formatting is done with a start and end tag:


Format        Start tag      End tag
-------------------------------------
Bold          *B             *b
Italic        *I             *i
Underlined    *U             *u


Following formatting commands require only one command (and another one
with the old value to restore the old setting):

Format           Tag
----------------------

Font:

  Font           *Fn     (n being a number corresponding to a font in the
                         font table in the header.rth file:
                          *F0 is the default font of your text processor
                          *F1 is Courier New     (fixed-pitch, default font)
                          *F2 is Times New Roman (proportional, serif)
                          *F3 is Arial           (proportional, sans serif) 
                          *F4 is Verdana         (fixed-pitch)  
                          *F5 is Garamond        (proportional)
                          *F6 is Symbol          (proportional Greek characters)
                         More fonts can be added by editing the header.rth file)

  Font size      *Snn    (nn being a number denoting the font size in 
                          half points, i.e. 
                            *S20 is 10pt (default),
                            *S24 is 12pt etc.)

  Font color     *On     (n being a number corresponding to the font table in 
                         the header.rth file:
                          *O0 is black
                          *O1 is red
                          *O2 is green
                          *O3 is blue
                          *O4 is yellow
                         More colors can be added by editing the header.rth file)


Aliging (do not use in environments!):
  
  Left           *L      (each of these control tags produces an RTF 
                          control command AND a newline!)
  Right          *R

  Centered       *C

  Justified      *J      (note: not all word processors support
                          justified text, e.g. the Write / WordPad 
                          application coming with Windows
                          doesn't!)

Other formatting commands:

  Newline        *\      (comments see below)


LXRTF supports "environments". They are embedded in a pair of
braces {,}. This provides temporary modification of the
formatting, without the need of restoring the old value
manually.
E.g., you can set the font size to 8pt for only one sentence
and the text following that sentence is written using
the old font size. This would look that way:

----
*S24
This is 12pt size. {*S16 This is written in 8pt size} This is 
written in 12pt size again.
----

Do not use aligning commands in environments, as this will cause
problems!

Thus, these braces are reserved characters, as the asterisk
is. So if you need such a brace in the output, write it with a
backslash in front of it: \{ or \}. (See section "Special
Characters").


..............................................................

5. Special Characters (\-commands):
====================================

Almost any 7bit ASCII character (the standard ASCII character
set, which is common in all codepages) can be used in the input
file and is translated to the output.
The exceptions are listed below.
High-ASCII (8-bit ASCII, i.e. ASCII values 128 to 255) are not
common in each codepage, thus, for codepage compatibility or
portability between DOS and Windows etc. high-ASCII characters
should not be used at all in the input file. 
Instead, either use the special character command as listed
below, or use the hexadecimal ASCII value, preceeded by \x, for
example \x9C for the Pound Sterling currency sign in Codepage 850.


7-bit ASCII exceptions and their LXRTF replacements:
----------------------------------------------------

*     \*
\     \\
{     \{
}     \}

(These characters are exceptions because they have a special
meaning for LXRTF)


8-bit ASCII characters supported by LXRTF:
------------------------------------------

German Umlauts:
     \a
     \A
     \o
     \O
     \u
     \U
     \s

Other characters: \xhh (hh=hex ASCII value)

..............................................................


6. Newline handling:
====================

LXRTF has two alternative ways to handle line breaks, which
follow different concepts. Different kinds of documents require
different line break concepts. Choose the one you need for your
document, based on the following explanation:

1. AUTOMATIC 1:1 FORMATTING:
   1:1 newline formatting, i.e. each line break in the input file is 
   translated to a line break in the output file. This is the default, 
   but not recommended if you write longer texts. This mode is more 
   useful when using fixed-width fonts to create column-aligned 
   formatted output (e.g. tables, ASCII drawings etc.), or when
   simply translating an ASCII text file to RTF without adding
   any additional formatting. In the latter case the result
   will (hopefully) look similar to a simple "text file import"
   of a word processor.

2. MANUAL FORMATTING:
   The newline command (*\, followed by a line break in the
   input file) can be used to generate line breaks in the 
   output. Line breaks in the input file without a leading
   newline command are ignored,
   I.e. you can write flowing text without needing to take care
   about line breaks to be at the correct position.
   This mode is used automatically, if at least one occurrence 
   of *\ is found in the input file.
   In this mode, also a blank line in the input causes LXRTF to generate 
   a newline in the output (this is similar to the behaviour of LaTeX). 
   However, unlike in LaTeX, here two empty lines in the input cause 
   a line break AND ONE empty line in the output.
   That means, the first empty line in the input is always
   converted to a newline in the output and every following
   consecutive blank line becomes also a blank line in the
   output.
   
   This mode is recommended for larger texts, because it allows to 
   write flowing text, which the RTF reading text processor will
   format following its own page / margin settings. The 1:1 mode also 
   allows flowing text, but only if one paragraph is entered as only 
   one line in the input file, which would be a pain with most
   text editors.


LXRTF creates the RTF output by first writing the RTF header
to the output file, which is stored in the file header.rth.
Then it appends the text of your input file (converted to RTF
format) and at last it appends a '}' to finish the RTF input.
The corresponding '{' is located in the header.rth file.

In the header.rth file, the default font settings are set to Courier New 
(fixed width font) and 10pt font size. This should be good for converting 
plain text files. And if you don't use the *\ command, formatting of the 
plain text file is kept 1:1 (see above). 

If you plan to write a longer text and want it to appear in a more 
beautiful, proportional font, you can simply add a line at the beginning 
of the input file, e.g.
*F2 *S24
to switch to Times New Roman 12pt.
Don't forget to use the *\ line break command at least once somewhere 
to let LXRTF know you don't want the formatting to be converted
1:1, but use the manual formatting mode!

..............................................................


7. Customization:
=================

LXRTF is controlled by a batch file, which you can easily adapt 
to your needs if necessary.
The basic tool is SED, and SEDRTF.SED is the SED command file 
which contains most of the "intelligence" (conversion from
input format to RTF). This file can also be adapted of course, 
additional control commands can be added, formatting can be 
modified etc. 
header.rth is the RTF header, which contains the font table and sets 
a default font and font size. It is already in RTF format.
The helper program addspace.exe regulates the distribution of
space characters in the RTF file. Due to the quite complicated
newline handling, and due to the space character sensitiveness
of RTF reader programs, it is necessary to add some spaces here
and there to make the output formatted correclty.
See the comments in addspace.c for details.


..............................................................


8. Tips and Tricks:
===================

* The Asterisk (*) is a special character, as it precedes all formatting 
  control commands. 
  Whereever an asterisk is used with a space or line break behind it,
  the asterisk can be used as usual (it is not recognized by LXRTF as a
  formatting command). But in some cases a plain astersik in
  the input file may lead to problems, because LXRTF thinks
  it is a formatting command. For example if you use a file
  specification like this: *BAT, LXRTF would read it as
  "Activate Bold and write AT". All following text woudl also
  be bold of course. You would need to write \*BAT instead.

* The default header.rth file sets the font to "Courier New", so spaces can 
  be used for formatting the text (don't use Tabs, as they are interpreted 
  differently by each text processor).

* If you don't need column-wise formatting using the fixed-space Courier font, 
  and if you prefer proportional (e.g. Times) font in your document, 
  set \F1 in the header.rth file to \F2. If you prefer Arial font, use \F3.
  See the font table in header.rth for all font options. The
  format of the file is easy to understand.

* Recommendation: Always use a pair of .F and .S commands at the beginning 
  of the input file to set "default" values for font and size which you 
  can always see by just going to the beginning of your input file.
  If you always only use environments for font / font size
  changes, the default value will always be restored if the
  environment ends.
  If most of the text should be written using the default font
  and only short parts should be written with different
  formatting, it's always best to use environments.

* Under http://latex2rtf.sourceforge.net/RTF-Spec-1.0.txt there is 
  the RTF 1.0 specification which you'll need if you're going to 
  add new features to LXRTF. 

* The character conversion SED script has been developed on a German HP 200LX, 
  so it may not work properly on systems using another language, codepage or 
  whatever. But you can easily add new special characters or convert the sed 
  script to another codepage.


..............................................................


9. Example input files:
=======================

There are some example input files (*.rtx).
You can use these for learning how to use LXRTF.
Call LXRTF EXAMPLE.RTX EXAMPLE.RTF and open EXAMPLE.RTF in a text
processor to see the result.

EXAMPLE.RTX uses automatic 1:1 newline formatting,
LETTER.RTX uses the manual formatting method with the newline
command *\.


..............................................................


10. Future plans / known problems:
==================================


Some problems are known (version 1.1). They MAY be solved in the next
versions of LXRTF:

* Aligning commands cause troubles when used inside environments.
  So don't do that for now.
* Aligning commands add two newline commands currently; this is 
  the only way to be sure they take effect in the RTF file.
  That means, each time chaning the aligning will cause an empty line
  in the output. In most cases not really a problem, but it is not
  the way it SHOULD work.
* In automatic formatting mode, each line of the input file is
  closed by an RTF newline command in the output, even if the input file
  only contains commands. So for example if you put an "Initialization 
  line" at the beginning of the input file, without any actual content,
  but just a font and font size command, it will be an empty line in
  in the output. 
* In manual formatting mode, a newline command only takes effect if it 
  placed at the end of a line in the input file (i.e. newline command
  plus actual newline causes a newline in the output).


These features MAY be implemented in the next versions of LXRTf.

* Support for comments in the input file (//...)
* Table support
* Support for more special characters (8-bit high ASCII characters)
* Codepage independency
* Support for simple graphical elements (lines...)
* Support for non-breakable text elements (LaTeX: "mbox"), i.e.
  putting a word / sentence / paragraph into such a "box" and
  it won't be broken up by line breaks or page breaks
* Support for TABs
* Support for manual page break
* Support for picture embedding
* Support for paragraph indentation
* Support for enumerations and lists


..............................................................


11. Support:
============

If you have questions, suggestions or enhancements, please send them to
the email address given at 
http://www.daniel-hertrich.de/contact


..............................................................


12. Thanks:
===========

...to Erwann Abalea for support with addspace.c and to Peter Eberl
and Etienne Lemaire for beta-testing LXRTF!

..............................................................


EOF