displayHTML.gp

• v 1.0 - first version
• v 1.1 - now uses expand() in the patched Genpage
• v 1.2 - now supports optionally actually interpreting tags at your discretion by using <#tag>.

displayHTML() takes one parameter and returns the quoted version of that string, suitable for inclusion as a HTML example.

aHTMLString is a valid Perl string that contains the string to be quoted. This can be a literal string (like "Hello world") or the result of a function call (like content( "example1" )).

It is possible to have displayHTML interpret html tags if you need to, to do this, specify the tags as <#TAG>

Currently, displayHTML() is not themable. The "syntax coloring" consists of magenta for special characters like &, gray for comments like <!-- this --> and blue for Genpage statements <!-- _GP_ return "this" -->. Maybe I will later add themes (if my color choice proves too hideous) or change the defaults (for the same reason).

Also, the background is a light gray and cannot be changed.

First of all, the file displayHTML.gp must be included in some content, by using <!-- _GP_ recipe( "displayHTML.gp" ) -->.

Let's have a look at the following sample HTML :

Note how the characters that have a special meaning for Perl (mainly '"') must be quoted, so that the first parameter contains all HTML.

This is the HTML that Genpage generates for the above line :

And this is what the result looks like (it looks like a code example, since that is what displayHTML() creates ) :

This is not really exciting, and it is quite cumbersome to quote all "-chars so that Perl dosen't chocke on it. So we now use another setup :

1. Set up a section that contains the HTML that you want to use (let's call it %example2%).
2. Use <!-- _GP_ displayHTML( content( "example2" )) --> to pull in the HTML code when you want it. This will always be the unevaluated version, none of the <!-- _GP_ ... --> tags will have been evaluated.
3. Use <!-- _GP_ displayHTML( expand( content( "example2" ))) --> to pull in the evaluated HTML code; All <!-- _GP_ ... --> tags will have been expanded.
4. Use <!-- _GP_ content("example2") --> to include the actual section (isn't it nice to have both, the example and its code always in sync ?)

This is what Genpage generates as HTML when using <!-- _GP_ displayHTML( content( "example2" )) --> :

And this is what the result looks like :

And if you ever need the contents of the section "example2" they are available through <!-- _GP_ content( "example2" ) --> :

Except for the color coding, this has some very nice features for documentation. Here is (repeating the steps above) again the cookbook to create your documentation. For example, you will want to demonstrate the workings of your routine (let's take the built-in version() as an example). The code to include version() would be

which gets expanded by Genpage evaluation to

which in the end looks like this :

The typical setup for displayHTML() in documentation use consists of four parts :

1. Set up the example HTML in its own section (let the name be example1).
2. Use <!-- _GP_ displayHTML( content( "example1" )) --> to display the HTML in the browser.
3. Use <!-- _GP_ displayHTML( expand( content( "example1" ))) --> to display the HTML after Genpage had its go at it.
4. Use <!-- _GP_ content( "example1" ) --> to display what the content looks like.

• Add theme files for syntax highlighting