Generates a static view of a web, as HTML files on disc, or as a
PDF, or as a
tgz archive file, or by uploading directly to an FTP server.
Previously known as GenHTMLAddOn, and then PublishAddOn, this is the original publishing extension for TWiki
NOTE: This extension is designed to work with TWiki 4.0 and later. You can use revision 1 of the attached zip file if you want to use the extension with an earlier version of TWiki, but it is missing many features and bugfixes.
PublishContrib provides support for the generation of stand-alone HTML from a TWiki web. It will generate fully rendered versions of a set of TWiki pages together with any attached files.
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)
- All standard TWiki tags are interpreted
- Plugins are called
- Unresolved links to non-existent topics are silently ignored
- Topic links internal to the TWiki are translated to relative links
- Powerful support for choosing what content gets published
- Any links to the 'pub' areas of topics in the web are automatically resolved and the referenced files copied
- Any links to images outside the TWiki are resolved, and the image is stored in the output (requires LWP)
- Output in HTML or PDF. HTML can be compressed in different archive formats.
- Full support for hierarchical webs
- Multiple instances (e.g. dev, test, prod) can be specified
- Special output format specific templates (such as viewpdf) can be used
- Able to publish HTML and referenced files directly to a remote server via ftp * Complete history of what was published, and when!
The easiest way to publish a web is from this topic, by filling in the following form.
The output is generated in a directory designated during installation. The progress messages printed during documentation generation tell you exactly where the output is, and you can use the publishers control interface
to manage your published output.
Publishing is a controlled process; before you can publish, you have to have VIEW access to the topics you want to publish, and CHANGE access to the publishing history topic.
You can also create a permanent topic in a web
to help with the publishing process.
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:
|| What it does
|| What the example matches
|| Matches any string, including an empty string.
| Every topic with "Cheese" somewhere in the name (but not "cheese")
|| Matches any single character.
|| 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:
xdigit. A character class matches any character belonging to that class. The
word character class matches letters, digits, and the character _.
|| Bag, Bog, Big, Beg, Bug
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.
Alternatively you can just take a copy of the form in this topic, paste it into your own topic, and change the defaults.
Publishing from the command line
TWiki-4 allows you to call any TWiki script from the command line, and the
script is no exception. Just
perl -T publish
. Parameters are passed as name=value pairs, for example:
perl -T publish web=Book exclusions='Web*' format=file
perl -T publish web=Book inclusions=WebBook format=pdf genopt='--book --duplex --toclevels=5'
The available parameter names are shown in the example above, in the 'Name' column.
Controlling which parts of a topic get published
You can control what gets published from a topic using
%STARTPUBLISH% is the first control tag seen in the file, everything before it will be ignored.
- Everything between
%STOPPUBLISH% and the next
%STARTPUBLISH% (or the end of the topic) will be ignored.
%STOPPUBLISH% will be visible in the viewed topic, so you can easily see what will be published from the topic.
Note: the old <nopublish> tag is deprecated and should be replaced in topics
Another good trick is to set up a special "publishing" web. Create topics in the web that %INCLUDE the topics from other
webs that you want to publish. You can use STARTSECTION
to highlight what you want published. This way the "publishing" web gives you a view of exactly what will be in the published output, without the need for special publishing tags.
Every time a web is published, then the results of that publishing step are stored in a topic in the web. By default this topic is called
, but you can choose another name (see the form, above). In order to publish a web, you have to be able to write to this topic. If you need to add access controls to the topic, then make sure you do that right at the beginning of the topic, or in the hidden preferences.
The history topics contains a list of all the parameters used, and the versions of the topics that were published, so it is very useful for tracking exactly what you publish. it is written every time you run
Note: If you want to generate PDF files, you will need an installation of
. This program is available from http://www.easysw.com/htmldoc/
for free, but you are strongly
recommended to buy the commercial version. Your support for open-source projects helps make open-source software possible.
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
Like many other TWiki extensions, this module is shipped with a fully
automatic installer script written using the BuildContrib.
- If you have TWiki 4.2 or later, you can install from the
configure interface (Go to Plugins->Find More Extensions)
- If you have any problems, then you can still install manually from the command-line:
- Download one of the
- Unpack the archive in the root directory of your TWiki installation.
- Run the installer script (
perl <module>_installer )
configure and enable the module, if it is a plugin.
- Repeat for any missing dependencies.
- If you are still having problems, then instead of running the installer script:
- Make sure that the file permissions allow the webserver user to access all files.
- Check in any installed files that have existing
,v files in your existing install (take care not to lock the files when you check in)
- Manually edit LocalSite.cfg to set any configuration variables.
and complete the installation in the PublishContrib
section. If you can't do this for some reason, these are the settings required in LocalSite.cfg:
| File path to the directory where published files will be generated. you will normally want this to be visible via a URL, so the TWiki pub directory is a good choice.
| URL path of the directory you defined above.
| Template command-line for the PDF generator program - for example, =htmldoc --webpage --links --linkstyle plain --outfile %FILE
|| F% %EXTRAS
|| U% %FILES
- install htmldoc from http://www.easysw.com/htmldoc/
can also be used to generate PostScript by using the
option in the
Other output generator options
above. See the
man pages for details.
.tgz (tar) output
- Install Archive::Tar and everything it depends on
- Install Archive::Zip and everything it depends on
This add-on started as the TWiki:Plugins/GenHTMLAddon
, written by TWiki:Main/CrawfordCurrie
at Motorola. It was then rewritten by TWiki:Main/EricScouten
, and then fixed and enhanced by TWiki:Main/CrawfordCurrie
). It has been further extended by TWiki:Main/SvenDowideit
Related Topics: TWikiPreferences
|| TWiki:Main/CrawfordCurrie, TWiki:Main/EricScouten, TWiki:Main.SvenDowideit, TWiki:Main.MartinCleaver
|File::Spec||>0||Required. Used to analyse URL paths.|
|File::Copy||>0||Required. Used to move files around.|
|File::Path||>0||Required to manipulate directories.|
|LWP||>0||Optional. Used to include images referenced by absolute URLs|
|Archive::Zip||>=0||Optional. Required to generate .zip output|
|Archive::Tar||>=0||Optional. Required to generate .tgz output|
|Net::FTP||>0||Optional. Required for ftp publishing.|
|htmldoc||Optional. Required to generate .pdf output|
|| 15973 (11 Dec 2007)
| Change History:
| 11 Dec 2007
|| TWikibug:Item5099 fixed
| 10 Nov 2007
|| Tested on 4.2.0. TWikibug:Item4624:, TWikibug:Item4625: TWikibug:Item4830: fixed. TWikibug:Item4825: added a basic skin to avoid the confusion caused by
text skin. TWikibug:Item4951: added interface to allow management of output files
|| fixed ftp publish, added doco, and added enabled plugin selection funcitonality
|| TWikibug:Item3722 worked around core attaching URL params to internal URLs
|| TWikibug:Item3671 cannot publish without write access to history topic, so security now checked early. TWikibug:Item3619 Cleaned up error handling from writers. TWikibug:Item3675 added history topic to record changeset. Plus major refactoring of main class to get rid of some of the cruft that had built up from many authors. Item2726: uses getExternalResource now, so should obey proxy settings (untested)
|| Added support for new internal api - no user changes
|| Added UI for FTP. Added .spec file. Fixed TWikibug:Item3515 and TWikibug:Item2725
|| Michael Daum - create a new TWiki object for every topic, don't reuse the current one (TWikibug:Item3139)
|| Correction to the correction for anchors.
|| Correction to support anchors in URLs properly
|| Martin Cleaver - changes to allow generation of viewprint and viewxxx when specified by TEMPLATE; multiple INSTANCE (dev/test/prod); (TWikibug:Item2269)
|| Bugfix TWikibug:Item2216
|| Crawford Currie - fixed problem where it was failing to remove <base> tags completely (TWikibug:Item2200)
|| Crawford Currie - added doc on usage from command line, corrected sense of topicsearch filter (TWikibug:Item2120, TWikibug:Item2121), renamed parameters (old ones are still valid), corrected handling of empty web refs (TWikibug:Item2128), deprecated nopublish html-style tag in favour of PublishWebPlugin-compatible style (though with richer semantics) (TWikibug:Item2196)
|| Crawford Currie - added support for hierarchical webs, and inclusion of external images.
|| Crawford Currie - added tgz and pdf support
|| Michael Daum - fixed rewriting urls; fixed nested resources issue; creating a new prefs object for each topic
|| Corrected form action so it uses up the right web preferences
|| Michael Daum - recursively archive resources imported by css files; fixed several html errors in the PublishContrib and PublishWeb topics; removed hardcoded reference to print.pattern
|| TWiki-4 version. Also supports publishing to a file area, making TWiki easier to use as a CMS (see also TWiki:Plugins/PublishWebPlugin, which does almost the same thing )
|| TWikibug:Item196 - bugfix for HTTP_HOST, as described in the Dev topic for the contrib
|| Changed interface to support wildcards, and lightened the plugin by replacing a lot of files with simpler ways of doing things.
|| Added Compress::Zlib dependency, as requested by Brad Taylor
| 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
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 sponsored by Wind River Systems
output formats were made possible by
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