TWiki . TWiki . PublishAddOn

PublishAddOn

Settings

Summary

Generates a ZIP file containing a static view of a web.

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:

TWiki is used to create documentation which has to be bundled into a product release,
Published versions of TWiki pages must be read-only,
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 zip file containing rendered versions of a set of TWiki pages together with any attached files.

WARNING The zip files can get pretty big, and the process itself puts a heavy load on the server for large webs.

Features

All standard TWiki tags are interpreted
Plugins are called
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.
Powerful support for choosing what content gets published

Usage

The easiest way to publish a web is from this topic, by filling in the following form.

The ZIP file is generated in a directory designated during installation. The progress messages printed during documentation generation tell you where this is.

Ypu can also create a permanent topic in a web to help with the publishing process. See below.

Wildcard Patterns

Wildcard patterns are well known to people who are used to command lines on computers, but may be unfamiliar to the Windows generation. A wildcard is a special string that you can put into a filename so that it matches a whole range of files:

String	What it does	Example	What the example matches
*	Matches any string, including the null string.	`Cheese`	Every topic with "Cheese" somewhere in the name (but not "cheese")
?	Matches any single character.	Example1?	Example10 and Example 1X but not example1
[...]	Matches any one of the enclosed characters. A pair of characters separated by a hyphen denotes a range expression; any character that sorts between those two characters, inclusive, using the current locale's collating sequence and character set, is matched. If the first character following the [ is a ^ then any character not enclosed is matched. A - may be matched by including it as the first or last character in the set. A ] may be matched by including it as the first character in the set. Within [ and ], character classes can be specified using the syntax [:class:], where class is one of the following classes defined in the POSIX.2 standard: `alnum`, `alpha`, `ascii`, `blank`, `cntrl`, `digit`, `graph`, `lower`, `print`, `punct`, `space`, `upper`, `word`, `xdigit`. A character class matches any character belonging to that class. The `word` character class matches letters, digits, and the character _.	B[aeiou]g	Bag, Bog, Big, Beg, Bug

Regular Expressions

A perl regular expression. You can use a simple string here, which will be matched exactly, or you can read up on perl regular expressions on the web.

Using a Publish Topic

You can create a publish topic in a web that contains all the details needed to publish that web. This is just a topic with a series of standard TWiki variable settings in it. You can use the PublishWeb topic in this web as a template for your own topics.

Controlling what gets published

You can control what gets published from a topic using the <nopublish> .. </nopublish> tags (anything between the tags will not be published).

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`
`data/TWiki/PublishWeb.txt`
`lib/TWiki/Contrib/Publish.pm`
`lib/TWiki/Contrib/PublishAddOn/build.pl`
`bin/publish`
`PublishAddOn_installer.pl`	Install script

Unzip PublishAddOn.zip in your twiki installation directory.
perl PublishAddOn_installer.pl to automatically check and install other TWiki modules that this module depends on, and configure the plugin. 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.
Name Version Description
Archive::Zip >=1.05 Required, available from the CPAN:Archive::Zip archive
Compress::Zlib >=1.16 Required, available from the CPAN:Compress::Zlib archive
Set the 'Settings' above in your TWikiPreferences topic..

Info

This add-on started as the TWiki:Plugins/GenHTMLAddon, submitted by TWiki:Main/CrawfordCurrie at Motorola. This version is a rewrite from TWiki:Main/EricScouten, subsequently fixed by TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)

Author:

EricScouten^?

Dependencies:

Name	Version	Description
Archive::Zip	>=1.05	Required, available from the CPAN:Archive::Zip archive
Compress::Zlib	>=1.16	Required, available from the CPAN:Compress::Zlib archive

Version:

1.301

Change History:

27 Apr 2005

1.301 Crawford Currie - fixed minor issues highlighted by Bruce Dillahunty and Scott Claridge

11 Apr 2005

1.3 Crawford Currie - reworked the interface and code to work better

13 October 2004

1.200 Crawford Currie - Cairo compatible

7 Jan 2003

1.1 Initial version

Home:

TWiki:Plugins/PublishAddOn

Feedback:

TWiki:Plugins/PublishAddOnDev

Related Topics: TWikiPreferences, TWikiPlugins

Copyright

This code is a development of the Architectures and System Platforms group of Motorola Inc. and is protected by the following copyrights:

The 2005 functionality improvements were made possible by the support of Wind River Systems (http://www.windriver.com)

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
-- TWiki:Main/CrawfordCurrie - 16:42:01 28 April 2005

----- Revision r1.1 - 05 Oct 2005 - 09:17 - Main.apache

This website has been archived and is no longer maintained.

Web to publish
Comma-separated list of wildcard patterns that match the names of topics to include
Comma-separated list of wildcard patterns that match the names of topics to exclude
A regular expression that will cause a topic to be excluded if the RE matches the topic content
Select skin for published HTML :	You are recommended to pick `print.pattern` or `plain` or `print` skin. Your installation may also offer a special `export` skin.