PublishWikiTrail

Summary: Provide the ability to publish the pages of a wiki trail as a single web page, formatted for printing

Version: 2.0.6

Prerequisites:

Status:

Maintainer: jr

Categories: Publishing, Administration, WikiTrails

Goal

Provide the ability to publish the pages of a wiki trail as a single web page, formatted for printing.

Solution

Please note. The PublishPDF library includes the PublishWikiTrail recipe.

Latest is publish-2.0.10.tar.gz Δ (current stable version is publish-2.0.6.tar.gz Δ); it seems to be working correctly on beta 26 and above. The latest version supports the Cookbook.SearchExtensions, publishing selected page links (see RenamePage action=links) and publishing selected pages from the trail using action=pubchoices.

The publish-2.0.10/ folder contains publish.php and a publish/ skin. It adds support for making the trail items link to anchors in the published page; trail markup links back to the top of the published page.

Translation

The strings to be translated are defined in the PmWiki.XLPageCookbookTemplate page, which is used to create any local XLPageCookbook page.

Installation

Move publish.php into local/. Move the publish/ directory (which contains print.tmpl and print.css) to pub/skins/. Unlike some skins, the recipe will not work if you put publish.php into pub/skins/publish/.

Add the following line to local/config.php:

    include_once("local/publish.php");

It works best if you also install MarkupExtensions (makes use of LazyWebLinks), but should work without.

Note: I just checked without the MarkupExtensions and it does not work without it! StefanR

To use the script, add the following to any trail page:

    (:publish:)

This generates a numbered listing, using the trail indentation to control the numbering level. For an unnumbered report, use

    (:*publish:)

Press the publish button to publish the trail.

You can also publish a trail page other than the current page with the variants

    (:publish TrailPage:)

(for a numbered report) or

    (:*publish TrailPage:)

(for an unnumbered report).

If you use the WikiCalendar and set $enable_publish = true note that publish.php must load after wikilog.php.

Version 2.0.6 now follows the n=$FullName convention. Version 2.0.8 picks up title directives when publishing search results (requires SearchExtensions). Version 2.0.9 adds the ability to pick the pages on a trail to be published. For example [[PmWiki.DocumentationIndex?action=pubchoices]] turns the trail into a form with a checkbox for each stop. Thanks to Hans for the suggestion. Version 2.0.10 fixes a few bugs.

Generate a table of contents with links to anchors for each trail page in the published report. This is included in version 2.0.6 and above. If the 'Include this page' option is checked, the trail stops are formatted as links to anchors in the published page, rather than to the pages themselves. Also the <<|TrailPage|>> markup renders as a link to the start of the trail page, ie the top of the published page. It correctly publishes PmWiki.DocumentationIndex as a single, very long page. Thanks to Ciaran for suggesting this enhancement.

Comments:

In the script publish.php I found the code '&ensp' in several markups. This displays as a square by IE and a space by Mozilla. Perhaps this is a typo and should be '&nbsp'. Otherwise the script works fine. Jan-Henrik.

Mozilla is correct: it's an en space, which is one third of an em space (designated by the &emsp; entity ' '); cf. – – and — — jr

Request for improvement

Context: Use of graphs based on the graphviz cookbook which also works in pmwiki2.ObetaXX.

When using a printable view the graph is OK.
When using publish the graph-code is displayed: (:graphwiki .... :). PS ?
It's not clear why this is happening. Is there a link to a page showing this behaviour? Does it work correctly in Edit Preview, Page History and other views?

WikiTrail Inconsistency

Problem

The second observation rule for WikiTrails states, "A page is part of the trail only if the page link immediately follows the list markup.". It doesn't appear that this recipe strictly follows this rule. On one of the larger index pages that I have that setup a WikiTrail, I include several links at the top of the page that link to anchors further down the same page as well as some non-WikiTrail links. These links are prefaced with empty WikiStyles markup. While this causes the links to not be included as part of the WikiTrail, they are still included when the WikiTrail is published with this recipe.

