#format wiki
#language en
#pragma section-numbers off
#pragma slides 2
#acl IanRiley:read,write,delete,revert,admin All:read
#pragma supplementation-page on

<<ContentsAndAppendices>>

= collect =

== Background and rationale ==

Collecting a number of MoinMoin pages for printing or saving as a single document could be useful in a range of circumstances. Although a single composite page could be constructed, an automated collection of existing pages makes more sense. Such automation avoids duplication, and having a set of separate pages is better for on-line delivery. The Collect parser has been written to combine of pages into a single document with consistent internal linking and a cover page with hyperlinks to pages within the collection. If saved by the [[PDF.py]] action, the internal links also work within a PDF reader. 

== Description ==

Collect is a simple parser that reads key:value pairs from a dictionary to combine pages into a collection for printing or saving as a booklet. 

The recognised key::value pairs are:

 '''heading:``: ''text'''''

  Text to be inserted at the top of the cover page as a level 1 heading

 '''paged:``: Yes | No'''

  Yes = insert a page break between collected pages, which has effect in print view and [[PDF.py]] action.
  No = insert a horizontal rule between collected pages.

 '''contents:``: List | Contents'''

  . List = insert s numbered list of collected pages on the cover page.
  . Contents = insert table of contents for each collected pages under level 2 headings on the cover page.

 '''contents-depth:``: 1...6'''

  Integer from 1 to 6 to specify the heading depth when tables of contents are inserted on the cover page.

 '''page:``: ''pagename'' [ | ''text'' ]'''

  Name of page to add to the collection, with an optional alternative text delimited by a vertical bar

 '''page-heading:``: Yes | No'''

  Yes = insert page name or alternative text (if specified) at the top of each collected page as a level 1 heading.

 '''page-url:``: Yes | No'''

  Yes = insert an external link on the cover page for page just specified.


The keys '''page''', '''page-heading''' and '''page-url''' can be repeated as a set to include more pages in the collection (see the example below).

This parser uses six plugin macros, [[AnchorLink.py]], [[EmbeddedPage.py]], [[FormattedPage.py]], [[GetTOC.py]], [[HttpLink.py]] and [[PageBreak.py]], which also need to be installed.

== Usage ==

As processing instruction

{{{
#format collect [raw]

 key:: value
 key:: value
 ...

}}}

As parser section

{{{{
{{{#!collect [raw]
 key:: value
 key:: value
 ...
}}}

The 'raw' argument is optional. When set, the output is the unformatted MoinMoin markup. 
}}}}

== Example ==

The following example collects this page along with those of the helper macros into a single document. [[PiAction]] is used to automatically provide the content as a PDF. The link to the example page followings the listing below of its raw content.

{{{
#action PDF
#format collect

 heading:: Collect Parser and Supporting Macros
 paged:: Yes
 contents:: List
 page:: collect.py|Collect parser
 page-url:: Yes
 page:: AnchorLink.py|AnchorLink macro
 page-url:: Yes
 page:: EmbeddedPage.py|EmbeddedPage macro
 page-url:: Yes
 page:: FormattedPage.py|FormattedPage macro
 page-url:: Yes
 page:: GetTOC.py|GetTOC macro
 page-url:: Yes
 page:: HttpLink.py|HttpLink macro
 page-url:: Yes
 page:: PageBreak.py|PageBreak macro
 page-url:: Yes

}}}

[[collect.py/Example]] - formatted example as a PDF.

[[collect.py/ExampleRaw]]  - intermediate MoinMoin markup generated by the Collect parser for this example.

== Download & Release Notes ==
|| Download || Release Version || Moin Version || Release Notes ||
|| [[attachment:collect-1.1.py]] || 1.1 || 1.9.2  ||  ||

== Copyright ==

 . @copyright: 2014 Ian Riley <ian@riley.asia>

== License ==

GNU GPL, see COPYING for details.

== Known issues and limitations ==

 * So that internally linked hypertext is distinguished, print.css on this site has been changed to give a and a:visited a text colour of blue.

-----

 Hits:: <<Hits>>