PRETML DOCUMENTATION
(created 00-06-09)


What is Pretml, and why?

 Pretml (which, by the way, is a very sucky name and you're welcome to suggest a better one..) is a HTML preprocessor. Yeah, I know, there's zillions of them out there, but, here's yet one more.. and, well, very beta, so maybe you should just grab something else. It would have taken me longer to find a decent HTML preprocessor that I'd enjoy than to write this anyway... It's written in another "preprocessed language"; Pyrl, but you can download the generated perl source and run that directly without using my pyrl2perl preprocessor.

Pretml can be put in 'listen mode'. It then 'listens' to all .phtm files in the directory it's running in and generates html files from any file that changes. The sleep time between checks can be passed at the commandline (or in the config file).
This means that you can edit your pages, alt-tab (or something) over to netscape and hit reload. You don't have to go via some 'compile' step. It feels like you're editing the pages directly.

Features?

 First off; you can disable some of the features via the command line or the config file.

    Defining macros / abbrevations
You can define strings like this:
#d shortword string to replace with - This replaces globally.
#din shortword string to replace with - This replaces only inside tags.
#dout shortword string to replace with - This replaces only outside tags.
#deol shortword string to replace with#MIDDLETEXT#another string - This replaces 'shortword' with the string before '#MIDDLETEXT#' and then puts the string after that at the end of the line where the keyword was found.
Let's see how it's useful:

#deol <BIGH> <font face="arial, helvetica">*#MIDDLETEXT#*</font><br>

blabla<br>
blabla<br>
<BIGH>This is a sub title in some text
blabla
would be rendered:

blabla<br>
blabla<br>
<font face="arial, helvetica"><b>This is a sub title in some text</b></font><br>
blabla

    Including files
Another directive is #i filename which let you include files. The contents of the included files will also be run through the macro processing, as will any macros in that file.


Any of these can be used anywhere in the text. So a #d newname stringtoreplacewith can be entered at tha last line of the document but will still be used through all of it.


    Formatting text
Making text bold is as easy as sorrounding the text with asterisks. Italics is produced by sorrounding text with underscores.
Example:
this is *bold* and this is _italics_
becomes:
this is bold and this is italics.

Links are easy:
[link name/text images whatever|the_href.html]
will produce a link like this:
link name/text images whatever

If you want to use some extra arguments you can type
[link name/text images whatever|the_href.html|class=whateverStyleSheetClassYouWant]
which becomes:
link name/text images whatever
(check the source to see how it came out)
To get those special characters on their own, simply escape them with a backslash. example: \* becomes *, \[ becomes [, etc.

If you use <I="img.html"...> rather than <img src="img.html"...> some nice features are added; width and height is fetched from the image and inserted automatically, if not already specified. The alt tag, if not specified, is inserted with the imagename, minus path and file ending, as string.

å, ä, ö, Å, Ä and Ö is translated to html codes. I guess I should add a zillion more, but you can simply add characters you need with #dout char &code; just as you usually define macros..

Several newlines together results in all additional (unnecessary) empty rows being deleted, except those inside a <pre> ... </pre> block, same goes for spaces (since the webbrowser throws out all spaces beyond one anyway.)

Note: The current directory (where you invoke the pretml program) is only scanned if no other directories are added via -d=... If directories are added to the "pathscan list", you have to add the current dir by hand if you'd like it scanned, like this: -d=./. This is a feature, not a bug!
If you have a lot of dirs added via -d in the config file but want to search only the current dir you can pass -o. -o makes pretml ignore all dirs added before the -o option. You can enter new/other dirs after the -o option, or none which equals -d=./ (read more on paramters further down...)

To learn more, check out the .ptml file for this page and for the mainpage of my homepage.

Commandline and configfile

 Here are the commandline options:
Anything between "[" and "]" is optionally typed, so all params can be shortened to one letter. Also, not passing an =N value to on/off switches equals passing =1 (on).

-d[irs]=dir;anotherdir    Adds dirs to scan. Dirs are separated with semicolons.

-o[nly]    ("only cwd") Resets directory list. Useful if you've got a long list of dirs in the config file but want to override and just add a few at commandline, or by not adding any, just scanning the current directory.

-r[ecurse][=N]    Turns on or off recursive scan. If you have a webpage with subfolders this is nice to turn on.

-l[isten][=N]    Set "listenmode", meaning that the program loops over the dirs passed (or just current dir) over and over again and recompiles .phtml files to .html whenever they are changed. N = time between checks, 0 = turns off listen mode (if it's set in the config file for an example.) If N (time) is not passed, it is set to 1 second.

-f[orce][=N]    If turned on, recompiles all found .phtml files even if they're up to date.


All these options can be entered in .pretmlrc which should be put in your home directory. This file is read before the commandline options are parsed, so you can override parts of the configfile by passing params at commandline.

TODO?

 Well, there's lot's of things that could be done, but I'll just wait and see if I find some bug or miss some feature which would make life easier. I prefer spending time on coding funny games rather than coding on this to "perfection".

Well, you're welcome to report bugs!


Project Log

 00-10-21 - Added more macro definition methods, intags, outsidetags, etc.. and fixed a few small bugs. Also made the code slightly more optimized.

00-06-17 - Made it possible to turn options off too. Necessary if you's like to override options set in the configfile. Also some small bug fixes.

00-06-15 - Fixed so that extra empty lines are left alone inside <pre> ... </pre>. Added support for configfile and changed options a bit. Added recursive mode. Added possibility to add several dirs to scan, not just current working directory.

00-06-12 - Some small fixes

00-06-08 - Started coding on it and finished most of it.


Visit the Pretml webpage: www.campbell.nu/oscar/pretml/
Mail (bugs to) Oscar Campbell: oscar@campbell.nu