When the sample index shown below is published, the NonWikiTrailPage will show up in the "index view" if the checkbox is checked and both the "Jump to..." links are listed as numbered headings in the published "page view". -Kurt Devlin February 06, 2006, at 09:42 AM

Sample Index

%rfloat%(:publish:)

!! Quick Links
* %%[[#A1 | Jump to Heading 1]]
* %%[[#A2 | Jump to Heading 2]]

[[NonWikiTrailPage]]

!! [[#A1]] Heading 1
* [[WikiTrailPage1]]
* [[WikiTrailPage2]]

!! [[#extract]] Heading 2
* [[WikiTrailPage3]]

Solution 1

From Kurt Devlin

NOTE: This is a less than optimal solution.

I edited my local copy of publish.php to change ExtractTrailStops() and the trial TOC code to use the foreach loop from PmWiki's trails.php

The line to use is:

  foreach(explode("\n",$trailtext) as $x) {
     $x = preg_replace("/\\[\\[([^\\]]*)->([^\\]]*)\\]\\]/",'[[$2|$1]]',$x);
     if (!preg_match("/^([#*:]+) \\s* 
          (\\[\\[([^|]*?)(\\|.*?)?\\]\\]($SuffixPattern)
          | (($GroupPattern([\\/.]))?$WikiWordPattern))/x",$x,$match))
       continue;
  ...

Solution 2

From jr

You might like to consider using the PageTableOfContents recipe to generate quick links to headings on the current page -- the (:toc:) directive generates links to the headings on the page and automatically inserts anchors for you.

The publish script is doing this deliberately. Consider the following markup:

    * some text
    ** [[link 1]]
    ** [[link 2]]

    * more text
    ** [[link 3]]
    ** [[link 4]]

The publish script uses the entire list to determine the structure of the output:

    1 some text
    1.1 link 1
    1.2 link 2

    2 more text
    2.1 link 3
    2.2 link 4

The version of the publish script included with the PublishPDF library is more advanced than the PublishWikiTrail script. In the latest version, it includes headings on the trail page in the structure, as well as list items. Thus the following will produce the same hierarchical structure:

    !!!some text
    * [[link 1]]
    * [[link 2]]

    !!!more text
    * [[link 3]]
    * [[link 4]]

This notion of a hierarchical output is not relevant when traversing a trail, but *is* relevant when publishing a page collection.

What I do to exclude unwanted list items from the structure is use the "invisible stop" from the MarkupExtensions recipe:

    `.* [[wiki link]]

This prevents items from matching for the trail, but they still get processed correctly -- the invisible stop is removed as part of the in-line markup processing.

How to wiki-style?

Hello there, the script works excellent with me. Indeed, it is a big relief since I was not able to achieve any result with PublishPdf (rendering ended with an error - I am struggling in an offline environment to learn and understand which style or markup causes the DTD inconsistency ...).
Anyway:

I am using customized styles which I define in a Group-Header (e.g. %define='note' p bgcolor='#ffffcc' border='1px dotted red' % ).
If I "publish", the customized style is gone by the wind, whereas any 'puristic' inline style definition (e.g. texttext %bgcolor='#ffffcc'% othertext) is published correctly.

Help! Groetjes - Rainer

pagelists?

Just wanted to second the comment about this being a great alternative to the publishPdf thingy. We fought for quite a while to get that to work. This works just as good and allows people to save as pdf themselves, or to an html page, or print out directly. Thanks for the recipe.

My question: is there any way to get this recipe to publish a pagelist? For example, I have a issues database where each issue has its own page. Creating a wiki-trail with a link to each page is not easy since I would have to maintain the links as issues come and go. Pagelists in pmwiki solve this by letting me basically list pages with any criteria i might have. Anyway to use a pagelist or search result to feed this publish recipe instead of a wiki-trail?

Thanks.

--Lordmundi

Hi,

This works well from me, but I would like to save the file as a PDF. Is there a way to feed this into the GeneratePDF recipe. Thanks Nigel

Contributor

User notes ? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.