Pagesetter 5.0 manual

Jørn Lind-Nielsen

Contents

Copyright (c) 2003-2004 Jørn Lind-Nielsen.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

See last chapter for full license.

Introduction

Pagesetter is a PostNuke module that allows the web site administrators to create their own types of publications. The goal is ultimately to be able to define all the kinds of publications that normally require different PostNuke modules. The list includes:

The screenshot shown here illustrates an example News item constructed with Pagesetter:

Features

Tutorial

Skip the reference and jump directly to the tutorial.

Credits

Printing This Manual

The CSS styles in this HTML has been carefully selected to generate a nicely formatted printout. This has although only been tested on the Internet Explorer 6.0. If you choose to print the manual then please remember to set the paper format to A4 portrait. You should have left and right margins set to 20mm.

Known bugs

The following features does not work (yet):

Permissions

Pagesetter works with five different access levels:

Readers
Users who are allowed to read Pagesetter publications.
Authors
Users who are allowed to submit new publications but do not have access to the list of existing publications.
Editors
Users who are allowed to submit new publications and have access to the list of publications.
Moderators
Users who are allowed to submit and delete publications, as well as moving them back and forth to the depot.
Administrators
Users who are allowed to create new publication types as well as performing other administrative Pagesetter tasks.
Remember that the order of the permission items is significant. PostNuke reads permissions from the top and downwards until it finds a match.

Permission instances are specified with regular expressions!

So in general you either have access to editing, or you don't—there is no in-between. But on top of the raw PostNuke permission Pagesetter adds it's own workflow system. Through this it is possible to specify who has access to what and when. The workflow system is able to handle such diverse setups as a Wiki framework (well, something that simulates it to a certain degree) and an enteprise level workflow with authors, editors and moderators. Read more in the workflow chapter.

The Pagesetter permission levels are mapped into the PostNuke permissions like this:

GroupComponentInstancePermission
readerspagesetter::tid:pid:Read
authorspagesetter::tid:pid:Edit
editorspagesetter::tid:pid:Add
moderatorspagesetter::tid:pid:Delete
adminspagesetter::tid:pid:Admin

In the table tid is used as the publication type ID and pid as the publication (instance) ID. You can use these to give access to specific subsets of the publications.

The special instance is '::' which matches both all publications and the generic test for access to the Pagesetter module. Here is a few examples:

GroupComponentInstancePermissionResult
All groupspagesetter::::ReadRead access for all groups to all publications.
Unregisteredpagesetter::4::NoneDeny access for unregistered users to all publications of type 4
Group Apagesetter::3::EditEdit access to publication type 3 for all in group A
Group Bpagesetter::2:(1|5|19):EditEdit access to publications 1,5 and 19 of type 2 for all in group B
My page adminpagesetter::1::AdminAdmin access for "My page admin" group to publication type 1

Permissions for Single Publications

The way that Pagesetter (and most other modules) uses the permission system can in some instances make it quite difficult to figure out a way to grant access to one single publication. For a publication ID P of type T you would expect to be able to match "pagesetter::" and "T:P:" for read and then follow it by a "pagesetter::" and "T::" for none, meaning "grant read access to specific publication and deny access to the remaining".

This could for instance be a News publication (item 7 og type 1)where you want a specific welcome message on the front page available for all unregistered users. But you do not want them to be able to read the rest. For this one would think of the following:

GroupComponentInstancePermission
Unregisteredpagesetter::1:7:Read
Unregisteredpagesetter::1::None

But this would not work! Pagesetter first checks with an empty publication item for access to the publication type as a whole. This means it tries to match "pagesetter::" and "1::" before any thing else. This does not match the first line, so access is denied even before we check for access to the single item.

What you must do is:

GroupComponentInstancePermission
Unregisteredpagesetter::1:7:Read
Unregisteredpagesetter::1:.+:None
Unregisteredpagesetter::1::Read

The third line ensures access to the publication type as a whole. The second line denies access to all item specific checks (those with something in between the colons). The first line grants access to the specific item.

Editing Publications

Instances of a publication, for instance News items as shown in the tutorial, are created and edited in the Edit window. This window consists of two main parts—the publication specific fields as defined by the system administrator and the meta data defined by Pagesetter. The publication fields part looks somewhat like this:

What you see is three different fields defined by the administrator of the web site. It is up to you to write whatever you find fitting for your kind of publication—in this case a News item describing some of the pleasantries of hiking Bornholm.

The meta data consists of the following fields, all described below:

Publish Information

Approval state
The approval state is an information about where the publication is located in the associated workflow. The possible states depends on the workflow setup, but the standard workflows uses states like "Preview" and "Approved" to denote the fact that the publication is ready for preview (by an editor) or actually approved by the moderator. The approval state can only be changed by one of the workflow actions available at the bottom of the page.
Online setting
This field indicates whether the publication is online or not, and thereby if it is visible on any of the publication lists or can be found by searching.
Publish Date
This setting specifies the first day a publication goes online.
Expire Date
This setting specifies the day a publication goes offline (it will not be available at the specified day).

Location

These settings categorizes the publication and defines where to find it.

Topic
The PostNuke topic in which the publication belongs.
Show in lists
Specifies whether or not the publication should be shown in the general list of this publication type. This can be usefull if you want some publications to be accessible through a menu or handcrafted URL only.
Language
The language in which the publication is written. The language influences when the publication shows up in the various lists and menus. The language must match the user's language in order to show up—or be set to "All".

Author Information

These settings holds who has written the publication and when.

Publisher
The PostNuke user name of the user who created the publication. This name cannot be changed.
Author
The name of the publication author. The creator's real name is inserted here—but may at any later time be changed to something else.
Created
The date of creation.
Last updated
Last updated date.

Setting Editor Defaults

It is possible to assign defaults for new publications via the URL as shown in the linking chapter.

