This plugin generates an index of all the pages included from one master page. This allows you to put together one huge document for print out plus a lean index for online browsing without extra maintenance.

Usage

Syntax Rules

%INCLUDEINDEX{"MasterPage" headers="n" format="string"}%

This discards everything from the included page, except:

1. Headlines up to given level, the default is 4.
2. %INLCUDEd pages, shown as defined by the format string. Default is "   * ", i.e. a bullet list.

The format string accepts the same syntax as a FormattedSearch. Use this to extract reports about your included pages. E.g. create a table of current revision information for all sub documents of a bigger manual:
%INCLUDEINDEX("MyProjectManual" headers="0" format="|[[$topic]] |$rev |$wikiusername |$date |"}%

Examples

%INCLUDEINDEX{"TWikiDocumentation" format="   0 $topic"}%

for the TWikiDocumentation of the Athens release yields:

1. TWikiImplementationNotes?
2. TWikiInstallationGuide
3. TWikiUpgradeGuide
4. TWikiUserAuthentication
5. TWikiAccessControl
6. TextFormattingRules
7. TWikiVariables
8. FileAttachment
9. TWikiForms
10. TWikiTemplates
11. TWikiSkins
12. FormattedSearch
13. TWikiMetaData
14. TWikiPlugins
15. TWikiSiteTools
16. ManagingTopics
17. ManagingWebs
18. AppendixFileSystem?
19. TWikiHistory

|*Topic* |*Rev*|*Author* |*Date* |
%INCLUDEINDEX{"TWikiDocumentation" headers="0" format="|[[$topic]] |  $rev|$wikiusername |$date |"}%

yields:

Topic Rev Author Date TWikiImplementationNotes? 1.22 MikeMannix 15 Sep 2001 - 08:56 TWikiInstallationGuide 1.41 PeterThoeny 05 Dec 2001 - 02:00 TWikiUpgradeGuide 1.27 PeterThoeny 05 Dec 2001 - 19:59 TWikiUserAuthentication 1.13 MikeMannix 15 Sep 2001 - 09:18 TWikiAccessControl 1.20 MikeMannix 02 Dec 2001 - 09:02 TextFormattingRules 1.30 MikeMannix 03 Dec 2001 - 04:11 TWikiVariables 1.46 MikeMannix 02 Dec 2001 - 11:58 FileAttachment 1.9 PeterThoeny 04 Dec 2001 - 10:19 TWikiForms 1.13 MikeMannix 03 Dec 2001 - 10:09 TWikiTemplates 1.11 PeterThoeny 04 Dec 2001 - 10:21 TWikiSkins 1.8 MikeMannix 16 Sep 2001 - 05:51 FormattedSearch 1.3 MikeMannix 02 Dec 2001 - 12:33 TWikiMetaData 1.9 MikeMannix 03 Dec 2001 - 12:53 TWikiPlugins 1.18 MikeMannix 03 Dec 2001 - 10:17 TWikiSiteTools 1.5 MikeMannix 04 Dec 2001 - 07:22 ManagingTopics 1.13 MikeMannix 18 Sep 2001 - 04:55 ManagingWebs 1.17 PeterThoeny 14 Sep 2001 - 10:09 AppendixFileSystem? 1.7 MikeMannix 15 Sep 2001 - 10:17 TWikiHistory 1.55 PeterThoeny 04 Dec 2001 - 10:25

Include Strategy

In theory, you can continue to write your pages as always and glue some of them to a bigger document via %INCLUDE.
In practice, you might want to change your strategy a bit, to make it easier to re-use pages as building blocks for large docs. The TWikiDocumentation example is not terribly useful, because it's just an linear enumeration. The following rules proved useful in bigger projects:

1. Don't put headlines into the topic pages, i.e.:
2. Concentrate headlines + includes in one master page
3. Title this according to your print-out needs
4. Create one index page using this plug-in, add links useful for online surfing, editorial hints etc.
5. Use TWiki:Main.ColasNahaboos savemulti Checkpoint function to save the master document without lengthy rendering
6. For really huge documents, where you want to print parts/chapters:
   1. create master page per printable chapter
   2. include master pages in global print page
   3. %INCLUDEINDEXes of master pages in index page

