DocumentTree macro
==================

[[Parent]]: available_macros.txt

The DocumentTree macro generates a hierarhical, alphabetically ordered list of the 
documents in the document tree, using a given document as the root document. This 
ordered list is enclosed in a `<div>` block, so that the list elements can be styled 
using CSS.

[RemarkPage]: [[Ref]]: RemarkPage_DocumentType.txt

Properties
-----------

### Output type

Remark

### Output expansion default

Enabled.

### Parameters

Ignored.

### Variables

DocumentTree.class_name
: 	The name of the html-class to give to the `<div>` tag. The html-class 
	allows to style the generated list using CSS.
	Default `DocumentTree`.

DocumentTree.exclude
:	A list of tag-name/glob pairs (e.g. file_name *.txt), one per row, 
	where the glob decides whether a given document with a given tag-value 
	is to be excluded from the list. Default empty (matches nothing).

DocumentTree.exclude_regex
:	A list of tag-name/regex pairs (e.g. file_name .*\.txt), 
	one per row, where the regex decides whether a given document with a 
	given tag-value is to be excluded from the list. 
	Default empty (matches nothing).

DocumentTree.root_document
:	The document to use as the root node.
	Default `[[tag file_name]]` (expanded).

DocumentTree.include
:	A list of tag-name/glob pairs (e.g. file_name *.txt), one per row, 
	where the glob decides whether a given document with a given tag-value 
	is to be included in the list. Default `file_name *` (matches everything).

DocumentTree.include_regex
:	A list of tag-name/regex pairs (e.g. file_name .*\.txt), 
	one per row, where the regex decides whether a given document with a 
	given tag-value is to be included in the list. 
	Default empty (matches nothing).

DocumentTree.max_depth
:	Maximum depth for a document to be listed.
	Default 10.

DocumentTree.min_depth
:	Minimum depth for a document to be listed.
	Default 1 (i.e. the root-document is not listed).

DocumentTree.compact
:	An integer specifying whether to use a compact representation for 
	the tree (non-zero), or not (zero). Default 1.

Notes
-----

When specifying patterns, multiple rows are interpreted as alternatives. 
Possible surrounding whitespace is stripped off for each line.
If both a regex pattern and a glob pattern is given, they
are combined as alternatives.

A document is said to _match_ when

 * it matches the include pattern, and
 * it does not match the exclude pattern.

### Non-compact representation

In the _non-compact_ representation, a document is listed if and only if

 * its depth is at least `min_depth` and at most `max_depth`, and
 * it matches, or it has matching descendants. 
 
This preserves the parent-child relation between documents.

### Compact representation

In the _compact_ representation, a document is listed if and only if

 * its depth is at least `min_depth` and at most `max_depth`, and
 * it matches, or it has matching children, or it has at least two 
 children with matching descendants.

This preserves the ancestor-descendant relation between documents, 
but not necessarily the parent-child relation.
 
Examples
--------

[[Example]]:
	[[DocumentTree]]

[[Example]]:
	[[set_many DocumentTree]]:
		min_depth 0
	[[DocumentTree]]

[[Example]]:
	[[set_many DocumentTree]]:
		min_depth 0
		include document_type RemarkPage
	[[DocumentTree]]


See also
--------

[[Link]]: pattern_matching.txt