Publication Types

Everything in Pagesetter begins with the declaration of a publication type. The publication type defines the set of fields that a publication may have, the name of the publication type, and a bunch of other things.

Pagesetter comes without any publication types pre-installed, so you will have to create your own. But a set of output templates for a News type is supplied—see the tutorial.

The publication type setup window looks like this:

The upper part lets you configure various things about the publication type as a whole. The lower part lets you add one or more fields to store publication data in. The fields in the upper part are:

Publisher
The name of the user who created this publication type.
Title
The name for this publication type. It is used to locate output templates that contains the name as part of the template file name. For this reason you must select a name that can be used as a file name.
Description
A short description of the publication type. It is not used for any thing else.
Enable PN-Hooks
Checking this checkbox will force Pagesetter to run it's output through PostNuke's hooks system. This enables commenting, scoring and other hook based features.
Workflow
The workflow configuration lets you define how complex a process you need for proof reading and approval of your publications. Pagesetter comes with three predefined workflows: "None", "Standard", and "Enterprise". The "None" workflow has no proofing or anything—publications are simply approved immediately upon submission. The "Standard" workflow is a two-step procedure with a moderator, and the "Enterprise" workflow is a three-step procedure with both editors and moderators. You can read more on workflows in a later chapter.
Number of publications to show in list
This lets you define how many publications you want to show up when this publication type is displayed on your PostNuke frontpage. It also applies to various blocks used by Pagesetter.
Sorting keys
These lets you define the default sorting order and direction of the publication lists. You must have committed your choice of fields before they are available in the key selections.

Field Types

Each field in a publication must have a type associated with it. Field types can be any of the following kinds:

string
A simple text string with no formatting. Text is entered in a one-line input field.
text
A simple text string with no formatting. Text is entered in a multi-line input field.
html
An HTML formatted text input. Text is entered via a what-you-see-is-what-you-get editor (on the Internet Explorer).
image
The URL to an image. The URL may either be entered manually or selected from any of Photoshare's albums.
bool
A checkbox.
int
Text field with validation for integers.
real
Text field with validation for real numbers.
time
Text field with validation for time (HH:MM).
date
Text field with validation for dates (YYYY-MM-DD). Uses a JavaScript date picker.
User defined list
Dropdown field with the items from the list.

Some examples of fields could be a headline (text), some instructions (html), payment (real), the starting date of some event (date) and so on. There is no restriction to how many fields you may choose to use.

Publication Setup

See the tutorial.

Lists and Categories

It is possible to define selection lists to be used as dropdown elements in the input or for categorization. An example of a selection list could be a selection of music media, for instance "CD", "DVD", "Tape", or "LP". A categorization could be book genres: "Fiction", "Art", "History", and so on. Lists can even be nested, so for instance you can define sub-genres for books "Fiction:Science Fiction" and "Fiction:Fantasy".

The lists are defined in this window:

It should be relatively simple; create a new list and then add the items you want in it. When all is as expected you commit the setup to the database.

The category fields are:

The list can afterwards be used for one or more fields in the publication types. Just select the list from the field type dropdown in publication setup window.

Templates

The output templating system uses a set of template files for each publication type and depends on the PostNuke .75 pnRender system (see installation guide). The template files are stored in pagesetter/pntemplates/... and they are named after the publication name like "PubName-format.html" where format depends on the situation.

Pagesetter uses the following template formats (here an example is shown in the parenthesis):

list (News-list.html)
The compact view of a publication when shown in a list.
list-header (News-list-header.html)
A template shown before a list.
list-footer (News-list-footer.html)
A template shown after a list.
list-single (News-list-single.html)
This single template takes the place of list, list-header, and list-footer in case no list-header template is found. It is not able to be cached though.
full (News-full.html)
The full view of a publication.
print (News-print.html)
The full view of a publication when shown as "Print this" without PostNuke frames.
xml (News-xml.html)
Full view of publication as XML. Used for the xmllist and xmlpub functions that adds a "Content-Type: text/xml" to the HTTP header.

Template Variables

The templates may refer to all of the user defined fields and most of the core meta data (author etc.). Template variables are inserted using {$name} or <!--[name]--> where "name" is the name of a variable. The braces are used here for simplicity but the best solution is to use the HTML comments style since this is compatible with various HTML editors.

The user defined fields are simply refered to by their field name, whereas the meta data is refered to through the "core" object as {$core.name} where "name" may be any of the following core fields:

id
A unique integer value identifying the publication.
tid*
The publication type ID.
format*
The template format name, e.g., "list" in "News-list-header.html".
author
Name of the author as set in the publication editor.
title
Copy of the value from the specified title field.
topic
Associated topic description. This is a struct with the following fields: id, name, text, and image. Use for instance like <!--[$core.topic.name]-->.
creator
Name of the person who actually created the publication.
created
The time stamp of when the publication was created.
lastUpdated
The time stamp of when the publication was last updated.
fullURL
The URL to the full display of the publication.
printThis
A complete link to "Print this" with description.
printThisURL
The URL to "Print this".
sendThis
A complete link to "Send this" with description.
sendThisURL
The URL to "Send this".

The items marked with * are also available in list headers and footers.

Using list items

When refering to a list or category item you must further specify which property of the list item you want. You can choose between the title, the qualified title (with parent items prefixed), the value, or the description. The properties are accessed as sub-values of the field (just like the properties of the core variable). The possible list properties are:

title
Item title.
fullTitle
Qualified item title. The parent item titles are prefixed with colon as separator. For instance Fiction:Fantasy.
value
Item value.
description
Item description.

For instance, say you have a category field in your publication type called bookType. It is defined as a list called typesOfBooks. To add the title of the category field to your template, use <!--[$bookType.title]-->

If you need to generate a select-box for a specific list field then you can use the pagesetter_listSelector Smarty plugin like this:

