The Labs.Com ProgrammerHTML

The Labs - Design & Functionality For The Net

Another Extensible Markup-Language (not XML)

written by René K. Müller

Latest version of this document you find here.

1. Introduction
2. The <def> Tag
3. Legal
4. Download & Installation
5. General Usage
6. In-Depth Resources
7. Security
8. Todo
9. Known Bugs
10. Sites Using ProgrammerHTML

ProgrammerHTML is small extension for HTML which allows programmers to write more sophisticated web-pages. Expected are indepth experience with HTML and Perl, JavaScript or C-language, otherwise this tool isn't of much use for you.

The main idea behind ProgrammerHTML is that you define how a certain tag is rendered, unlike XML does, you define which language you write the script/program, inline or external program.

The design and the textual content is split, actually the way HTML formerly was designed for, but during the last years HTML became a design-language, not longer a markup-language. ProgrammerHTML gives this functionality back, and further supports several programming languages.

ProgrammerHTML 2. The <def> Tag

This is the core of phtml, the def-tag is the tag which opened you into the world of ProgrammerHTML.

In general, you can define new tags as you like, the functionality can be implemented with

• Perl
• ModPerl (same as Perl, but input/output restricted)
• JavaScript
• C

<def name=name plugin=program-name [language=language]>

...

</def>

if you want an external program handling it, then set program-name to an exactuable program (compiled program or script).

But also you can enclose the source-code direct:

<def name=name plugin=inline language=perl>

print "<ul>";

while(<STDIN>) {

print "<li> $_";

}

print "</ul>\n";

</def>

the same if you use it "on-the-fly" content-handler:

<def name=name plugin=inline language=modperl>

out("<ul>");

foreach(split(/\n/,$arg{body})) {

out("<li> $_");

}

out("</ul>\n");

</def>

Following tag-arguments are supported:

• name (required), ie. name="test"
• plugin (not required), ie. plugin=inline, plugin=testtag
  default is no plugin, then it functions as macro replacement
• language (not required), ie. language=perl (javascript, c)
  language only required when plugin=inline
• container (not required), ie. container=yes, container=no
  default is container=yes, then <test></test> otherwise tag can be used <test> solely when container=no.

For deeper information how to write new HTML-tags definition look at The DEF Tag.

ProgrammerHTML 3. Legal

ProgrammerHTML is copyrighted by René K. Müller 1997-1999, 2000, 2001

Free for educational, non-commercial and commercial use, but comes without any support and warranty.

ProgrammerHTML 4. Download & Installation

Download

• phtml (standalone)
• ProgrammerHTML.tar.gz (apache content-handler)

($MyVersion: 0.067 - Thu Aug 28 13:56:30 CEST 2003 - kiwi$)

$MyHistory$

28 Aug 2003: 0.067: NOT_FOUND error included .

24 Aug 2003: 0.066: plugin_calls init .

21 Jan 2003: 0.065: handler(): ">" occassionaly appeared, bug fixed .

03 Sep 2000: 0.064: bug fix for multiple %in{xyz} assignments, \0 sep..

26 Jul 2000: 0.063: Makefile.PL for content-handler .

22 Jun 2000: 0.062: virtuals supported, with dedicated ./phtmlrc .

10 Jun 2000: 0.061: executable (-x) html define their own content-typ..

31 May 2000: 0.059: PHTMLHeader support (text/html default, off, or d..

25 May 2000: 0.056: more clean up, handler() gets %in (cgi params) .

24 May 2000: 0.054: major source-code clean up & handler() .

19 May 2000: 0.052: modperl support, possible to use as cgi/mod_perl ..

29 Jan 2000: 0.051: small fix about starting tag n .

28 Aug 1999: 0.049: webtree functionality built-in .

02 Mar 1999: 0.048: allow empty args within tags .

10 Oct 1998: 0.043: tags are case-insensitive (as it should be) .

22 Sep 1998: 0.041: perl called inline (faster) .

07 Aug 1998: 0.037: structure file supported .

26 Mar 1998: 0.020: norecursive improved 'def' can now include all ki..

03 Feb 1998: 0.017: phtmld (defined in the same code).

02 Jan 1998: 0.010: rename to phtml or ProgrammerHTML, excluded some ..

26 Dec 1997: 0.005: plug-in's implemented.

13 Dec 1997: 0.001: start, first version.

Copy phtml into /usr/local/bin or you prefered bin/ directory, and ln -s phtml phtmld as well.

ProgrammerHTML 5. General Usage

Preprocessor

% phtml test.phtml  or as  % phtml   then all ./*.phtml will be converted in case the have changed since the last run of phtml. If you have a tree of directories  % phtml -recursive  then all directories are checked for *.phtml files.

Content Handler

A special mode is available to use phtml as content-handler within Apache httpd in conjunction with modperl or as CGI. This means you can write ProgrammerHTML-enhanced pages which will be converted on the fly. More details at ProgrammerHTML: Handler.

Daemon

You can call phtmld also, where /usr/local/lib/phtml/dirs contains a list of directories which contain .phtml files. Once phtmld runs in the background and converts the files automatically. (Under Development)

ProgrammerHTML 6. In-Depth Resources

The DEF Tag How to write plugins (extern and inline)	ProgrammerHTML-Handler how to use it as apache-http/modperl content-handler
ProgrammerHTML-Cookbook Advanced use of ProgrammerHTML with simple usage upto expert examples	ProgrammerHTML-Webtree Define the logical structure of a site
ProgrammerHTML-Plugins Collection of plugins, useful to study other people' ideas

ProgrammerHTML 7. Security

• Don't allow any web-user to write HTML pages at all.
• Don't use guestbooks, or threaded discussions which create HTML pages direct, web-user could enter malicious <def> code by themselves.
• Use guestbooks or discussion-forums which store their submission as text or HTML in separate file(s) (but not .html pages); those files you include from an phtml page. This way the data doesn't get interpreted by phtml.
• In general, anything which is requested direct via http:// is wrapped via phtml; anything you include (read from a file or db) within an phtml-file/page is not interpreted.

ProgrammerHTML 8. Todo

• More examples and better documentation
• . . .

ProgrammerHTML 9. Known Bugs

• If you use plugin=inline, and you are using by chance somewhere the term </def>, it will be considered the end of the definition. If it appears in quotes like "</def>", then it won't be considered as ending, this allows to easily to write phtml-files within a phtml-tag.

• phtmld isn't 100% reliable yet, if a file isn't written completely (in case NFS is real slow) it converts not the entire source-code. Any hints to solve this?

ProgrammerHTML 10. Sites Using ProgrammerHTML

Some samples of web-sites where ProgrammerHTML was used:

This Site All done with one phtmlrc, some pages override certain tags (ie this one does override one tag)	SpiritWeb.Org Main-section of this site are done using ProgrammerHTML and PicArt.	SpiritArt.Org This was done by one single phtmlrc, and PicArt package.
Bhagavad-Gita.Org graphic intensive site (sanskrit verses) etc.

                                                                                                                                   

PicArt

Homepage

Graphic Lab