|Current maintainer :||Max Maischein|
|Author(s) :||Max Maischein|
|Recipe homepage :||<none>|
|Compatible Genpage Versions|
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>Note that for literal strings, certain characters need to be quoted such that Perl does not choke on them, especially the double-quote character (") and the character @ (whatever its name is).
displayHTML( "<A href=\"mailto:joev\@freddyfrog.com\">" );
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,
<!-- _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 :
<!-- _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.
<!-- _GP_ displayHTML( expand( content( "example2" ))) -->to pull in the evaluated HTML code; All
<!-- _GP_ ... -->tags will have been expanded.
<!-- _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
<!-- _GP_ content( "example2" ) --> :
Hello world. Also, other comments haven't received any special attention.
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 :This is some text processed by Genpage - Version: 1.0.7.
The typical setup for displayHTML() in documentation use consists of four parts :
<!-- _GP_ displayHTML( content( "example1" )) -->to display the HTML in the browser.
<!-- _GP_ displayHTML( expand( content( "example1" ))) -->to display the HTML after Genpage had its go at it.
<!-- _GP_ content( "example1" ) -->to display what the content looks like.