<form action="...">
 Select Category: <!--[pagesetter_listSelector name="categoryInput" field="category"]-->
 ...
</form>

This will produce a select input with the name "categoryInput" based on the field "category". The select input will show item titles and use item IDs as values.

Using Pageable Fields

A field that has been enabled for multiple pages is accessed as an array of pages, so you will have to specify which page to show. The page number is passed in the URL as the query variable page which can be accessed like $core.page. You can get the number of pages as $core.pageCount.

The template system offers a "pager" generator function named pagesetter_pager. The pnRender module already offers different kinds of pagers, but I never got them to work with Pagesetter. Besides that this one is easier to use with Pagesetter items. To insert the pager you add <!--[pagesetter_pager]--> to the template. The function accepts the following parameters:

page
The current page number—zero based for look-up in page array. If left out then $core.page is used.
pageCount
The number of pages available. If left out then $core.pageCount is used.
baseURL
The base URL of the view (link to page). If left out then $core.baseURL is used.
next
A piece of HTML to insert as the "Next page" link. Default is ">"
prev
A piece of HTML to insert as the "Prev page" link. Default is "<"
separator
A piece of HTML to insert as the separator between page number. Default is &nbsp;
pageClass
A CSS class name to include in the anchors of the prev/next links.
thisPageClass
A CSS class name to put the current page number into using a <span> tag.
Example template:
Page <!--[$core.page+1]--><br>
<!--[pagesetter_pager]-->
and a bit more advanced example:
Page <!--[$core.page+1]--> of <!--[$core.pageCount]--><br>
<!--[pagesetter_pager prev="<img src='leftArrow.gif'>"
                      next="<img src='rightArrow.gif'>"]-->

Showing Hit Counts

Hit counts are refered to as $hitCount$ and not {$hitCount}. This is because normal template variables are cached, which means you always see the same value until the page is edited again. This would freeze the hit count—thereby rendering it completely useless. So $hitCount$ is replaced in the text after the cached template is fetched.

Beware that this means a user can insert $hitCount$ anywhere in the publication!

Showing "Edit This" Link

Such a link can be added with the $editThis$ variable and not {$editThis} for the same reason as the hit count—we do not want to cache this since it depends on the user's permissions.

Single and Multiple List Templates

The list view used in Pagesetter allows you to display a set of publications through a template. The can be done with either a single template, in which you must iterate through the elements yourself, or with a header/list/footer combination of templates that allows you to display one publication alone in a template, which is then invoked by Pagesetter multiple times.

Single Template

If template named x-list-header.html can be found then x-list-single.html will be used instead. This template will be passed an array named publications which contains one entry for each publication in the list. Each array entry contains exactly the same variables as the ones passed to the multiple list template. This allows you to finetune the exact positioning of the publications, at the cost of some performance since the complete list output cannot be cached.

Checking on existence of x-list-header.html instead of x-list-single.html makes it possible to specify different template formats than "single".

Example:

<h1>My Frontpage</h1>

<table style="width: 70%">
  <tr>
    <td style="width: 50%">
      <h2><!--[$publications[0].core.title]--></h2>
      <!--[$publications[0].teaser]-->
    </td>
    <td style="width: 50%">
      <h2><!--[$publications[1].core.title]--></h2>
      <!--[$publications[1].teaser]-->
    </td>
  </tr>
  <tr>
    <td style="width: 50%">
      <h2><!--[$publications[2].core.title]--></h2>
      <!--[$publications[2].teaser]-->
    </td>
    <td style="width: 50%">
      <h2><!--[$publications[3].core.title]--></h2>
      <!--[$publications[3].teaser]-->
    </td>
  </tr>
</table>

Multiple Templates

If a template named x-list-header.html can be found then this will be displayed first. After this the template named x-list.html will be displayed one time for each publication in the list. At last the template named x-list-footer.html will be displayed. This reduces the possibilities for finetuning the layout, but it improves performance since the output of each of the publications can be cached.

Theme Specific Templates

