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.
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:
The PublishPlugin supports the generation of several different read-only document formats from Foswiki pages, including HTML and PDF.
The easiest quickest way to publish a web is from this topic, by filling completing 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.
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.
You can also create a permanent topic in a web to help with a repeated publishing process.
Most publishing tasks will only require setting the immediately visible options. Other more advanced options can be accessed by opening the collabsible sections.
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 an empty 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 |
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.
Create a link that invokes the rest
script and pass the current topic in param inclusions
:
Publish this page
(added newlines for readability).
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%
The Bookmaker allows you to select a number of topics by visiting them in turn and adding them to the book. Once your book is complete, you can return to this page to publish it.
To start the bookmaker, enable the BookmakerPlugin, and revisit this page to enable the interface. Once the bookmaker is running, visit the pages you want to add to the book and add them to the book. Once you are finished, use the bookmaker interface to return to this page to publish the results. To publish a book generated by Bookmaker, use the %BOOKLIST{"Bookweb.BookName"}%
macro in the topiclist
parameter.
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.
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.
Just cd
to the bin
directory, and perl -T rest /PublishPlugin/publish
. Parameters are passed as name=value pairs, for example:
perl -T rest /PublishPlugin/publish web=Book exclusions='Web*' format=file perl -T rest /PublishPlugin/publish web=Book inclusions=WebBook format=pdf extras='--book --duplex --toclevels=5'
The available parameter names are shown in the publish form above, in the last column.
You can control what gets published from a topic using %STARTPUBLISH%
and %STOPPUBLISH%
control tags:
%STARTPUBLISH%
is the first control tag seen in the file, everything before it will be ignored. %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
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.
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
.
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.
Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".
If you have any problems, or if the extension isn't available in configure
, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.
Run configure
and complete the installation in the PublishPlugin section.
PDF
output Install htmldoc from http://www.easysw.com/htmldoc/
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 Install Archive::Tar and everything it depends on
.zip
output 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.
This add-on started life as the GenHTMLAddon, written by Foswiki:Main/CrawfordCurrie at Motorola. It was then extended by Eric Scouten, and then further fixed and enhanced by Foswiki:Main/CrawfordCurrie (http://c-dot.co.uk). It has also been extended by Foswiki:Main/SvenDowideit and Foswiki:Main/MartinCleaver, and most recently refactored for Foswiki by Foswiki:Main/CrawfordCurrie. Other significant contributors are Foswiki:Main.ArthurClemens and Foswiki:Main.MichaelDaum.
Authors: Author: | Foswiki:Main/CrawfordCurrie, Eric Scouten, Foswiki:Main.SvenDowideit, Foswiki:Main.MartinCleaver, Foswiki:Main.ArthurClemens | |||||||||||||||||||||||||||||||||
Dependencies: |
| |||||||||||||||||||||||||||||||||
License: | GPL | |||||||||||||||||||||||||||||||||
Version: | 6222 (2010-02-05) 11251 (2011-03-28) | |||||||||||||||||||||||||||||||||
Release: | 05 2.2.0 Feb 2010 | |||||||||||||||||||||||||||||||||
Change History: | ||||||||||||||||||||||||||||||||||
05 Feb 2010 2.2.0 (28 Mar 2011) | Documentation update. Foswiki:Tasks/Item8225: fix handling of plugin contexts Item2635: make sure index.html is generated Foswiki:Tasks/Item10529: test integration with BookmakerPlugin? via new topiclist parameter | |||||||||||||||||||||||||||||||||
12 Jan 2010 2.1.7 (01 Nov 2010) | Foswikitask:Item2557 Foswikitask:Item8658 : fixed publish head elements added by ADDTOHEAD fix rest output when publishing to file, pdf and ftp | |||||||||||||||||||||||||||||||||
11 Jan 2010 2.1.6 (29 Oct 2010) | Foswikitask:Item2615 Foswikitask:Item8522 : fixed finding resources not inside quotes support for Foswiki 1.1.x and also 1.0.x+ZonePlugin Foswikitask:Item1638: fixed finding resources with parameters (e.g. ?t=2365421 ) | |||||||||||||||||||||||||||||||||
30 May 2009 2.1.5 (05 Feb 2010) | Foswikitask:Item8168 Documentation update. : fixed genopt (extras) | |||||||||||||||||||||||||||||||||
22 May 2009 2.1.4 (12 Jan 2010) | Foswikitask:Item8165 Foswikitask:Item2557 : fixed missing BASEWEB and other internal preferences. publish head elements added by ADDTOHEAD This was resulting in the wrong web being used for some operations | |||||||||||||||||||||||||||||||||
16 May 2009 2.1.3 (11 Jan 2010) | Foswikitask:Item1626 Foswikitask:Item2615 : fixed META{"formfield" finding resources not inside quotes Foswikitask:Item8150: (Marc Schaefer) fix for -skin parameter Foswikitask:Item1557: doc fix Foswikitask:Item1585: allow history topic in different web Foswikitask:Item871: add missing newline at start of topic text. Foswikitask:Item1449: topic publisher was not popping the context correctly Foswikitask:Item1632: improve backporting support | |||||||||||||||||||||||||||||||||
18 Mar 2009 2.1.2 (30 May 2009) | Foswikitask:Item804 Foswikitask:Item8168 : automatically create publish fixed genopt (extras) dir Foswikitask:Item8078: support publishing to a subdir of the publish dir, under url param control | |||||||||||||||||||||||||||||||||
14 Feb 2009 2.1.1 (22 May 2009) | Foswikitask:Item1033 Foswikitask:Item8165 : fixed button missing BASEWEB and other internal preferences. This was resulting in the wrong web being used for some operations PublishWeb | |||||||||||||||||||||||||||||||||
27 Nov 2008 2.1.0 (16 May 2009) | Foswikitask:Item8019 Foswikitask:Item1626 : refactored as fixed META{"formfield" a plugin and tested in Foswiki Foswikitask:Item8150: (Marc Schaefer) fix for -skin parameter Foswikitask:Item1557: doc fix Foswikitask:Item1585: allow history topic in different web Foswikitask:Item871: add missing newline at start of topic text. Foswikitask:Item1449: topic publisher was not popping the context correctly Foswikitask:Item1632: improve backporting support | |||||||||||||||||||||||||||||||||
27 Oct 2008 2.0.2 (18 Mar 2009) | 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 Foswikitask:Item804: automatically create publish dir Foswikitask:Item8078: support publishing to a subdir of the publish dir, under url param control | |||||||||||||||||||||||||||||||||
11 Dec 2007 2.0.1 (14 Feb 2009) | Item5099 fixed Foswikitask:Item1033: fixed button in PublishWeb | |||||||||||||||||||||||||||||||||
10 2.0.0 (27 Nov 2007 2008) | Tested on 4.2.0. Item4624:, Item4625: Item4830: fixed. Item4825: added a basic skin to avoid the confusion caused by Foswikitask:Item8019text : refactored as a plugin and tested in Foswiki skin. Item4951: added interface to allow management of output files | |||||||||||||||||||||||||||||||||
13222 1.6.5 (27 Oct 2008) | fixed ftp publish, added doco, Item5385: Fixed doc for configtopic Item5388: $WEB and added enabled plugin selection funcitonality $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 | |||||||||||||||||||||||||||||||||
13064 1.6.4 (11 Dec 2007) | Item3722 worked Item5099 fixed around core attaching URL params to internal URLs | |||||||||||||||||||||||||||||||||
12961 1.6.3 (10 Nov 2007) | Item3671 cannot publish without write access to history Tested on 4.2.0. Item4624:, Item4625: Item4830: fixed. Item4825: topic, so security now checked early. Item3619 Cleaned up error handling from writers. Item3675 added history topic a basic skin to record avoid changeset. Plus major refactoring of main class to get rid of some of the cruft that had confusion caused by built up from many authors. Item2726: uses getExternalResource now, so should obey proxy settings (untested) text skin. Item4951: added interface to allow management of output files | |||||||||||||||||||||||||||||||||
12824 1.6.2 | Added support for new internal api - no user changes fixed ftp publish, added doco, and added enabled plugin selection funcitonality | |||||||||||||||||||||||||||||||||
12708 1.6.1 | Added UI for FTP. Added .spec file. Fixed Item3515 and Item3722 worked around core attaching URL params to internal URLs Item2725 | |||||||||||||||||||||||||||||||||
12028 1.6.0 | Michael Daum - create a new TWiki object Item3671 cannot publish without write access to history for every topic, don't reuse 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 current one (Item3139) cruft that had built up from many authors. Item2726: uses getExternalResource now, so should obey proxy settings (untested) | |||||||||||||||||||||||||||||||||
10412 1.5.5 | Correction to Added support the correction for anchors. new internal api - no user changes | |||||||||||||||||||||||||||||||||
10345 1.5.4 | Correction to support anchors in URLs properly Added UI for FTP. Added .spec file. Fixed Item3515 and Item2725 | |||||||||||||||||||||||||||||||||
10242 1.5.3 | Martin Cleaver Michael Daum - changes to allow generation of viewprint and viewxxx when specified by TEMPLATE; multiple INSTANCE create a new wiki object for every topic, don't reuse the current one (Item3139) (dev/test/prod); (Item2269) | |||||||||||||||||||||||||||||||||
10063 1.5.2 | Bugfix Item2216 Correction to the correction for anchors. | |||||||||||||||||||||||||||||||||
10006 1.5.1 | Crawford Correction Currie - fixed problem where it was failing to remove | |||||||||||||||||||||||||||||||||
9986 1.5.0 | Crawford Currie Martin Cleaver - added doc on usage changes to allow generation from command line, corrected sense of topicsearch filter (Item2120, Item2121), renamed parameters (old ones are still valid), viewprint and viewxxx when specified by TEMPLATE; multiple INSTANCE (dev/test/prod); (Item2269) corrected handling of empty web refs (Item2128), deprecated nopublish html-style tag in favour of PublishWebPlugin-compatible style (though with richer semantics) (Item2196) | |||||||||||||||||||||||||||||||||
9823 1.4.3 | Crawford Currie Bugfix Item2216 - added support for hierarchical webs, and inclusion of external images. | |||||||||||||||||||||||||||||||||
9773 1.4.2 | Crawford Currie - added tgz and pdf support fixed problem where it was failing to remove | |||||||||||||||||||||||||||||||||
9725 1.4.1 | Michael Daum Crawford Currie - fixed rewriting urls; fixed nested resources issue; creating a new prefs object for each topic 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) | |||||||||||||||||||||||||||||||||
9713 1.4.0 | Corrected form action so it uses up the right web preferences Crawford Currie - added support for hierarchical webs, and inclusion of external images. | |||||||||||||||||||||||||||||||||
9695 1.3.9 | Michael Daum Crawford Currie - recursively archive added tgz resources imported by css files; fixed several html errors in the PublishPlugin and PublishWeb topics; pdf support removed hardcoded reference to print.pattern | |||||||||||||||||||||||||||||||||
8959 1.3.8 | TWiki-4 version. Also supports publishing to Michael Daum - fixed rewriting urls; fixed nested resources issue; creating a file area, making TWiki easier to new prefs object for each topic use as a CMS (see also Foswiki:Extensions/PublishWebPlugin, which does almost the same thing ![]() | |||||||||||||||||||||||||||||||||
6276 1.3.7 | Item196 - bugfix for HTTP_HOST, as described Corrected form action so it uses up in the Dev topic for right web preferences the contrib | |||||||||||||||||||||||||||||||||
5566 1.3.6 | Changed interface to support wildcards, and lightened Michael Daum - recursively archive resources imported the plugin by replacing a lot of files with simpler ways of doing things. css files; fixed several html errors in the PublishPlugin and PublishWeb topics; removed hardcoded reference to print.pattern | |||||||||||||||||||||||||||||||||
5499 1.3.5 | Added Compress::Zlib dependency, TWiki-4 version. Also supports publishing to a file area, making TWiki easier to use as requested by Brad Taylor a CMS (see also Foswiki:Extensions/PublishWebPlugin, which does almost the same thing ![]() | |||||||||||||||||||||||||||||||||
27 1.3.4 Apr 2005 | 1.301 Item196 Crawford Currie - fixed minor issues highlighted by Bruce Dillahunty and Scott Claridge bugfix for HTTP_HOST, as described in the Dev topic for the contrib | |||||||||||||||||||||||||||||||||
11 1.3.3 Apr 2005 | 1.3 Changed Crawford Currie - reworked the interface and code to work better support wildcards, and lightened the plugin by replacing a lot of files with simpler ways of doing things. | |||||||||||||||||||||||||||||||||
13 1.3.2 October 2004 | 1.200 Crawford Currie - Cairo compatible Added Compress::Zlib dependency, as requested by Brad Taylor | |||||||||||||||||||||||||||||||||
7 Jan 2003 1.3.1 (27 Apr 2005) | 1.1 Initial version Crawford Currie - fixed minor issues highlighted by Bruce Dillahunty and Scott Claridge | |||||||||||||||||||||||||||||||||
Home: 1.3.0 (11 Apr 2005) | http://foswiki.org/Extensions/PublishPlugin Crawford Currie - reworked the interface and code to work better | |||||||||||||||||||||||||||||||||
Support: 1.2.0 (13 October 2004) | http://foswiki.org/Support/PublishPlugin Crawford Currie - Cairo compatible | |||||||||||||||||||||||||||||||||
1.1.0 (7 Jan 2003) | Initial version | |||||||||||||||||||||||||||||||||
Home: | http://foswiki.org/Extensions/PublishPlugin | |||||||||||||||||||||||||||||||||
Support: | http://foswiki.org/Support/PublishPlugin |
Related Topics: DefaultPreferences, SitePreferences, Plugins
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
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
I | Attachment | Action | Size | Date | Who | Comment |
---|---|---|---|---|---|---|
![]() | publish.gif | manage | 53.3 K | 24 Feb 2010 28 Mar 2011 - 19:11 18:32 | AdminUser | Logo |
![]() | wikiringlogo20x20.png | manage | 1.3 K | 24 Feb 2010 28 Mar 2011 - 19:11 18:32 | AdminUser |