Version 6.1-1
Copyright © 2004 The Pagesetter Development Team
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 can be obtained from the Free Software foundation
Abstract
This manual documents how the web publishing tool Pagesetter for PostNuke works. Pagesetter is a publishing module that allows the PostNuke users to create web pages from structured data, with the data structure and output templates defined by the PostNuke administrator.
Table of Contents
List of Figures
List of Tables
List of Examples
Pagesetter is a publishing module that allows the PostNuke users to create web pages from structured data, with the data structure and output templates defined by the PostNuke administrator. The goal is ultimately to be able to define all the kinds of publications that normally require different PostNuke modules. The list includes:
… and so on.
See the readme.txt
for installation instructions.
Pagesetter publications can be organized in a folder structure with the help of another module "Folder" from www.elfisk.dk. Without this module you can browse through linear lists of publications with Pagesetter itself.
Read more in the PostNuke Features chapter.The CSS styles in the HTML version 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 5mm.
Let us start with a quick tutorial showing how to setup your very first Pagesetter publication. For this we use a News type as an example. With this publication type we will be able to write News with a title, a short header, full text, and an associated image selected from Photoshare.
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 publication named "PN-News" it should look like below:
Now click "New Publication Type" which will bring you to this window were you define your publication setup:
Here you must fill out the name of the publication and add your input fields—these are the input fields that end user will be able to enter data in. The field description is accessible as a "on-mouse-hover" hint when editing your publications.
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.
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:
You must enable images (with attributes!) and other HTML tags in PostNuke's setup before you can display any images. If you forget this then you will only see the text "<img ...>" instead of the actual image.
You must also enable popups for your site if you have any popup blockers installed, otherwise HTMLArea and previewing won't work.
You must also have EZComments installed to get the News example running with the templates in the examples directory.
The template used to display your data is named
PN-News-full.html
and is located in the pntemplates
directory. 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:
Example 2.1. Example template for News item.
// (the html presented is not the most correct with respect // to accessibility and xhtml compliancy) <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: <!--[nocache]--><!--[$core.hitCount]--><!--[/nocache]--> | <!--[nocache]--><!--[$core.editInfo]--><!--[/nocache]--></td> <!--[if $core.pageCount > 1 ]--> <td align="right">(Page <!--[$core.page+1]--> of <!--[$core.pageCount]-->)</td> <!--[/if]--> </tr></table> </div>
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.
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):
Pagesetter works with five different access levels:
On top of the raw PostNuke permission system, 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:
Table 3.1. Permission levels
Group | Component | Instance | Permission |
readers | pagesetter:: | tid:pid: | Read |
authors | pagesetter:: | tid:pid: | Edit |
editors | pagesetter:: | tid:pid: | Add |
moderators | pagesetter:: | tid:pid: | Delete |
admins | pagesetter:: | 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:
Table 3.2. Examples for permission setups
Group | Component | Instance | Permission | Result |
All groups | pagesetter:: | :: | Read | Read access for all groups to all publications. |
Unregistered | pagesetter:: | 4:: | None | Deny access for unregistered users to all publications of type 4 |
Group A | pagesetter:: | 3:: | Edit | Edit access to publication type 3 for all in group A |
Group B | pagesetter:: | 2:(1|5|19): | Edit | Edit access to publications 1,5 and 19 of type 2 for all in group B |
My page admin | pagesetter:: | 1:: | Admin | Admin access for "My page admin" group to publication type 1 |
Pagesetter supports topic based access control through the stand-alone module "TopicAccess" which you can download from www.elfisk.dk. The TopicAccess module lets the administrator define read/write access to Pagesetter based on the topic selected for a publication.
Topic based permission control follows these rules:
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:
Group | Component | Instance | Permission |
Unregistered | pagesetter:: | 1:7: | Read |
Unregistered | pagesetter:: | 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:
Table 3.3. Permission setup for access to a single publication item.
Group | Component | Instance | Permission |
Unregistered | pagesetter:: | 1:7: | Read |
Unregistered | pagesetter:: | 1:.+: | None |
Unregistered | pagesetter:: | 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.
Table of Contents
Instances of a publication type, 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 fields looks like below.
This setting specifies the first day a publication goes online. Normally this value is left empty, but you can get Pagesetter to insert the current date for you. This feature is enabled in the general configuration section ("Auto fill publish date").
This setting specifies the day a publication goes offline (it will not be available at the specified day).
These settings categorizes the publication and defines where to find it.
The PostNuke topic in which the publication belongs.
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.
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".
These settings holds who has written the publication and when.
The PostNuke user name of the user who created the publication. This name cannot be changed.
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.
The date of creation.
Last updated date.
It is possible to assign defaults for new publications via the URL as shown in the linking chapter.
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:
To use this field you must first install the "Folder" module separately. If you want more control over the location of new publications then specify a sub-folder name here. The name may include references to values in the publication which means you can create sub-folders on the fly by, for instance, including either topic name, created date or even both in the sub-folder name!
The syntax is whatever Smarty uses (just like the templates) except that you must use curly braces to indicate Smarty variables. Besides that you can refer to any publication data in exactly the same way as you would do in a template. The sub-folder name can include slashes to indicate sub-sub-...-sub-folders. None of the sub-folders need to exist prior to creating a publication.
Example: to create a sub-folder based on the topic name and current year and month you could write
{$core.topic.name}/{$core.created|date_format:"%Y/%m"}
. In this case you would
get a sub-folder named Linux/2005/06
for a publication created in June 2005.
Each field in a publication must have a type associated with it. Field types can be any of the following kinds:
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.
Upload fields are just, from an abstract point of view, data fields like all the other ones—you can have as many upload fields you want in one publication and uploads are also handled correctly by the revision control system.
When editing a publication with upload fields, you only need to upload your files once—even when editing and previewing your input. Any uploaded file is stored temporarily until you submit your publication, after which the uploaded file is permanently stored with the publication.
Uploads are stored as files on the web server and only references to these files are stored in the upload fields. You must configure the location of the files in Pagesetter's admin panel (goto administration::configuration::general). The upload directory must be writable by the webserver for this to work.
Uploaded files are accessed via PostNuke's standard index.php
file and thereby through Pagesetter. This has two implications 1) files
are always subject to the same access control as the publication
it is stored with, and 2) data must be streamed through PHP, generating
a performance overhead comparing to linking directly to the files.
It is the developers opinion that complete access control
is more important than performance in this case.
Pagesetter does not automatically delete uploads associated with a publication type when an upload field is either changed to another type or deleted.
Therefore you must manually delete the uploaded files when you decide they are not in use anymore.
Uploaded files are named TxPxRxF.dat
where
T is publication type, P is publication ID, R is revision and F
is field name. So if you remove field "document" on publication type 5
then you should delete all files named 5x*document.dat
.
See the tutorial.
It is possible to define categories to be used as dropdown elements in the input. An example of a category could be a selection of music media, for instance "CD", "DVD", "Tape", or "LP". A categorization could also be book genres: "Fiction", "Art", "History", and so on. Categories can even be nested, so for instance you can define sub-genres for books "Fiction:Science Fiction" and "Fiction:Fantasy". The categories are defined in this window:
It should be relatively simple; create a new category 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 category can afterwards be used for one or more fields in the publication types. Just select the category from the field type dropdown in the publication setup window.
Table of Contents
Here is a list of the various Pagesetter URLs you can use:
Here is a short description of the various URL parameters:
News-RSS.html
. The template name "News" is always
derived from the publication type and cannot be changed. If used with a list display
then Pagesetter will look for News-RSS-header.html
and
News-RSS-footer.html
also. If News-RSS-header.html
cannot be found then News-RSS.html
is assumed to be a
single template list without header/footer.
Here you can see which parameters you can use for the different functions (with less used functions included):
Table 6.1. URL parameters
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:
Table 6.2. Template overview by URL function
Function | Header / footer | Def. Template | Description |
None | x | list | Normal publication list |
viewpub | full | Full publication display | |
printpub | Full publication display, no frames | ||
dumppub | 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 |
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.fieldName
. The default sorting direction is ascending,
but descending can be specified with a ":desc" appended to a field name.
Example 6.1. Ordering by core fields
Example 6.2. Ordering by category fields and category field properties
It is also possible to filter the various lists of publications via restrictions in the 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 or hats (^). A single filter combines all it's expressions using an AND-operator (making it a conjunction). The possible filter operators are:
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.
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).
Example 6.3. Filtering
Now assume we have a book category as shown in the following image and use this in a book review publication with a field named "category" (using the category type of course).
Then we can select various sub-sets of the reviews with the following examples.
Example 6.4. Filtering by category fields
It is furthermore possible to match all items using the special list value "top", for instance in a filter like "filter=category:sub:top".
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>
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> ...
Table of Contents
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 template name
like "template-format.html" where
template is specified in the publication setup and
format depends on the situation.
Pagesetter uses the following formats in various situations (here an example filename is shown in the parenthesis):
1) Remember to make pagesetter/pntemplates
writeable
by the webserver if you want to use Pagesetter automatic generation of templates.
2) You always specify a format (like "RSS") when asked to supply a template in a block or URL. You do not specify a full filename!
3) If a list display cannot find a template header, for instance
News-list-header.html
then it assumes a
single template list is used and looks for the format "list-single" instead,
for instance News-list-single.html
.
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 can be used 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:
News-list-header.html
.
created
for a description of time stamps.
The items marked with * are also available in list headers and footers.
When refering to a category item you must further specify which property of the 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 or a topic field). The possible category properties are:
For instance, say you have a category field in your publication type called bookType. It is defined as a category 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 category 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 an HTML "select" input with the name "categoryInput" based on the field "category". The select input will show item titles and use item IDs as values.
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:
$core.page
is used.
$core.pageCount
is used.
$core.baseURL
is used.
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'>"]-->
When refering to upload fields you must specify one of the following properties:
Hit counts can be displayed in your publications by inserting
<!--[$core.hitCount]-->
. But you need to do something to avoid caching
of the output, otherwise the value would always stay the same (even though
the actual hit count is incremented anyway). For this purpose Smarty adds
the "nocache" tag. So the complete piece of code you need to insert is:
<!--[nocache]--><!--[$core.hitCount]--><!--[/nocache]-->
Such a link can be added by inserting <!--[$core.editThis]-->
or <!--[$core.editInfo]-->
, where the
first one takes you directly to the edit page, whereas the second adds
a little popup with some publication info and links to editing and
creation of new publications. As with the hit counts you must add
a "nocache" tag around the code:
<!--[nocache]--><!--[$core.editThis]--><!--[/nocache]-->or
<!--[nocache]--><!--[$core.editInfo]--><!--[/nocache]-->
The list view used in Pagesetter allows you to display a set of publications through a template. This 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.
If a 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 fine tune 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>
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.
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):
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"]-->
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.
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:
If you choose to organize your Pagesetter publications with the Folder
module then you might want to create your own templates for this purpose. If you
do not create any templates then the default templates folder.view.html
and folder.select.html
will be used for displaying items in the
folder system and selecting items in the folder system respectively.
You can design your own templates and name them
PubTypeName-folder.view.html
and
PubTypeName-folder.select.html
respectively.
You can use Image-folder.view.html
or
FileUpload.view.html
for inspiration.
Table of Contents
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.
Besides checking the normal permissions for Pagesetter, this block also checks for read access to the component "pagesetter:Waitingblock:" and instance "Block title:Block Id:Type Id". The "Type Id" is the publication type Id.
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 then
Default.html
is used.
The list block cannot yet handle single template lists and must have both a header and a footer.
By default, for a publication with the template set to "News", the block looks
for News-block-list.html
. If you don't write anything then this is the file
you must create. You must also supply News-block-list-header.html
and
News-block-list-footer.html
in this case.
If you want something different then you must write a "format" name—for
instance "other". Then the block will look for News-other.html
,
News-other-header.html
and News-other-footer.html
.
Besides checking the normal permissions for Pagesetter, this block also checks for read access to the component "pagesetter:Listblock:" and instance "Block title:Block Id:Type Id". The "Type Id" is the publication type Id.
The list block supplies the header and footer templates with a simplfied
$core
template variable. This variable contains tid
as the publication type ID, title
as the title of the publication type, and
blockTitle
as the title of the 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.
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.
Besides checking the normal permissions for Pagesetter, this block also checks for read access to the component "pagesetter:Pubblock:" and instance "Block title:Block Id:Publication Id". The "Publication Id" is what is normaly referred to as "pid".
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. Besides checking the normal permissions for Pagesetter, this block also checks for read access to the component "pagesetter:Listmenublock:" and instance "Block title:Block Id:Type Id". The "Type Id" is the publication type Id.
Configuring To set up the menu you need to specify the following attributes
pagesetter/examples/News/styles.css
.
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.
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".
Example 8.1. Example of search form taken from the standard PostNukeSilver theme.
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>';
It can be a bit difficult to get HTMLArea working with short URLs since
it's popups are refering directly to the directories on the web server. For
instance modules/pagesetter/guppy/HTMLArea/plugins/link.html
.
To avoid this problem you must tell the URL rewwriter that the HTMLArea URLs should be ignored. This can be done with the following rewrite rule:
RewriteRule ^(.+)guppy/HTMLArea30beta(.+)$ - [L,NC,NS]
The use of filters in the URL can also be a bit troublesome since the colons of the filter expressions ruins the browser's interpration of the URL. For this reason both hats (^) and colons (:) can be used in filters. Hopefully this helps.
If you want improved performance from Pagesetter then make sure caching is enabled in pnRender. Go to "Admin - pnRender" and enable caching.
With the help of a separate module "Folder", found on elfisk.dk, you can organize your publications in a hierarchical folder structure. It is further more possible to import all of your existing Pagesetter publications into that module.
To import your publications you must first define folders and sub-folders for each of the publication types. Then make sure you have spelled the sub-folder template correctly—for instance by creating a few publications from within Pagesetter and verifying that they end up in the expected sub-folders. After that go to Pagesetter's admin page :: Tools :: Export Data and transfer all the items.
Table of Contents
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.
It is possible to get the title of a Pagesetter publication put into the browser window's title bar with the use of the pagesetter_Title plugin, but only with Xantia themes.
It is also possible to do this using Jöerg's "Title-hack". Read more at http://sourceforge.net/projects/lottasophie.
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 use FEProc 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.
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, a topic, and the workflow state 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:
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 category type, which we will name "Experience". The category 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 dropdown input named "experience". The values of the dropdown field must be the category IDs for the Pagesetter category items (14, 15, and 16). The setup should be as in the following screen shots. Here is the FormExpress setup:
Here is the FormExpress dropdown 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:
Now you are ready to accept registrations for your course!
Table of Contents
Pagesetter offers a small set of tools to import data from other modules. You find these tools in the Tools::Import menu link which will take you to the window shown below.
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.
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.
Pagesetter also offers 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.
The PostCalendar import is still a bit experimental. It can copy most of the
data from PostCalendar into Pagesetter, except for the categories, which you
will have to add afterwards. The templates can be found in
pagesetter/examples/postcalendar
. It has only been tested with
PostCalendar version 4.1.0.
Pagesetter can read a publication type configuration from an uploaded XML file and create a new publication type based on that data. Beware that 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".
Table of Contents
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 bundled with this manual.
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.
Allows Authors to create pre-approved documents. Not much to this one.
Allows Authors to submit a publication. It then requires an Editor to approve it.
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.
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 .
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:
Create a publication type named "Gardens" (or similar) and add the fields you need.
Assign the "MyWiki" workflow to this publication type.
Check (enable) the access to editing of own pages.
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).
Table of Contents
The Guppy input forms CSS files are located in
pagesetter/guppy/themes/YourThemeName/style.css
. If you
do not write your own then the file
pagesetter/guppy/themes/guppy/style.css
will be used.
Pagesetter does not only let you define your own publication types and their presentation. It also lets you define both workflows, as described in the previous chapter, as well as the input forms used for editing your publications.
Different input form layouts can in fact be associated 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/<PubTypeFormName>
.
The "PubTypeFormName" is the "Form name" field of the publication type setup.
The filename used for a new instance of a publication
(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 located in the same
directory as this manual. The Guppy manual is meant to be a
complete Guppy manual, but for customizing input forms layout, 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).
The Guppy forms system allows the administrator to develop new simple types of inputs. Currently the "datetime", "e-mail", and "url" inputs are made this way. See the Guppy manual for further information.
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/<PubTypeFormName>
. 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).
Example 12.1. Adding a CSS class selector to 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"}}] } ); }
Some of the internal windows are rendered via pnRender—especially the
error messages that are displayed via pagesetter_error.html
.
This means you can redesign the layout of the error messages.
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).
Table of Contents
It is our hope that this manual some day becomes available on the internet with the ability to comment on the individual chapters. This appendix is meant for collecting all those comments that does not fit elsewhere.
Version 1.2, November 2002
Copyright © 2000,2001,2002 Free Software Foundation, Inc.
Version 1.2, November 2002
Table of Contents
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.
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.
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.
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.
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:
GNU FDL Modification Conditions
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.
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".
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.
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.
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.
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.
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.
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:
Sample Invariant Sections list
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:
Sample Invariant Sections list
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.