With the pnRender system it is possible to specifiy theme specific templates. Just place your templates in the structure shown here (the top theme directory is PostNuke's main theme directory):

Template Operations

You can do a bunch of stuff with the Smarty template system. Please read the documentation at smarty.php.net as well as the pnRender documentation when it becomes available.

Here's anyway a few examples:

  <!-- Uppercase the title -->
<h2><!--[$title|upper]--></h2>

  <!-- Truncate the topic to 40 characters use ... at the end -->
Topic: <!--[$topic|truncate:40:"..."]-->

  <!-- Produce category bread crumbs using "separator.png" image as separator
       instead of colons in the qualified title of a list item -->
Genre: <!--[$genre.fullTitle|replace:":":" <img src='separator.png'> "]-->

  <!-- format a literal string -->
<!--[$"now"|date_format:"%Y/%m/%d"]-->

Auto Generated Templates

It is possible to auto generate missing templates. Go to "Publications:Create Templates" in the menu. Here you find a list of your publications and the possibility to mark which templates to generate. The new templates are based on the templates named __template-... so you can modify these to suite your own needs.

You need to make the pntemplates directory writable by all for this to work!

pnRender Plugins

If you look into the pagesetter/pntemplates/plugins directory you will find a set of predefined plugins for Pagesetter. You will have to read the PHP code to get the documentation so far. But here's a short list:

pagesetter_pager
Generates a "<< 1,2,3, ..., >>" set of links for selecting a page in a multipaged publication.
pagesetter_listBrowser
Generates a tree based on a category field. Just like the castegory based menu block.
pagesetter_inlinePubList
Creates a templated list of publications to be inserted on your page.
pagesetter_listSelector
Generates a HTML select tag for selection of items from a category field.
pagesetter_pubPager
Generates a prev/next link set for browsing through a list of publications.
pagesetter_createFilter
Creates a filter for input to the Pagesetter API function getPubList.
var
Internally used to auto-create templates.
bool_format
Formats a bool value as one of two strings.

Linking

Here is a list of the various Pagesetter URLs you can use:

List: .../index.php?module=pagesetter
The basic link used for Pagesetter on the frontpage. This link shows the Pagesetter default publication list.
List: .../index.php?module=pagesetter&tid=T&topic=P&lang=L
The same as the above link but with various extra modifiers. You can specify which publication type you want to show the list for by setting tid to the type ID. In the same way you can specify the topic ID as well as language (otherwise the current language is used to filter the list). All the modifiers are optional and can be mixed as necessary.
View.../index.php?module=pagesetter&func=viewpub&tid=T&pid=P
This is the link for viewing a specific publication of a specific type. You need to set tid to the publication type ID and pid to the publication ID.
Print: .../index.php?module=pagesetter&func=printpub&tid=T&pid=P
This is the link for showing a publication as "printable"—which means without the PostNuke frameset and with a special template. The tid and pid parameters works as above.
Edit: .../index.php?module=pagesetter&func=pubedit&tid=T
This is the link for the creation of a new publication of the publication type specified in tid. You can use this link for a "Submit Publication" menu entry like the standard PostNuke "Submit News" link.
Edit: .../index.php?module=pagesetter&func=pubedit&tid=T&goback=1
Edit link as above but redirect user to refering page after edit is completed.
Edit list: .../index.php?module=pagesetter&func=pubList&tid=T
This is the link for the editor's list of publications and is used for managing all the publications. As usual the tid parameter identifies the publication type ID.

Here is a short description of the various URL parameters:

tid
Publication type ID.
pid
Publication instance ID.
topic
PostNuke topic ID.
lang
PostNuke language ID.
tpl
Template name for overriding default.
pubcnt
The number of publications to show on one page. If left out then the publication type default is used. If set to zero then all publications are shown.
goback
Used to redirect the user back to refering page after editing. Set it to 1 to enforce this redirection. If this parameter is not set the user is redirected to the editors list of publications.

Here you can see which parameters you can use for the different functions (with less used functions included):

Function tid pid topic lang tpl pubcnt Description
None x x x x x Normal publication list
viewpub x x x Full publication display
printpub x x x Full publication display, no frames
dumppub x x x Full publication display, no surrounding html tags
xmlpub x x x Full publication display, adds content-type text/xml
pubedit x x Edit publication
publist x Editor's list of publiations
printlist x x x x x Display list of publications, no frames
dumplist x x x x x Display list of publications, no surrounding html tags
xmllist x x x x x Display list of publications, adds content-type text/xml

Here is a list of the templates required for the various options:

Function Header/footer Def. Template Description
None x list Normal publication list
viewpub full Full publication display
printpub print Full publication display, no frames
dumppub print Full publication display, no surrounding html tags
xmlpub xml Full publication display, adds content-type text/xml
pubedit - Edit publication
publist - Editor's list of publiations
printlist x list Display list of publications, no frames
dumplist x list Display list of publications, no surrounding html tags
xmllist x list Display list of publications, adds content-type text/xml

Sorting

With Pagesetter you can sort the various lists of publications via restrictions in URL. To do so you specify "orderby=field-list". The list of fields is separated by commas and you refer to the field names as you would do in a template. Either as fieldName or as core.coreFieldName. The default sorting direction is ascending, but descending can be specified with a ":desc" appendend to a field name.

Example: to order by author (descending) and then by title you would specify orderby=core.author:desc,title.

Filtering

It is also possible to filter the various lists of publications via restrictions in URL. To add a filter you simply specify "filter=expr" in the URL where expr is a filter expression.

Filter expressions are written as comma-separated lists of filter terms where each term consists of a field name, an operator, and an operand separated by colons. A single filter combines all it's expressions using an AND-operator (making it a conjunction).

The possible filter operators are:

eq
Equal.
ne
Not equal.
lt
Less than.
le
Less than or equal.
gt
Greater than.
ge
Greater than or equal.
like
Using database's LIKE operator to match operand as '%operand%'.
null
Test for field being NULL. Should be used without an operand—like filter=FieldName:null.
nottnull
Test for field being NOT NULL. Should be used without an operand—like filter=FieldName:notnull.
sub
Test for a list field being equal to or an descendant of the operand. Only valid for list fields.

The right hand side operands in a filter expression may contain "@now" which will expand to the current date. This may although not be that usefull since there is no support yet for plus or minus operators.

Beware that URL variables are separated with ampersands "&". Ampersands are therefore also used to separate different filters on the URL. But multiple filters are OR-ed together which is opposite the usual interpretation of the ampersand!

Multiple filters can be combined on the URL using "filterN=expr" where N is an integer starting from 1. Multiple filters are combined using an OR-operator (putting the whole filter language in a disjunctive normal form).

Here is a few examples:

filter=title:like:pagesetter
Find all the publications where the title field contains the word "pagesetter".
filter=age:ge:18
Find all the publications where the age field is greater than or equal to 18.
filter=age:ge:18,country:eq:DK
Find all the publications where the age field is greater than or equal to 18 and the country is equal to "DK".
filter1=age:ge:18,country:eq:DK&filter2=country:eq:NO
Find all the publications where (1) the age field is greater than or equal to 18 and the country is equal to "DK", or (2) the country is equal to "NO".

Categories used for books.

Now assume we have a book category as shown in the box and use this in a book review publication with a field named "category" (using the category list type of course). Then we can select various sub-sets of the reviews with these examples:

filter=category:eq:8
Find all the reviews of category "Fiction"—but not sub-sets of that.
filter=category:sub:8
Find all the reviews of category "Fiction" and any sub-sets of that (Science Fiction and Classics).
filter1=category:sub:11&filter2=category:eq:23
Find all the art(11) and drinks(23) reviews, but not non-alcoholic drinks (since we use the eq operator instead of sub operator).

It is furthermore possible to match all items using the special list value "top", for instance in a filter like "filter=category:sub:top".

Indirect Operands

Filtering using input from web form.

The above setup is fine as long as you are using hard-coded URLs. But when you want to let the user enter something in a form and then filter by that, you need to refer to other URL variables in the filter. Assume for instance you want to filter a keywords field using the like operator based on something the user enters in a form. The user input is entered in a HTML input field named "keyword". Now we can refer to the URL variable as "$keyword" in a filter like "filter=keywordField:like:$keyword".

An example template using this feature could look like this for the list-header template of a knowledge base:

<div class="pn-pagetitle">Knowledge Base</div>

<form action="<!--[pnmodurl modname="pagesetter" tid=$core.tid]-->" method="POST">
 <table>
  <tr><td>Keyword:</td><td><input type="text" name="keyword"></td><tr>
  <tr><td><input type="submit" value="Update"></td><tr>
 </table>
 <input type="hidden" name="filter"
        value="keywordField:like:$keyword">
</form>

<ul>

Setting Defaults for Editor

You can assign default values to the editor when creating a new publication. Simply add set_xxx=yyy" to the URL and the user defined variable xxx will be set to the default value yyy instead of being empty. Use category ID for category fields.

Example: assume you have a News publication and a Project publication. The News publication can be categorized by some category. The same goes for your projects. On each project page you can now add a "Submit Related News" link that presets the category of the News item to that of the current project. To do so your Project template must contain something like this:

<div class="pn-pagetitle">Projects</div>

...

<a href="<!--[modurl module=pagesetter func=pubedit tid=T
                     set_category=$category.id]-->">...</a>

