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

<<ContentsAndAppendices>>

= TableOfAppendices and ContentsAndAppendices =

== Background and rationale ==

MoinMoin provides useful macros, !TableOfContents and !PageList, which can be used to provide lists for headings or pages, but the two have different formatting. A listing of subpages (say, added as appendices providing additional information to a page) could be a helpful addition to individual links to the subpages. Although this can be done with !PageList marco, it would be more visually consistent to provide this list to match the format of the table of contents. To achieve this with wiki markup alone would be cumbersome.

== Description ==

!TableOfAppendices is a macro to insert a table of appendices (subpages) in the same format as the inbuilt !TableOfContents macro. If no subpages are found, an empty table of appendices is not inserted. This differs from the behaviour of the !TableOfContents macro.

!ContentsAndAppendices is a macro to insert a combined table of contents and appendices (subpages). If no subpages are found, an empty table of appendices is not included.

For clarity in both cases, the name of the root page is removed from the listing of the subpages.

The processing instruction `#pragma alt-name argument` can be included in a subpage. The text entered as the `argument` will become the text displayed in a table of appendices instead of the name of the subpage. Setting `#pragma index off` excludes the subpage from the listing

== Usage ==

=== <<TableOfAppendices>> ===

{{{

<<TableOfAppendices>> or <<TableOfAppendices()>> - inserts the table of appendices (subpages).

}}}

=== <<ContentsAndAppendices>> ===

{{{

<<ContentsAndAppendices>> or <<ContentsAndAppendices(maxdepth)>> - inserts the combined table of contents and appendices (subpages).

maxdepth: limits the heading level included in the table of contents 

}}}

== Download & Release Notes ==
|| Download || Release Version || Moin Version || Release Notes ||
|| [[attachment:TableOfAppendices-1.3.py]] || 1.3 || 1.9.8  ||  ||
|| [[attachment:ContentsAndAppendices-1.3.py]] || 1.3 || 1.9.8  ||  ||

== Examples ==

{{{
<<TableOfAppendices>>
}}}

<<TableOfAppendices>>

{{{
<<ContentsAndAppendices(2)>>
}}}

<<ContentsAndAppendices(2)>>

== History ==

Version 1.3 - 05.03.2015: keep pragma for calling page and reset for subpages.

Version 1.2 - 28.11.2012: added natual sorting and exclusion option for subpages.

Version 1.1 - 30.10.2012: direct list construction, sorted list, aternative subpage naming.

Version 1.0 - 19.12.2010: initial version.

Developed with inspiration and code from:

 . !TableOfContents macro @copyright: 2007 MoinMoin:JohannesBerg

 . !PageList macro @copyright: 2001-2003 Juergen Hermann <jh@web.de>, 2003-2008 MoinMoin:ThomasWaldmann, 2008 MoinMoin:ReimarBauer

== Copyright ==

 . @copyright: 2012-2015 Ian Riley <ian@riley.asia>

== License ==

GNU GPL, see COPYING for details.

== Known issues and limitations ==

 * The appendices (subpage) listing is not hierarchical, so if a subpage has a subpage it is not included as an indent indented list item, as is the case with second and third order headings in the contents listing. However, adding subpages to subpages would not be a recommended practice.

-----

 Hits:: <<Hits>>