Tags:
create new tag
, view all tags

GenHTMLAddon

THIS ADDON IS NO LONGER SUPPORTED - PLEASE SEE PublishContrib

-- CrawfordCurrie - 02 Feb 2003

When TWiki generates a view, it does so dynamically i.e. there's a CGI script that runs, processes some files, and generates HTML that is displayed by the browser. There are circumstances in which this may not be desireable or even possible. For example:

  1. TWiki is used to create documentation which has to be bundled into a product release,
  2. Published versions of TWiki pages must be read-only,
  3. The TWiki server is inaccessible to the audience (e.g. on the other side of a corporate firewall).

GenHTMLAddon provides support for the generation of stand-alone HTML from a TWiki web. It will generate a directory containing rendered versions of a set of TWiki pages together with any attached files.

WARNING This addon generates HTML output in the 'pub' directories of your twiki installation. For a large web, this can amount to a considerable amount of data!

Features

Tags

  • All standard TWiki tags are interpreted, including Plugins
  • UnresolvedLinks to non-existant topics are silently ignored
  • Topic links internal to the web are translated to relative links
  • External links (outside this web) are left untouched
  • Any links to the 'pub' areas of topics in the web are automatically resolved and the referenced files copied into the 'images' subdirectory.

Using the Addon

To generate HTML for a web, view any topic in the web. Edit the URL of the topic and change 'view' to 'genhtml'. For example, if you are viewing the WebHome topic, the URL will be something like
http://node.company.com/twiki/bin/view/Main/WebHome
Modify this URL to read instead
http://node.company.com/twiki/bin/genhtml/Main/WebHome
(Your TWiki administrator may have already set up a shortcut in the view template; see your local site information for details) Then hit return to invoke the script.

The first thing you see is a web form that allows you to control the HTML generation for the web. From this form you can change the web to generate documentation for, and list perl regular expressions to match topics that you wish to include (default: all) or exclude from generation. When you have set these parameters appropriately, hit the "Generate HTML" button.

The HTML is generated in a subdirectory of the 'pub' directory for the web; the progress messages printed during documentation generation indicate where the generated HTML has been written.

Specialised templates

A specialised template can be provided. If a template called 'genhtml.tmpl' can be found then this is automatically used. A default top-level template is provided with the installation.

Tip you can refer to a stylesheet within the genhtml.tmpl template. As long as this stylesheet is within the 'pub' directories for the web it will automatically be copied into the generated HTML.

Known problems

  • Doesn't handle revision info tags in templates
  • Plugin tags that create complex HTML (sug as TWikiDraw DRAWING tags) are not handled correctly.
  • GenHTMLAddon was originally developed for use with the Dec 2000 release of TWiki. The Sep 2001 release has introduced changes that have not been fully researched.
  • Links to excluded topics get generated as links

Addon Installation Instructions

  • Download the ZIP file from the Plugin web (see below). Contents:
    File: Description:
    GenHTMLAddon.xml Ant build file
    data/Plugins/GenHTMLAddon.txt Addon topic
    bin/genhtml New command
    templates/genhtml.tmpl Sample template
    pub/Plugins/GenHTMLAddon/example.css Example stylesheet
    lib/TWiki/Plugins/GenHTMLAddon/GenHTML.pm Module library
    lib/TWiki/Plugins/GenHTMLAddon/GenHTMLIF.pm Module library
    lib/TWiki/Plugins/GenHTMLAddon/test.zip Test files
  • Unzip GenHTMLAddon.zip in your twiki installation directory.
  • Add the following line to the "TWiki Addons" section of TextFormattingRules:

Addon info

One Line Description: Generate static HTML for a TWiki Web
Addon Author: CrawfordCurrie
Addon Version: 1.1
Change History: 1 Oct 2001: Initial version
  7 Oct 2001: Updated to fix compatability problem in Sep2001 release
  3 Jan 2002: Added inclusions, fixed '-' in attachment names, fixed directory permissions issue.
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.0
Addon Home: http://TWiki.org/cgi-bin/view/Plugins/GenHTMLAddon
Feedback: http://TWiki.org/cgi-bin/view/Plugins/GenHTMLAddonDev

Related Topics: TWikiPreferences, TWikiPlugins

Further development

Further development of this code is welcomed. It is recommended that you unpack the distribution into a development directory and use the supplied Ant http://jakarta.apache.org build file which provides targets to test and install your development code into a test installation.

Copyright

This code is a development of the Architectures and System Platforms group of Motorola Inc. and is protected by the following copyrights:
  • Copyright (C) 2001 Motorola. All Rights Reserved.

License

As required for the publication of all extensions to TWiki, the software is published under the terms of the GNU General Public License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, published at http://www.gnu.org/copyleft/gpl.html

See also

Further discussions are to be found at: GenHTMLPluginProbs

A new version of this add-on was released as PublishAddOn.

Topic attachments
I Attachment History Action Size Date Who Comment
Compressed Zip archivezip GenHTMLAddon.zip r2 r1 manage 14.0 K 2002-01-03 - 10:47 CrawfordCurrie Unzip at top level of TWiki installation
Unknown file formatgz GenHTMLPlugin.tar.gz r1 manage 8.5 K 2001-09-15 - 13:01 CrawfordCurrie Out of date - use the zip file
Edit | Attach | Watch | Print version | History: r15 < r14 < r13 < r12 < r11 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r15 - 2006-04-19 - WillNorris
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.