...

PostNuke Features

Waiting Block

This block displays submitted publications waiting for approval. Since "waiting for approval" is a term that cannot be hardwired into the system, due to the flexible workflow system, you must configure which workflow states that should be considered "waiting". For each publication type you will find a list of checkboxes representing workflow states—each of these can be checked to mark that state as a "waiting" state.

You can create multiple Waiting blocks with different definitions of waiting states. By using PostNuke's permission system for the blocks you can then have different Waiting block setups for different groups of users.

List Block

This block shows the title of the top N publications of a specific type—for instance the last ten News items. The list is the same as shown when using Pagesetter as the frontpage module and the ordering as well as number of items depends on the publication type.

The List block uses the template named "TypeName-block-list.html" (for instance "News-block-list.html") to render each of the publications. If this template does not exist then "Default-block-list.html" is tried and if even this is non-existent "Default.html" is used.

Old Stories Block

You can setup a block for "old stories" using the "List" block described above. The idea is that the front page normaly shows N items, so the "old stories" block should show the next X items after N. To do so you set the field "First publication number" to N and "Number of publications" to X. To style the list closer to the original PostNuke "old stories" block, you can specify the template to use as "list-old-block", which is a supplied Pagesetter template for "PN-News" publications.

Publication Block

This block shows a specific publication using a template of your own choice. You need to select a publication type to show and then write the publication type ID yourself (so far no point-and-click selection). The template name must not include publication name and .html extension. So for a "News" publication you should just write "full" to use the "News-full.html" template.

Category Based Menu Block

Categories used to generate a menu block.

The category based menu block generates a nested list of menu entries based on the items in a specific category. Clicking on a menu item takes the user to a list of all publications associated with that category item or any sub-category item.

Configuring

To set up the menu you need to specify the following attributes:

Publication type
The publication type that this menu should show items from.
List field to base menu on
This is the name of the publication field that this menu is based on. The field must be an existing field and be associated with some category (list). No error checking is done on this input.
Top item ID
If you consider the nested category structure as a tree then this is the ID of the category item that will be used as the root item for the menu. This allows you to only show a sub-set of the items. No error checking is done on this input. Leave it empty to get all items.
Maximum numbers of sub-levels to show
This specify how deep a nesting into the category structure the menu will show items from.
CSS class name for list
Any CSS class name of your choice. It will only be added to the top level <ul> HTML tag. You can find sample CSS rules in pagesetter/examples/News/styles.css.

PostNuke Hooks

Pagesetter is fully hook aware (with hooks for both display, transformation, create and delete). This means you can enable auto links, comments, rating and other nice hooks for your publications.

To enable hooks you must do two things. First hooks must be enabled for Pagesetter in general. This can be done in the standard admin::modules section where you click "edit" for Pagesetter. This will bring you to the hooks enabling.

The next thing is to enable hooks for your publication type. This is done in the checkbox "PN-Hooks" found in the publication type configuration.

PostNuke Searching

Pagesetter complies to the standard interface for PostNuke searching, which means you can search any of your publication fields for "all" words in a query as well as "any" word in a query.

You may have to install the search file yourself (this depends on the zip-file structure). Copy the file html/modules/pagesetter/pnsearch/pagesetter.php into html/includes/search and you are ready to use the standard search module.

One of the things you often see in a PostNuke theme is a small search input field in the top bar. If you want to enable Pagesetter in this you must add a (hidden) input field in the web form with the properties type set to "hidden", name set to "active_pagesetter", and value set to "1".

An example taken from the standard "PostNukeSilver" theme looks like this:

echo  '<form action="modules.php" method="post">'
     .'<input type="hidden" name="name" value="Search">'
     .'<input type="hidden" name="file" value="index">'
     .'<input type="hidden" name="op" value="modload">'
     .'<input type="hidden" name="action" value="search">'
     .'<input type="hidden" name="overview" value="1">'
     .'<input type="hidden" name="active_stories" value="1">'
     .'<input type="hidden" name="active_pagesetter" value="1">'
     .'<input type="hidden" name="bool" value="AND">'
     .'<input name="q" type="text" size="15">'
     .'</form>';

