PublishAddOn < TWiki

TWiki
TWiki.PublishAddOnr1.1 - 08 Feb 2005 - 02:47 - Members.guesttopic end
This add-on started as the TWiki:Plugins/GenHTMLAddon, submitted by TWiki:Main/CrawfordCurrie at Motorola. This version is a major rewrite from TWiki:Main/EricScouten.

---++ Usage

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 desirable or even possible. For example:
   1 TWiki is used to create documentation which has to be bundled into a product release,
   1 Published versions of TWiki pages must be read-only,
   1 The TWiki server is inaccessible to the audience (e.g. on the other side of a corporate firewall).

PublishAddOn 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.

   * A specific section of a template or page may be omitted from the rendered HTML by wrapping it in *&lt;nopublish&gt;* ... *&lt;/nopublish&gt;*. (*Hint:* Wrap the "control panel" of a template -- the portion that provides edit/attach/etc. in &lt;nopublish&gt;.)

---+ 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 'publish'. (*Hint:* Create a <nop>WebPublish topic in your web that does this for you.) For example, if you are viewing the WebHome topic, the URL will be something like
<pre>
http://node.company.com/twiki/bin/view/Main/WebHome
</pre>
Modify this URL to read instead
<pre>
http://node.company.com/twiki/bin/publish/Main/WebHome
</pre>
(Your TWiki administrator may have already set up <a href="%SCRIPTURLPATH%/publish/%WEB%">a shortcut</a> 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 "Publish" button. *Note:* You can bypass this screen by adding the option *goAhead=yes* in the query string.

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

---++ Specialised templates
This addon renders using existing skins. It will, by default, use the skin specified in WebPreferences for the published web. This can be overriden by adding the option *skin={skin name}* in the query string (same as the view script).

---+ Settings
The next two settings should be in %TWIKIWEB%.TWikiPreferences or WebPreferences
   * Root directory for static-published HTML
   * Set  PUBLISH_DIR = /home/httpd/path/to/published/files/
   * Root URL for static-published HTML (should point to the same dir as PUBLISH_DIR)
   * Set PUBLISH_URL_PATH = /url/path/to/published/files/

Local settings
   * Name of the perl package
      * Set STUB = TWiki::Contrib::Publish
   * Short description
      * Set SHORTDESCRIPTION = Generate static HTML for a TWiki Web
---++++ 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.
   * Links to excluded topics get generated as links

---+++ Installation Instructions
   * Download the ZIP file from the Plugin web (see below). Contents:
   | *File:* | *Description:* |
   | ==data/TWiki/PublishAddOn.txt== |  |
   | ==lib/TWiki/Contrib/Publish.pm== |  |
   | ==lib/TWiki/Contrib/PublishAddOn/build.pl== |  |
   | ==templates/oopsmore.tmpl== |  |
   | ==templates/oopspublished.tmpl== |  |
   | ==templates/oopspublisherr.tmpl== |  |
   | ==templates/publish.tmpl== |  |
   | ==bin/publish== |  |
   | ==PublishAddOn_installer.pl== | Install script |

   * Unzip ==%TOPIC%.zip== in your twiki installation directory.
   * =perl= ==%TOPIC%_installer.pl== to automatically check and install other TWiki modules that this module depends on. This script also includes an _uninstaller_ should you ever wish to remove the plugin from your installation.
   * Alternatively, manually make sure the dependencies listed in the table below are resolved.
   <table border=1><tr><th align="left">Name</th><th align="left">Version</th><th align="left">Description</th></tr><tr><td align="left">Archive::Zip</td><td align="left">&gt;=1.05</td><td align="left">Required, available from the CPAN:Archive::Zip archive</td></tr><tr><td align="left">Compress::Zlib</td><td align="left">&gt;=1.16</td><td align="left">Required, available from the CPAN:Compress::Zlib archive</td></tr></table>
   * Set the 'Settings' above in your %TWIKIWEB%.TWikiPreferences topic.

---+++ Info
| Author: | Main.EricScouten |
| Dependencies: | <table border=1><tr><th align="left">Name</th><th align="left">Version</th><th align="left">Description</th></tr><tr><td align="left">Archive::Zip</td><td align="left">&gt;=1.05</td><td align="left">Required, available from the CPAN:Archive::Zip archive</td></tr><tr><td align="left">Compress::Zlib</td><td align="left">&gt;=1.16</td><td align="left">Required, available from the CPAN:Compress::Zlib archive</td></tr></table> |
| Version: | 1.201 |
| Change History: | |
| 13 October 2004 | 1.200 Crawford Currie - Cairo compatible |
| 7 Jan 2003 | 1.1 Initial version |
| Home: | TWiki:Plugins/%TOPIC% |
| Feedback: | TWiki:Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins

---++++ Copyright
This code is a development of the Architectures and System Platforms group of Motorola Inc. and is protected by the following copyrights:
   * Copyright &copy; 2001 Motorola. All Rights Reserved.

Further modifications were made by Eric Scouten and are copyright &copy; 2002-2003, Eric Scouten.

The Cairo compatible version is Copyright &copy; 2004 Crawford Currie http://c-dot.co.uk

---++++ 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

-- TWiki:Main/EricScouten %BR%
-- TWiki:Main/CrawfordCurrie - 08:47:33 08 February 2005
<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the Dev topic instead. -->
to top
End of topic
Skip to action links | Back to top
You are here: TWiki > PublishAddOn

to top