Generates a static view of a web, as HTML files on disc, or as a PDF, or as a zip or tgz archive file, or by uploading directly to an FTP server.
Generates a static view of a web, as HTML files on disc, or as a PDF, or as a zip or tgz archive file, or by uploading directly to an FTP server.
Originally written for TWiki, previously known as GenHTMLAddOn, PublishAddOn, and PublishContrib, this is the most complete publishing solution for Foswiki.
Originally written for TWiki, previously known as GenHTMLAddOn, PublishAddOn, and PublishContrib, this is the most complete publishing solution for Foswiki.
PublishPlugin provides support for the generation of stand-alone HTML from a web. It will generate fully rendered versions of a set of Foswiki pages together with any attached files.
PublishPlugin provides support for the generation of stand-alone HTML from a web. It will generate fully rendered versions of a set of Foswiki pages together with any attached files.
When you want to read a document stored in Foswiki, you have to have access to the web server that hosts that document. There are times when this may not be desirable, or even possible. For example:
When you want to read a document stored in Foswiki, you have to have access to the web server that hosts that document. There are times when this may not be desirable, or even possible. For example:
Foswiki is used to create documentation which has to be readable off-line
Published versions of Foswiki pages must be read-only
The Foswiki server is inaccessible to the audience (e.g. on the other side of a corporate firewall)
You want to put product documentation on a CD
Foswiki is used to create documentation which has to be readable off-line
Published versions of Foswiki pages must be read-only
The Foswiki server is inaccessible to the audience (e.g. on the other side of a corporate firewall)
You want to put product documentation on a CD
The PublishPlugin supports the generation of several different read-only document formats from Foswiki pages, including HTML and PDF.
The PublishPlugin supports the generation of several different read-only document formats from Foswiki pages, including HTML and PDF.
Features
Features
All standard Foswiki macros are interpreted
Plugins are called
Unresolved links to non-existent topics are silently ignored
Topic links internal to the wiki 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 wiki 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!
All standard Foswiki macros are interpreted
Plugins are called
Unresolved links to non-existent topics are silently ignored
Topic links internal to the wiki 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 wiki 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!
Usage
Usage
Publish Form
Publish Form
The easiest way to publish a web is from this topic, by filling in the following form.
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. Admins can use the PublishPluginControlCentre to manage the published output.
The output is generated in a directory designated during installation. The progress messages printed during documentation generation tell you exactly where the output is. Admins can use the PublishPluginControlCentre to manage the published output.
Publishing is an access-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.
Publishing is an access-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.
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 _.
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
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.
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.
How-tos
How-tos
Publishing a single topic
Publishing a single topic
Create a link that invokes the rest script and pass the current topic in param inclusions:
Create a link that invokes the rest script and pass the current topic in param inclusions:
Now you can use this link in a skin adaption to put the link (or button) on all pages. Example of a template:
Now you can use this link in a skin adaption to put the link (or button) on all pages. Example of a template:
%TMPL:INCLUDE{view}%
%TMPL:DEF{"printable"}%Publish this page%TMPL:END%
%TMPL:INCLUDE{view}%
%TMPL:DEF{"printable"}%Publish this page%TMPL:END%
Using a Publish Topic (configtopic)
Using a Publish Topic (configtopic)
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 preference settings (which correspond to the form parameters) in it. You can use the PublishWeb topic in this web as a template for your own topics.
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 preference settings (which correspond to the form parameters) 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.
Alternatively you can just take a copy of the form in this topic, paste it into your own topic, and change the defaults.
To use a publish topic, you must pass the configtopic parameter to the publish script set to the name of the topic to use to control publishing. You can specify a topic in another web using the standard Web.Topic syntax.
To use a publish topic, you must pass the configtopic parameter to the publish script set to the name of the topic to use to control publishing. You can specify a topic in another web using the standard Web.Topic syntax.
Publishing from the command line
Publishing from the command line
Just cd to the bin directory, and perl -T rest /PublishPlugin/publish. Parameters are passed as name=value pairs, for example:
Just cd to the bin directory, and perl -T rest /PublishPlugin/publish. Parameters are passed as name=value pairs, for example:
The available parameter names are shown in the publish form above, in the last column.
The available parameter names are shown in the publish form above, in the last column.
Controlling which parts of a topic get published
Controlling which parts of a topic get published
You can control what gets published from a topic using %STARTPUBLISH% and %STOPPUBLISH% control tags:
You can control what gets published from a topic using %STARTPUBLISH% and %STOPPUBLISH% control tags:
If %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.
%STARTPUBLISH% and %STOPPUBLISH% will be visible in the viewed topic, so you can easily see what will be published from the topic.
If %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.
%STARTPUBLISH% and %STOPPUBLISH% will be visible in the viewed topic, so you can easily see what will be published from the topic.
Note: the old tag is deprecated and should be replaced in topics
Note: the old 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 and ENDSECTION 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.
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 and ENDSECTION 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.
Publishing History
Publishing History
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 PublishPluginHistory, 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.
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 PublishPluginHistory, 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 publish.
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 publish.
Installation Instructions
Installation Instructions
Dependencies
Dependencies
Note: If you want to generate PDF files, you will need an installation of htmldoc. 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.
Note: If you want to generate PDF files, you will need an installation of htmldoc. 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.
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.
Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".
Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".
Note that htmldoc can also be used to generate PostScript by using the -t option in the Other output generator options above. See the htmldoc man pages for details.
Note that htmldoc can also be used to generate PostScript by using the -t option in the Other output generator options above. See the htmldoc man pages for details.
.tgz (tar) output
.tgz (tar) output
Install Archive::Tar and everything it depends on
Install Archive::Tar and everything it depends on
.zip output
.zip output
Install Archive::Zip and everything it depends on
Install Archive::Zip and everything it depends on
WARNING! Anything published is no longer under the control of Foswiki access controls, and if you make the publish output directory visible on the web then you may need to take precautions to prevent accidental leakage of confidential information by restricting web access to this directory, for example in the Apache configuration.
WARNING! Anything published is no longer under the control of Foswiki access controls, and if you make the publish output directory visible on the web then you may need to take precautions to prevent accidental leakage of confidential information by restricting web access to this directory, for example in the Apache configuration.
Item5385: Fixed doc for configtopic Item5388: $WEB and $TOPIC were not correct in %IF statements Item5390: remove comments from .css before processing for included resoures Item5706: Improved FTP upload process for incrementally maintained webs Item6029: expand config topic on load to support use of searches Item6030: respect VIEW_TEMPLATE in published topics Item6092: expand common tags in configtopic Item6094: move sitemap options into base file generator Item6110: rename settings in config topic to avoid clashes with other plugins
11 Dec 2007
Item5099 fixed
10 Nov 2007
Tested on 4.2.0. Item4624:, Item4625: Item4830: fixed. Item4825: added a basic skin to avoid the confusion caused by text skin. Item4951: added interface to allow management of output files
Item3722 worked around core attaching URL params to internal URLs
12961
Item3671 cannot publish without write access to history topic, so security now checked early. Item3619 Cleaned up error handling from writers. 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)
12824
Added support for new internal api - no user changes
12708
Added UI for FTP. Added .spec file. Fixed Item3515 and Item2725
12028
Michael Daum - create a new TWiki object for every topic, don't reuse the current one (Item3139)
10412
Correction to the correction for anchors.
10345
Correction to support anchors in URLs properly
10242
Martin Cleaver - changes to allow generation of viewprint and viewxxx when specified by TEMPLATE; multiple INSTANCE (dev/test/prod); (Item2269)
10063
Bugfix Item2216
10006
Crawford Currie - fixed problem where it was failing to remove tags completely (Item2200)
9986
Crawford Currie - added doc on usage from command line, corrected sense of topicsearch filter (Item2120, Item2121), renamed parameters (old ones are still valid), corrected handling of empty web refs (Item2128), deprecated nopublish html-style tag in favour of PublishWebPlugin-compatible style (though with richer semantics) (Item2196)
9823
Crawford Currie - added support for hierarchical webs, and inclusion of external images.
9773
Crawford Currie - added tgz and pdf support
9725
Michael Daum - fixed rewriting urls; fixed nested resources issue; creating a new prefs object for each topic
9713
Corrected form action so it uses up the right web preferences
9695
Michael Daum - recursively archive resources imported by css files; fixed several html errors in the PublishPlugin and PublishWeb topics; removed hardcoded reference to print.pattern
8959
TWiki-4 version. Also supports publishing to a file area, making TWiki easier to use as a CMS (see also Foswiki:Extensions/PublishWebPlugin, which does almost the same thing )
6276
Item196 - bugfix for HTTP_HOST, as described in the Dev topic for the contrib
5566
Changed interface to support wildcards, and lightened the plugin by replacing a lot of files with simpler ways of doing things.
5499
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
Item5385: Fixed doc for configtopic Item5388: $WEB and $TOPIC were not correct in %IF statements Item5390: remove comments from .css before processing for included resoures Item5706: Improved FTP upload process for incrementally maintained webs Item6029: expand config topic on load to support use of searches Item6030: respect VIEW_TEMPLATE in published topics Item6092: expand common tags in configtopic Item6094: move sitemap options into base file generator Item6110: rename settings in config topic to avoid clashes with other plugins
11 Dec 2007
Item5099 fixed
10 Nov 2007
Tested on 4.2.0. Item4624:, Item4625: Item4830: fixed. Item4825: added a basic skin to avoid the confusion caused by text skin. Item4951: added interface to allow management of output files
Item3722 worked around core attaching URL params to internal URLs
12961
Item3671 cannot publish without write access to history topic, so security now checked early. Item3619 Cleaned up error handling from writers. 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)
12824
Added support for new internal api - no user changes
12708
Added UI for FTP. Added .spec file. Fixed Item3515 and Item2725
12028
Michael Daum - create a new TWiki object for every topic, don't reuse the current one (Item3139)
10412
Correction to the correction for anchors.
10345
Correction to support anchors in URLs properly
10242
Martin Cleaver - changes to allow generation of viewprint and viewxxx when specified by TEMPLATE; multiple INSTANCE (dev/test/prod); (Item2269)
10063
Bugfix Item2216
10006
Crawford Currie - fixed problem where it was failing to remove tags completely (Item2200)
9986
Crawford Currie - added doc on usage from command line, corrected sense of topicsearch filter (Item2120, Item2121), renamed parameters (old ones are still valid), corrected handling of empty web refs (Item2128), deprecated nopublish html-style tag in favour of PublishWebPlugin-compatible style (though with richer semantics) (Item2196)
9823
Crawford Currie - added support for hierarchical webs, and inclusion of external images.
9773
Crawford Currie - added tgz and pdf support
9725
Michael Daum - fixed rewriting urls; fixed nested resources issue; creating a new prefs object for each topic
9713
Corrected form action so it uses up the right web preferences
9695
Michael Daum - recursively archive resources imported by css files; fixed several html errors in the PublishPlugin and PublishWeb topics; removed hardcoded reference to print.pattern
8959
TWiki-4 version. Also supports publishing to a file area, making TWiki easier to use as a CMS (see also Foswiki:Extensions/PublishWebPlugin, which does almost the same thing )
6276
Item196 - bugfix for HTTP_HOST, as described in the Dev topic for the contrib
5566
Changed interface to support wildcards, and lightened the plugin by replacing a lot of files with simpler ways of doing things.
5499
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
The 2005 functionality improvements were sponsored by Wind River Systems
The 2005 functionality improvements were sponsored by Wind River Systems
The pdf and tgz output formats were made possible by Sabio Labs
The pdf and tgz output formats were made possible by Sabio Labs
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
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