Extra Features

RSS Feeds

Pagesetter can generate RSS feeds using the XML dumper and an appropriate template. The URL for this is:

.../index.php?module=pagesetter&func=xmllist&tid=T&tpl=RSS

This assumes the RSS template is in the file Name-RSS.html. An example template PN-News-RSS.html is supplied with Pagesetter. This file needs some modifications related to the feed title, image and description.

Title-Hack

It is possible to get the title of a Pagesetter publication put into the browser window's title bar using Jöerg's "Title-hack". Read more at http://sourceforge.net/projects/lottasophie.

FEProc Integration

Users that needs to submit something through FormExpress/FEProc needs to have "Author" permissions to Pagesetter. This will enable them to submit new publications but it will not allow them to access other publications.

FEProc is a PostNuke module for processing of forms data. It depends on FormExpress for the creation of web forms and then allows the admin to process the incoming data using various back-end handlers. FEProc comes with built-in handlers for e-mail notification, data transformations, validation rules, and much more—except a generic database API. With a Pagesetter handler for FEProc that problem is now solved.

With the combination of FEProc/Pagesetter you can let

FEProc be used for data input and validation and Pagesetter for storing the result. This can for instance be used in a setup where users can register for some event using FormExpress, get an acknowledge mail sent using FEProc, while at the same time you store a copy of the registration in Pagesetter.

In FEProc you combine various handlers by stringing them together to form a data pipe-line or set as FEProc calls it. Each instance of the handlers is called a stage and you may configure the stages in various ways depending on what kind of handler it is an instance of. A mail handler may let you define the recipient address, a display handler may let you define a template, and so on. When data flows through the various stages it may be modified or transmitted to some external handler and then passed further on to the next stage. Each stage defines two ancestor stages—a success stage and a failure stage. Depending on the result of the current stage, data may be transferred to either the first or the second ancestor stage.

Pagesetter FEProc Handler

Remember to use FEProc's import manager to first import the Pagesetter handler before you can use it.

The Pagesetter handler lets you store previously entered data from a web form in a new publication instance of any type. The handler lets you pre-configure the publication type, the author name, and a topic for the new instance. The rest of the core attributes are hard-coded. All of the user defined fields are taken from any forms data entered before the Pagesetter handler is executed. To get the data from a web form you need to name the form fields exactly like the Pagesetter field you want it to be stored in.

Here is a list of the attributes you can set for a Pagesetter FEProc stage:

Pagesetter type ID
The ID of the publication type you want to create an instance of when storing the FEProc data. Remember you must have an exact one-to-one match between the Pagesetter field names and your FormExpress field names.
Topic ID
The ID of the topic you want you publication associated with. This is currently hardcode and cannot be set from any form data. Use -1 for no topic.
Author
The name you want to store as the author for the created publication. This can be edited in the publication later on. The stored Publisher name/ID will be the PostNuke user ID of the person who initialized the publication creation through FEProc.

Example - An Event Registration Setup

In this example we want our users to register for our "Advanced PostNuke" course. To do so they must submit their name and level of experience with Pagesetter. The level can be "Novice", "Administrator", or "Developer", which we want submitted as a Pagesetter list value.

For this we create a publication type named "Registration" with the fields "Name" and "Expirence", but to do so we must also create a list type, which we will name "Experience". The list setup should be like this:

The publication setup should be:

So now we have somewhere to store the registration. Next thing is to create a FormExpress form. Open FormExpress' admin part and create a form with a text input named "name", and a list input named "experience". The values of the list field must be the list IDs for the Pagesetter list items (14, 15, and 16). The setup should be as in the following screen shots.

Here is the FormExpress setup:

Here is the FormExpress list field setup:

Now we have all we need to string a complete FEProc pipe-line together. Open FEProc's admin part and create a new set. This set should contain the following stages:

This can be obtained as follows:

  1. Create the Error Display stage. The template should contain a reference to ${message:error} in order to show Pagesetter error messages.
  2. Create the Success Display stage.
  3. Create the Pagesetter Store stage. Set "next success" stage to stage 2. Set "next error" stage to stage 1.
  4. Create the Mail stage. Set "next success" stage to stage 3. Set "next error" stage to stage 1.
  5. Create the FormExpress Input stage. Set "next success" stage to stage 4. Set "next error" stage to stage 1.
Now you are ready to accept registrations for your course!

Workflows

The online Encyclopedia "Wikipedia" describes a workflow like this:

Workflow is the operational aspect of a work procedure: how tasks are structured, who performs them, what their relative order is, how they are synchronized, how information flows to support the tasks and how tasks are being tracked. [WikiPedia www.wikipedia.org]

In Pagesetter we can control where in the workflow a publication is located, what kind of actions you can perform on it, when it can be done, and who can do it. The location is defined by the publication's state, which for instance can be "Preview" for something in preview for an editor. The state is something visible and can always be seen on the editor's list. The actions can be things like "Submit", "Accept", or "Reject", all of which triggers some code that modifies the publication. A publication can only change state as a result of a workflow action. You never edit the state directly.

Each of the workflows may have some configuration settings that can be set through the menu Configuration::Workflow. The standard settings are things related to notification mails to be sent when a publication changes state during the workflow. The most obvious of these are the mail addresses of the editors and moderators that should be informed of new content arrivals.

The workflow system has been designed to let the administrator add his own workflow without modifying the existing ones. This is done through an XML file in the "workflows/custom" directory. A thorough description of how this is done can be found in the Workflow Manual in "docs" directory.

Remember that, no matter how clever a workflow you might create, everything begins and ends with your editors. The workflow in it self is only a technology, it is not and will never be a substitute for good writers.

Standard workflows

None

Allows Authors to create pre-approved documents. Not much to this one.

Standard

Allows Authors to submit a publication. It then requires an Editor to approve it.

Enterprise

