The htm1-pp processor expands macros found in .htm1
-files
and produces a corresponding .html
-file.
(it accepts .HTM1
as well).
The possible macros
are not restricted to those predefined - you can even define
your own macros in the actual .htm1
-sourcefile.
The syntax is modelled as to be able to directly feed plain rfc822 internet-mail messages to htm1-pp . The predefined functionality in htm1-pp will try to produce a nice result, or really, to arrive at a nice result without much changes in that e-mail for you.
The htm1-pp perl-based processor has served me very well in the
past months (so I hope to got rid of major bugs). At the time of
writing, I am always using htm1-pp to create html-documents -
even this html-document has an
accompanying .htm1
-file
(index.htm1) that it was built from.
Use `htm1-pp index.htm1'
`index.html'
`index.htm1'
If you are often using a Makefile, you may want to include
the following:
.SUFFIXES .html |
`make'
.htm1
-files
into their corresponding .html
-files.
A htm1
-tag does always end with a single colon, optionally followed
by subtag arguments in round parentheses.
The start of a tag is marked by
htm1
-text - more on this later).
b: this text is in bold face and this is not |
this text is in bold face and this is not |
{b: all this text will be set in bold face } but not this |
all this text will be set in bold face but not this |
You are free to embed arbitrary html-tags as long as the first
opening angle starts at the beginning of a line. The actual source
code for the table above looks like this
<table border=1 width=80%> ===:(top) {td-code: {b\: all this text will be set in bold face } but not this } ---: {b: all this text will be set in bold face } but not this </table> |
`b:'
Here should be a list full of pointers to pages telling you about the predefined macros. As you can see, most these aren't working. Alas, you are free to look at the source code that is containd in:
htm1
-sources just as seen there. Take this file as a good
example on possibilities of defining (mostly) simple htm1
-tags.
`content-table:'
Check out these documents...
The macro names you can choose must match the regular expressions
'[\w\+\-][\w\+\-\#]+'
for about any tag or
'[\w\+\-\=\*][\w\+\-\#\=]+'
for line-only tags.
In normal words: you can choose any alphanumeric name plus '+' and '-'. Line-only tags may also contain '=' and they may also start with one '*'. Besides used as the first letter, the names may also contain '#'.
Usually html-tags must be written with an opening html-tag, the
enclosed text, and a closing html-tag (written like "</end>"). You
can declare those with `html-tag2:'
Some html-tags are not used with a closing tag, e.g. the horizontal
ruler <hr>, or the <img>-tag. That's what the `html-tag1:'
Most of the simple html-tags should be predefined, but sometimes
you get warnings about `unknown tag {blockquote:...}'
`html-def2: blockquote "blockquote"'
`redefining blockquote'
`x-*'
`x-html-def2: blockquote "blockquote"'
Note that `html-tag2:'
`html-tag2: blue "font color=blue"'
`<font color=blue>...</font>'
The `html-def'
`html-tag2:'
htm1
-tag is replace directly with the text.
Yet, there's some magic in html-def too. When expanding the definition,
you can access the values of variables. They should look like
`$(name)'
`$(*)'
`$(.)'
htm1
-tag use.
(`$()'
`$(*)'
What are variables? Well actually, the name is a little misleading.
It is simply a storage of the values of the last expansions. An explicit
variable usage is (currently) called `put:'
`{put:h2}'
`x-*'
So in fact, I am often using `{put:title}'
`{put:From}'
`{x-bgcolor: #FFFFE0}'
`html-def:'
`$(From)'
using `{put:From}'
`html-def:'
`html-def'
Functions are not defined in a ht1-file, instead you include them
in a perl-inclusion file a.k.a. pl1-file. The perl argument
is simply the current enclosement (`$(*)'
`&getArgs()'
`return "<table".getArgs().">".@_."</table>";'
Just look into the predefined functions to learn some of the tricks.
On compiling your .htm1
source files into .html
files you will
notice a bunch of files being pre-loaded for you. Here's the order:
get | `/usr/etc/htm1-pp.ht#' |
and | `/usr/etc/htm1-pp.pl#' |
get | `/usr/html/etc/htm1-pp.ht#' |
and | `/usr/html/etc/htm1-pp.pl#' |
get | `~/etc/htm1-pp.ht#' |
and | `~/etc/htm1-pp.pl#' |
get | `~/.htm1-pp.ht#' |
and | `~/.htm1-pp.pl#' |
get | `./etc/htm1-pp.ht#' |
and | `./etc/htm1-pp.pl#' |
get | `./.htm1-pp.ht#' |
and | `./.htm1-pp.pl#' |
and replace the '#'-number sign with "",1,2,3,4,5,6,7,8,9 in this
order. So you may copy some files to your project directory (or the
project's subdirectory `etc'
`bin'
`~/etc/htm1-pp.pl2'
`~/.htm1-pp.pl2'
`.pl1'
There is made a distinction between the header of a file and its body - just like in an e-mail message the header expands down to the first empty line after which the body part starts.
In the header, line-tags may actually span multiple lines - as long as the extension lines don't start at the first column and have rather a little indent-space before.
Even more unknown tags are not really warned - they are transferred
into meta-tags. So `Organization: Lucky Company'
`<meta name="Organization" value="Lucky Company"'
The value of unknown x-tags will simply be stored in the Vars-space, and no meta-tag is generated (fine for emails with X-Status tags...).
After the header-part has been fully compiled, the htm1-pp program turns to the body. When it comes to the point to spit out the text, the last body-color, link-color Var-values, etc. are being put in the corresponding sub-tags of the <body>-tag.
Other specials:
`*:'
`<li>'
`content-table-#'
`{name: named texts}'
Have fun!
`/'
`/'
`html-tag2'
`/'
`html-tag1'
`html-tag2'
`='
`{/font_color=red:some text}'
`[name:] <text> '
`html-def: name <text>'
`/'
`%'
`='
`{www.fsf.org}[@]'
` {www.fsf.org}[i] '
` {www.fsf.org}[/i] '
`text[tag:arg]'
`text[tag]'
`text[/b][/i]'
`[/i]'
The distribution file contains the files along in
their usual subdirectories `bin'
`etc'
`doc'
`tar xzvf htm1-pp.tgz'
It is very probably you have to edit `bin/htm1-pp'
`perl'
`type -p perl'
`whereis perl'
That should be it. It may get a lot nastier on non-unix systems. I am currently running it under linux, hpux and solaris, installed under my home directory.
bugs & caveats do most often have to do with functions, since those are quite special. I recommend to name all functions with an additional non-alpha-numerical character in the name, so that you'll be warned. (well, quite a few function-tags don't follow this rule yet, I'll try hard to rename them... so expect changes)
`html-def:'
htm1
-macro-tags in there, so they will expand to their definitions.
This is quite handy, but it may not do what you expect, esp. if
some of the htm1
-tags are functions. The reason is, that the embedded
tags are expanded before the definition is stored, ie. the
functions are called, may return sth. (or just fail), and the later
usage of your new tag will not call the function again. [fixed]
`\{'
`{'
.htm1
-source of this file
to see how I have written this paragraph...)
`{small:(oooohhh)}'
`small:'
htm1
-tag and the first
one of the parentheses, ie. `small: (oooh)'
htm1
-tag is
always recommended.
The package is Free Software in the notion
of Lesser GPL,
(the `GNU Library General Public License'
- and remember: faithful in the matter, but use at your own risk - the sources tell you all | |
they are your safety, warranty, compatibility, portability, and much more |
comments, bugfixes, patches or extensions - everything's wellcome.
Cool, I'm glad SmartHTML proved useful beyond its original intent :)
I like some of the ideas, e.g. using the META GENERATOR tag, the argument
abbreviation (i.e. change an argument of "100%" automatically into
width=100% sine that's where it's used most), definition of global
"variables" (e.g. $(fgcolor)) so you can easier change your color scheme.
| htm1-pp 1.2 | e-mail:guidod@gmx.de |