For a brief overview See
hhelp.
Contents
1.1 What is "htxp"?
It is a preprocessor that provides time-saving features for
writing HTML files:
by allowing the use of user-specified abbreviations, and
built-in and user-definable macros.
We assume that you are already familiar with HTML commands. If not,
some good places to start are
1.2 How does "htxp" work?
You write a raw or source file (say, its name is
"file") that is essentially an ordinary HTML file
with (optional) abbreviations and macros replacing long
strings and commands, (you can also modify an
existing regular HTML file) and then use "htxp" to expand it.
There are three types of shorthand.
- Abbreviations. Words, phrases,
and long strings of ascii (such as file
names, directory names, or parts of them)
that occur more than a couple of times in one
or more documents can be given abbreivated codes.
For example, it is much faster to type
";ab" than
"abbreviation", ";fe" than "for example", or
"$h" than "//www.mcs.anl.gov/home/kwong".
These abbreviations are defined, in specified files, by the user.
- Common HTML commands have shorter built-in "htxp" equivalents, such as
instead of
and
.ah $h/linked_file See "linked_file" for details.
instead of
- User Macros. They work very much like
the built-in commands above, but they are defined by the user.
With ingenuity, one can construct some rather complicated
and useful macros. For example, the "Tips" environment used below
and the "Example" environment used in Section 3.4 are generated
by the pairs of macros "]tp", "]Tp", and "]xp", "]Xp", respectively,
without having to explicitly enter the link for the
the color bullets and the header texts every time.
As an example, the raw file for some version of part of
this subsection is shown below.
The command
will expand "file" into a regular HTML file "file.html".
TIP:If you use "vi", make an alias "vhtxp"
alias vhtxp "vi \!1; htxp \!1 > \!1.html"
Then "vhtxp file" lets you edit "file". Once you finish
editing, "file.html" will be automatically generated.
An additional argument "-" after the file name expands
only the abbreviations, not the macro commands.
To use the
help utility,
issue the command
1.4 Do I want to go on?
Does that Mean I Have to Learn More Commands?
- You make your own macros (]cm, ]tp, etc.) and abbreviations
(;H, ;cm, $h, etc.), so you do not have to learn them.
- "htxp" commands, macros, and abbreviations are independent of each other
and are optional. Use only the ones you know or remember.
- Start with abbreviation and gradually build up your repertoire.
Won't Too Many Macros Make the Document Cryptic?
You use the macros for enetering text
(IT SAVES TIME), but, if you prefer, you can read or
show others the expanded files.
Once you've gotten the hang of it, you will probably agree
that the raw files are, in many cases, no more cryptic than the
corresponding HTML files.
What if a Command Does Not Work As Claimed?
Maybe you do not understand the instructions correctly.
Maybe there is a bug in the program.
In any case, simply stop using the command and revert back to the
regular HTML commands.
Very few "htxp" commands are mandatory.
I Didn't Use Any htxp Commands, But Funny Things Still Happen!
The text must have contained, inadvertently, some
"htxp" commands. See 2.2 for ways to suppress expansion.
Benefits
- Abbreviations really can save you time
and can reduce the chance of typos.
- "htxp" abbreviations can also be used for non-HTML text processing.
- You can make your own environments with user macros.
(For example, all the "TIP: "
in this document are speified simply by the pair "]tp" and "]Tp".)
To change the
appearance of the environment, you simply change the definition of the
macros (instead of having to make changes at every occurrence of
the commands).
- Macros can make the document easier to read by reducing
long chains of commands. You can use the "htxp file -"
option to expansion the abbreviations and retain the macros.
1.4 Installation
If you work at MCS, Argonne, the commands "magicxp"
and "hhelp" are already
available in /usr/local/bin.
If not, obtain the C source files
magicxp.c,
hhelp.c,
html.hlp,
and
magicxp.h
and compile them with "cc magicxp.c -o magicxp"
and "cc hhelp.c -o hhelp"
(in a UNIX environment, or with "gcc").
[ If you use a PC, a standard C compiler works
(I have tried turbo C), but
the sizes of the variable arrays (for storing the abbreviation
and commands) need to be greatly reduced
(I have not had the time to find out the optimal sizes)
or else the program must be rewritten to economize on memory
usage. Help appreciated. ]
The code may be modified from time to time for improvement or
for bug removal. You should update your copy of the code
accordingly -- check the date of last revision in the code.
Pick a directory where you will place your user-specified files
("html.rc" or "html.ab1", "html.ab2", and "html.ucm")
and the help file "html.hlp"
(if you have not obtained this file yet, get it by clicking the
name that appears at the beginning of the section),
and create the aliases (if you
use a shell similar to "csh") [ create batch files "htxp.bat"
and "hthlp.bat" in DOS ]
alias htxp magicxp DIR/html.
alias hthlp hhelp DIR/html.
IMPORTANT:
The period . is part of the command.
The parent command "magicxp" (of "htxp") is a general-purpose
macro tool.
Preprocessors for writing other moderately complex document formats
can be easily created by modifying the underlying
"built-in command macro database" that appears in the second half
of "magicxp.h".
1.5 Disclaimers
Use the program at your own risk.
- It is a good practice to
use "htxp" in a directory free from other important files
(or else back them up first) until you know what you are
doing.
An example of a potential disaster:
if you use a derived command
such as "vhtxp" (in Section 1.3) to automatically generate a file
"file.html" from the file "file", and a file with the name
"file.html" already exists, it will be wiped out.
- Writing programs such as "htxp" is only my hobby, not my main
line of research.
My research interest
involves differential equations,
wavelets, signal and image processing, applied
mathematics, and linear algebra.
I have developed this program and made sure that it worked
because I find it extremely useful to me. But
I do not have the time (nor the patience, nor the expertise)
to optimize and to perfect the code.
- The code contains minimal
documentation and is far from being clean (it has been adapted
from codes of previous and more complicated projects in
a short time; there are bound to be superfluous
variables and code segments here and there). Also, experts in
compiler and preprocessor design will probably find
the code most unconventional. I will not be surprised
to find that there
are ways to overhaul
the code to produce a much more powerful and efficient
program. Any help in these directions will be appreciated.
Mathematics and Computer Science Division
Argonne National Laboratory
9700 S Cass Ave
Argonne, IL 60439