Adds an additional approval step to the Standard workflow. An Author submits. An Editor accepts or rejects. A Moderator approves or rejects. A Moderator can also take publications offline and then put them back online.

Wiki

This workflow gives Authors full access to the publications. Every time someone updates a publication, a new version is built and a notification email is sent. All changes to all publications are logged. Every document is pre-approved.

The use of Wiki for the name refers to the "edit-by-all" and revision control features. There is no support for the normal Wiki notations like using !/!!/!!! for headlines .

MyWiki

This workflow gives Authors full access to their own publications only. Every time someone updates a publication, a new version is built. All changes to all publications are logged. Every document is pre-approved. No reason to mail someone since it is assumed that you edit your own pages only.

This is the workflow you should use if you want to allow your users to have their own set of pages they can manage. If for instance you have a home-garden site and want you users to present their gardens on your site then do as follows:

  1. Create a publication type named "Gardens" (or similar) and add the fields you need.
  2. Assign the "MyWiki" workflow to this publication type.
  3. Check (enable) the access to editing of own pages.
  4. Make sure your users have "author" access to this publication type. This can be done with a permission line in PostNuke like this: "YourGroup | pagesetter:: | T:: | Edit" (where T = type ID).

With this setup your users should be able to create new pages as well as edit their own pages only. You need to give them a URL to the "edit publication" feature (see the linking section).

Customisation

Input Forms

Pagesetter does not only let you define your own publication types and their presentation. It also lets you define both workflow, as described in the previous chapter, as well as the input forms used for editing your publications.

The idea is to associate different input form layouts with different workflow states. To do so you must create an XML layout file with a name related to the workflow name and place it in a publication type specific directory. The filename must be made up like <StateName>FormLayout.xml and be placed in a directory named publications/<PubTypeName>. The filename used for a new creation (yet without a workflow state associated with it) is newFormLayout.xml.

So to specify the form layout for the "waiting" state of a "PN-News" publication you would have to create a file named publications/PN-News/waitingFormLayout.xml.

The structure of the layout XML file is described in the Guppy Development manual in the same directory as this manual is placed in. This manual will at some point be a complete Guppy manual, so you only need to read the chapter on "Form Layout"—the rest can be ignored.

In the examples directory you can find a newFormLayout.xml example file to use for standard PN-News items. Just copy it to publications/PN-News—you probably need to create the layout directory yourself.

HTMLArea Editor

The editor can be customized with a callback JavaScript file placed in the publication type specific directory. The filename must be named editorsetup.js and be placed in a directory named publications/<PubTypeName>. For instance publications/PN-News/editorsetup.js

In the callback file you can place two callback functions named HTMLAreaConfigSetup and HTMLAreaEditorSetup. The first one will be called when the configuration object has been loaded by Pagesetter (and passed the config object). The second one will be called when the editor object has been created (and passed that object). Here is an example implementation that adds a CSS class selector and HTMLArea's right-click context menu:

  // Load various plugins on load of the setup script
HTMLArea.loadPlugin("ContextMenu");
HTMLArea.loadPlugin("CSS");


  // This function is called (if it exists) after the editor configuration is created,
  // but before the editor itself is created
function HTMLAreaConfigSetup(config)
{
    // Here you can call config.registerButton, change the toolbar, and much more ...
    // See HTMLArea's own documentation
}


  // This is called with the editor right after it has been created
function HTMLAreaEditorSetup(editor)
{
    // Register the plugins
  editor.registerPlugin(ContextMenu);
  editor.registerPlugin(CSS, { combos: [{label:"CSS", options:{a:"classA", b:"classB"}}] } );
}

Post Submit Handler

In some cases it might be usefull to modify the data submitted after editing a publication. This can be accomplished with the addition of a single extra custom workflow operation. Please check the workflow manual for further instructions (it is not possible to modify/add data before opening the editor).

Tutorial

Creating a Publication Type

Make sure you have admin rights on your PostNuke site and then goto the Pagesetter administration page. Here you will see an empty list of publication types. Except for the two publications in this demo it should look like:

Now click "New Publication Type" which will bring you to this window:

Here you must fill out the name of the publication and add your fields. The field description is accessible as a "on-mouse-hover" hint when editing your publications.

The sorting keys will be empty until you have committed some fields.

Do not press "Commit" before you are satisfied with the result!

Use the green and red +/- symbols to add and delete fields. Make sure you name everything exactly as you see it in the image (description text is unimportant).

The title radio button indicates which field to use as title field in the various Pagesetter lists. The multiple pages checkbox allows you to define which field the user may insert page breaks in. Only one field may be selected for multiple pages, but none need to be so. Page breaks can be inserted using the editor button for it or inserted manually with a <hr class="pagebreak"/> tag. The templating system then ensures the field is split into pages separated by that tag

The "List Setup" settings specify sorting order and such like for this publication type when an overview is requested—for instance when Pagesetter is chosen as the frontpage module in PostNuke's admin settings.

The sequence of the fields does also define the sequence in which they are presented when creating a new publication instance.

Now you are ready to submit the publication type to the database. Press "Commit" and you are done.

Creating a Publication Instance

Now that we have a publication type available (News) we should start publishing something. Select the "New" link in the publication types window:

This will bring you to the "Publication Edit" window:

Entering the text should be straight forward. The image URL can be selected from Photoshare (if installed) by clicking the "..." button.

Now press "Save" and you are done and will be brought to the publication list:

If you have named all your fields correctly then you should be able to view your new publication through the pre-installed templates. Click the view action and you should see:

Templates

The template used to display your data is called pntemplates/PN-News-full.html. As you can see the name consists of the publication name concatenated with a dash and a template format name (in this case "full"). If you open the file you will see something like:

<div style="width: 500px;">

