displayHTML.gp



Creator information
Current maintainer :Max Maischein
Author(s) :Max Maischein
Recipe homepage :<none>

Version history
The documentation file was last modified on Tue Nov 29 18:22:58 2016.

Overview
displayHTML.gp is a recipe that allows the easy creation of HTML examples within HTML. It is mainly usefull for people that create documentation for Genpage recipes :).
Compatible Genpage Versions
Version 1.0.4+
Syntax
displayHTML( aHTMLString )

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).
A string containing an email adress must be passed to Perl like this :
displayHTML( "<A href=\"mailto:joev\@freddyfrog.com\">" );

Currently, displayHTML() is not themable. The "syntax coloring" consists of magenta for special characters like &amp;, 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.


Examples

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 :

<!-- _GP_ displayHTML("<FONT color=\"red\">red</FONT>") -->

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 :

<TABLE width="100%" bgcolor=#E8E8E8><TR><TD><CODE>
&lt;FONT color=&quot;red&quot;&gt;red&lt;/FONT&gt;
</CODE></TD></TR></TABLE>

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

<FONT color="red">red</FONT>

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 ?)
Here's how this setup could look (put this under %example2%):

This is some sample <B>HTML</B>. I didn't bother with anything like quoting stuff or keeping
Genpage from evaluating inline statements like <!-- _GP_ return "<CODE>Hello world</CODE>" -->.
Also, other comments <!-- like this one --> haven't received any special attention.

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

<TABLE width="100%" bgcolor=#E8E8E8><TR><TD><CODE>
This is some sample &lt;B&gt;HTML&lt;/B&gt;. I didn't bother with anything like quoting stuff or keeping<BR>
Genpage from evaluating inline statements like <FONT color=blue>&lt;!-- _GP_ return &quot;&lt;CODE&gt;Hello world&lt;/CODE&gt;&quot; --&gt;</FONT>.<BR>
Also, other comments <FONT color=gray>&lt;!-- like this one --&gt;</FONT> haven't received any special attention.<BR>

</CODE></TD></TR></TABLE>

And this is what the result looks like :

This is some sample <B>HTML</B>. I didn't bother with anything like quoting stuff or keeping
Genpage from evaluating inline statements like <!-- _GP_ return "<CODE>Hello world</CODE>" -->.
Also, other comments <!-- like this one --> haven't received any special attention.

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

This is some sample HTML. I didn't bother with anything like quoting stuff or keeping Genpage from evaluating inline statements like 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

This is some text processed by <!-- _GP_ version -->.

which gets expanded by Genpage evaluation to

This is some text processed by <a href="http://www.freddyfrog.com/hacks/genpage/">Genpage</a> - Version: 1.0.7.

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 :

  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.


To-do List

Known Bugs
None known :) Make the documentation a bit clearer - I'm not sure if everybody understands this ...

Back to Top


This page generated using Genpage - Version: 1.0.7 on Wed Nov 30 16:34:11 2016

© Max Maischein
1999