You write:

MyProject:	MyProjectManual:	Topic pages:
---+ My project %INCLUDEINDEX{... ---++ See also: <a href=/cgi-bin/edit/MyProjectManual>edit structure</a> <a href=/cgi-bin/pdf/MyProjectManual>Print PDF</a>	---+ Foo Topic 1 %INCLUDE{Topic1... ---++ Bar Topic 2 %INCLUDE{Topic2... ---++ Three... ---+ Bar Topic X %INCLUDE{TopicX...	Lorem ipsum dolet
		Lorem ipsum dolet
		. . .
		Lorem ipsum dolet
You get:
MyProject: Foo Topic1 Bar Topic2 Three... Bar Topic X See also: Edit structure Print PDF	MyProjectManual Foo Topic 1 Lorem ipsum dolet Foo Topic 2 Lorem ipsum dolet Three... Lorem ipsum dolet Bar Topic X Lorem ipsum dolet	Lorem ipsum dolet
		Lorem ipsum dolet
		. . .
		Lorem ipsum dolet

Compare to SectionalEditPlugin

The TWiki:Plugins/SectionalEditPlugin addresses the same problem with a completely different approach: it keeps one (possibly huge) wiki page for your printed document. The wiki way is emulated by opening small sections for editing.

Advantages of IncludeIndexPlugin:

• You can reference the sub-topics as plain wiki pages
• People can edit the sub-topics independently
• WebChanges etc. work as expected.
• Revision history of sub-documents is easy to track
• Need to render full document only when saving the master doc, but not for sub-topics

Advantages of SectionalEditPlugin:

• More topics mean more names, mean more possiblities to screw up namespace
• Sometimes, it is more convenient to edit many topics in one go
• TWiki (shame!) doesn't support Wiki:WayBackMode (yet), It is very hard to get a previous version of a composite doc other than storing printouts

Other Approaches

TWiki:Codev/FineGrainedAddressing & TWiki:Codev/NamedIncludeSections all try to solve the TWiki:Codev/LongTopicNav igation problem. They sub-structure topics, with the aim to handle bigger pages.

This clearly transcends the original wiki concept of small, simple pages. The IncludeIndexPlugin tries to stick with the idea of lean content topics and offload the complex and ugly %FOO{"BAR" random="markup"}% into distinct TWiki "wizard" pages.

I.e., instead of chopping up long, bulky topics into smaller slices, build the big structures bottom up. TWiki's %INCLUDE and skin for print and this plugin for navigation.

IncludeIndexPlugin Global Settings

• There are no global settings necessary for this plugin, except
  • Set SHORTDESCRIPTION = Generate an index of pages included from a master page.
  • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

• Download the ZIP file from the Plugin web (see below)
• Unzip IncludeIndexPlugin.zip in your twiki installation directory. Content:

File: Description: data/TWiki/IncludeIndexPlugin.txt Plugin topic lib/TWiki/Plugins/IncludeIndexPlugin.pm Plugin Perl module

• Test if the plugin is correctly installed: Between the following two horizontal rulers, the list of topics in the TWikiDocumentation should show up:

---

%INCLUDEINDEX{"TWikiDocumentation" format=" 0 $topic"}%

---

Plugin Info

Plugin Author: TWiki:Main/PeterKlausner Plugin Version: V1.000 Change History:   27 May 2005: Posted for Sep2004 Cairo release 11 Jun 2003: Posted for Feb2003 Bejing release Jul 2002: Initial version for Dec2001 Athens release CPAN Dependencies: none Other Dependencies: none Perl Version: 5.005 Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/IncludeIndexPlugin Feedback: http://TWiki.org/cgi-bin/view/Plugins/IncludeIndexPluginDev Source: CVSplugins:IncludeIndexPlugin

Related Topics:

• TWiki:Plugins/SectionalEditPlugin
• TWiki:Plugins/TocPlugin
• TWiki:Plugins/PdfPlugin
• TWikiPlugins
• TWiki:Codev/LongTopicNav

-- TWiki:Main/PeterKlausner - 11 Jun 2003