<div class="pn-title"><!--[$title]--></div>
<div class="pn-sub">By: <!--[$core.author]--> (<!--[$core.creator]-->)
<!--[$core.lastUpdated|date_format:"%Y.%m.%d"]--></div><p>

<table>
 <tr>
  <td valign="top">
   <!--[$text[$core.page]]--><br>
   <!--[if $core.pageCount > 1 ]-->
    Page: <!--[pagesetter_pager]-->
   <!--[/if]-->
  </td>
  <td valign="top">
   <!--[if $image != "" ]-->
     <img src="<!--[$image]-->" width="200" alt="<!--[$imagetext]-->" title="<!--[$imagetext]-->"><br>
     <i><!--[$imagetext]--></i>
   <!--[/if]-->
  </td>
 </tr>
</table>

<p>

<table width="100%"><tr>
<td><!--[$core.printThis]--> | <!--[$core.sendThis]--> | Hits: $hitCount$ | $editThis$</td>
<!--[if $core.pageCount > 1 ]-->
 <td align="right">(Page <!--[$core.page+1]--> of <!--[$core.pageCount]-->)</td>
<!--[/if]-->
</tr></table>

</div>

(the html presented is not the most correct with respect to accessibility and xhtml compliancy)

The <!--[]--> HTML comments contain code for the pnRender templating system. Basically you can put $fieldName into them to show your publication fields, but more complex stuff like switching statements and for-loops can be added too.

The variable name $core is predefined by Pagesetter and contains core information about the publication like author and creation date.

Do not edit the template directly. Copy it instead to a theme specific template and put it into your themes directory as described in the template chapter.

Read more about templates in the Template chapter.

Putting the News on the Frontpage

If you want to show your News items on the frontpage of your PostNuke installation, you need to find the admin section of PostNuke and then go into the settings section. Here you find a dropdown somewhere where you can select Pagesetter as the frontpage module.

But before that you need to tell Pagesetter which publication type to show on the frontpage. Go to the general settings of Pagesetter:

and select the News publication type for the frontpage:

If everything goes as expected you should be able to see the News list on the frontpage (thanks to www.postnuke.dk for design inspiration):

Extra Tools

Importing Data

Importing From PostNuke News

Pagesetter offers the possibility to import all of your existing news items into a new publication type. Select Tools:Import from the menu. Then click on the "Import News" button and you are done! You can check the "Add image field" in order to get a selectable image and image text associated with your news items.

If you have many news items then you may have trouble doing the import in the time allocated for your PHP script on the web server. If you have any influence on this factor then make sure your script have enough time. Otherwise, just try and see what happens, it probably works.

The new publication type will be named PN-News, comes with a full set of predefined templates named accordingly, and have the main text field converted to a multi-page field. The import does not import news categories.

If your new(s) items do not show up in the list, then check the language, "include in lists", approval state, and online status of the missing items.

You must also set the publication list ordering in order to sort descending by creation date.

The import cannot import the comments. This is impossible since Pagesetter have no notion of a "comment". It only knows "Hooks" which can be used, among other things, for comments.

Importing From ContentExpress

Pagesetter offers also the possibility to import all of your ContentExpress pages into a new publication type. Select Tools:Import from the menu. Then click on the "Import ContentExpress" button and you are done!

The new publication type will be named CE, comes with some predefined templates (full and print) named accordingly, and have the main text field converted to a multi-page field. The import does not import categories.

If your new items do not show up in the list, then check the language, "include in lists", approval state, and online status of the missing items.

Importing Pagesetter Publication Types

Pagesetter can read a publication type configuration from an uploaded XML file and create a new publication type based on that data. Beware the a new publication type is created from the file, and any categories found in the XML file will also be created as new categories. So the current implementation does not allow you to update an existing publication type.

Select Tools:Import from the menu. Then select an XML schema file to upload and click "Import XML Schema".

Exporting Pagesetter Publication Types

With Pagesetter you can export the setup of a publication type as an XML file. This file will be self containing with both the publication setup and the categories needed for it. Select Tools:Export to create the export file.

GNU Free Documentation License

		GNU Free Documentation License
		  Version 1.2, November 2002


 Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.


0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.

This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.


1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The "Document", below,
refers to any such manual or work.  Any member of the public is a
licensee, and is addressed as "you".  You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.

A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject.  (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.

The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.  A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text.  A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification.  Examples of
transparent image formats include PNG, XCF and JPG.  Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".)  To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.


2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.


3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.


4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct
   from that of the Document, and from those of previous versions
   (which should, if there were any, be listed in the History section
   of the Document).  You may use the same title as a previous version
   if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
   responsible for authorship of the modifications in the Modified
   Version, together with at least five of the principal authors of the
   Document (all of its principal authors, if it has fewer than five),
   unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
   Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
   adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
   giving the public permission to use the Modified Version under the
   terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
   and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add
   to it an item stating at least the title, year, new authors, and
   publisher of the Modified Version as given on the Title Page.  If
   there is no section Entitled "History" in the Document, create one
   stating the title, year, authors, and publisher of the Document as
   given on its Title Page, then add an item describing the Modified
   Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
   public access to a Transparent copy of the Document, and likewise
   the network locations given in the Document for previous versions
   it was based on.  These may be placed in the "History" section.
   You may omit a network location for a work that was published at
   least four years before the Document itself, or if the original
   publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
   Preserve the Title of the section, and preserve in the section all
   the substance and tone of each of the contributor acknowledgements
   and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
   unaltered in their text and in their titles.  Section numbers
   or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements".  Such a section
   may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements"
   or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.


5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications".  You must delete all sections
Entitled "Endorsements".


6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.


7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.


8. TRANSLATION

Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers.  In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.


9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License.  Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.


10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.


ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:

    Copyright (c)  YEAR  YOUR NAME.
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the "with...Texts." line with this:

    with the Invariant Sections being LIST THEIR TITLES, with the
    Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.