[$name|TemplateFormat$]
[$title|Template Format$]
[$frame|HTMLPage.tmpl$]
<p>
The templates used by [$pageName|GenDocs$] are the desired HTML
output files, but with some additional markup.
</p>
<p>
Goldie's own documentation
templates (in [$code|inline|{goldie root}/docssrc$]) should serve as a
good example. Pay special attention to the files
[$code|inline|docs.tmpl$] (which serves as the "main" file and defines
all the pages in the documentation) and [$code|inline|HTMLPage.tmpl$]
(which provides the common HTML "frame" that gets used on every page).
</p>

<a name="Usage" />
<h2>Usage</h2>
<p>
The basic usage of [$pageName|GenDocs$] involves creating a single "main"
template file (such as [$code|inline|docs.tmpl$]). This main template file
contains the content of the documentation's main entry page.
It also defines all of the main page's sub-pages which,
in turn, define their own content and sub-pages, and so on. Any of these
pages can be defined all in one large template file, or divided up however you
wish across multiple template files.
(Standard Goldie convention is to define the entire sitemap in the main
template, and give each page its own file named
[$code|inline|{full name of page}.tmpl$].)
</p>
<p>
Each page may also specify a "frame" file
(such as [$code|inline|HTMLPage.tmpl$])
which contains all of the HTML header/footer boilerplate.
</p>
<p>
The main template file is passed to [$pageName|GenDocs$] which automatically
loads all referenced templates, processes them, and creates the HTML
documentation as a directory tree. This directory tree has one directory and
[$code|inline|index.html$] file for each page
(the name of this HTML file can be changed as a command-line
parameter). The name of the directory is the same as the name of the page.
The name of the page is set in the template; it is not assumed to be the
template's filename.
</p>

<a name="Example" />
<h2>Example</h2>
<p>
Consider the following template file.
The main page is named "MyApp". It contains three sub-pages,
"A", "B", and "C". Sub-page "B" has its own sub-page
"MoreB".
</p>
[$code|plain|
[:[$name|MyApp$]
[$title|My App's Documentation$]
&lt;p&gt;Welcome to my documentation!&lt;/p&gt;

[$page|
    [$name|A$]
    [$title|Page A$]
	&lt;p&gt;This is page A.&lt;/p&gt;
$]

[$page|
    [$name|B$]
    [$title|Page B$]
	&lt;p&gt;This is page B.&lt;/p&gt;

    [$page|
        [$name|MoreB$]
        [$title|More Page B$]
		&lt;p&gt;This is more information for B.&lt;/p&gt;
	$]
$]

[$page|
    [$name|C$]
    [$title|Page C$]
	&lt;p&gt;This is page C.&lt;/p&gt;
$]
:]$]

<p>
From that template, [$pageName|GenDocs$] will create the following
directory tree:
</p>
[$code|plain|
[:MyApp/
|-- index.html
|
|-- A/
|   |-- index.html
|
|-- B/
|   |-- index.html
|   |
|   |-- MoreB/
|       |-- index.html
|
|-- C/
    |-- index.html
:]$]

<p>
And the pages will look like this:
</p>
<img src="[$urlToRoot$]GenDocsSampleMain.png" alt="" />
<img src="[$urlToRoot$]GenDocsSampleA.png" alt="" />
<img src="[$urlToRoot$]GenDocsSampleB.png" alt="" />
<img src="[$urlToRoot$]GenDocsSampleMoreB.png" alt="" />
<img src="[$urlToRoot$]GenDocsSampleC.png" alt="" />


<a name="Syntax" />
<h2>Syntax</h2>
<p>
All the [$pageName|GenDocs$] markup falls into one of two
categories: tags and quotes. These are explained below.
See the file
[$link| http://www.dsource.org/projects/goldie/browser/tags/v0.4/lang/tmpl.grm | {goldie root}/lang/tmpl.grm $]
for a formal definition of the syntax.
</p>

<a name="Tags" />
<h3>Tags</h3>
<p>
Tags can either insert data, format data, or provide [$pageName|GenDocs$]
with information.
</p>
<p>
Some examples of tags:
</p>

<ul>
<li>[$code|inline|[:[$title$]:]$]</li>
<li>[$code|inline|[:[$link| http://www.dsource.org/projects/goldie | Goldie Homepage $]:]$]</li>
</ul>

<p>
The basic format is:
</p>
<p>
[$code|inline|[:[$ tag_name $]:]$]<br />
[$code|inline|[:[$ tag_name | tag_data $]:]$]<br />
[$code|inline|[:[$ tag_name | first_param | tag_data $]:]$]<br />
...<br />
[$code|inline|[:[$ tag_name | first_param | second_param | etc... | tag_data $]:]$]<br />
</p>
<p>
The tag name, parameters and data are all separated by the pipe character.
</p>
<p>
Leading and trailing whitespace is trimmed from the tag name, parameters and data.
</p>
<p>
The data of a tag can contain quotes.
</p>
<p>
Tags do not nest (except for [$code|inline|[:[$page|...$]:]$]). Yes, this is
limiting and complicates certain aspects of [$pageName|GenDocs$] templating,
but fixing this would be a non-trivial change.
However, this feature may be added in a later version
([$link| http://www.dsource.org/projects/goldie/newticket | patches are welcome! $]).
</p>

<a name="Quotes" />
<h3>Quotes</h3>
<p>
Quotes insert text literally. Normally, any unquoted text gets inserted into
the output automatically, but quotes are needed to escape pipe characters and
square brackets. They can also be used to prevent whitespace surrounding tag
data from getting trimmed.
</p>
<p>
Outputting pipes and brackets:
</p>
<div class="code-plain">[:[:Hello! A | is a pipe. In D, int[] is an array.:]:[:]:]</div>
<p>
Preventing whitespace-trimming:
</p>
<div class="code-plain">[:[$link|http://www.dsource.org/projects/goldie|[:   Goldie Homepage   :]:[:]:][:$]:]</div>
<p>
Quotes do not nest. The first instance of [$code|inline|:[:]:]$] ends the quote.
Quotes do not have any escape sequences.
</p>
<p>
Any tags inside a quote do not get processed and simply get output literally.
</p>

<a name="Anchors" />
<h2>A Note About Anchors</h2>
<p>
There are a few tags that generate or reference HTML anchors.
Any time [$pageName|GenDocs$] does this, it "sanitizes" the anchor name by converting
certain invalid characters (specifically: space, parentheses, square brackets,
and exclamation point) to underscores.
</p>

<a name="TagList" />
<h2>Defined Tags</h2>
<p>
These are the tags that [$pageName|GenDocs$] recognizes:
</p>
<p>
NOTE: Some of these tags generate references to [$pageLink|#CSSList|CSS classes$].
It's up to the person writing the templates to include CSS code that defines these
CSS classes.
</p>

[$apiHeadPlain|[:[$rem| {comment} $]:]$]
<div class="api-def">
<p>
A comment. [$pageName|GenDocs$] just simply removes these.
</p>
<p>
The term "rem" is borrowed from BASIC and DOS BATCH and is short for "remark".
</p>
</div>

[$apiHeadPlain|[:[$name| {pageName} $]:]$]
<div class="api-def">
<p>
Sets the name of the current page.
The page will be created in a directory of this name.
This should be something like [$ident|MyPageName$].
</p>
<p>
Every page should set this.
</p>
</div>

[$apiHeadPlain|[:[$name$]:]$]
<div class="api-def">
Displays this page's name, which was set by [$code|inline|[:[$name|...$]:]$].
</div>

[$apiHeadPlain|[:[$fullName$]:]$]
[$apiDef|
<p>
Displays the full name of this page.
</p>
<p>
Example: If the main root page is named "Foo", and it has a sub-page
named "Bar", then the full name of page "Bar" is "Foo.Bar".
</p>
$]

[$apiHeadPlain|[:[$title| {pageTitle} $]:]$]
<div class="api-def">
<p>
Sets the title of the current page.
This will be displayed to the user, and can be anything,
such as [$code|inline|My Wonderful Page$].
</p>
<p>
Every page should set this.
</p>
</div>

[$apiHeadPlain|[:[$title$]:]$]
<div class="api-def">
Displays this page's title, which was set by [$code|inline|[:[$title|...$]:]$].
</div>

[$apiHeadPlain|[:[$desc| {pageDescription} $]:]$]
<div class="api-def">
<p>
Sets a description for the current page.
</p>
<p>
If this is defined, this will be shown to the user when the
parent page uses [$code|inline|[:[$pageMenu$]:]$].
</p>
</div>

[$apiHeadPlain|[:[$desc$]:]$]
<div class="api-def">
Displays this page's description, which was set by [$code|inline|[:[$desc|...$]:]$].
</div>

[$apiHeadPlain|[:[$frame| {filename} $]:]$]
[$apiDef|
<p>
Takes the filename of a template. This file will be used to "frame" the current page.
</p>
<!-- <p>
See example below.
</p> -->
$]

[$apiHeadPlain|[:[$framed$]:]$]
<div class="api-def">
<p>
If the current template was included as a frame (via [$code|inline|[:[$frame|...$]:]$]),
this inserts the content of that page (the page being "framed").
</p>
<!-- <p>
TODO: Example here.
</p> -->
</div>

[$apiHeadPlain|[:[$div| {cssClassName} | {content} $]:]$]
<div class="api-def">
<p>
Creates an HTML &lt;div&gt; with a given CSS class.
</p>
<p>
This is provided as a shorthand for:
</p>
[$code|plain|[:&lt;div class="{cssClassName}"&gt;{content}&lt;/div&gt;:]$]
</div>

[$apiHeadPlain|[:[$span| {cssClassName} | {content} $]:]$]
<div class="api-def">
<p>
Creates an HTML &lt;span&gt; with a given CSS class.
</p>
<p>
This is provided as a shorthand for:
</p>
[$code|plain|[:&lt;span class="{cssClassName}"&gt;{content}&lt;/span&gt;:]$]
</div>

[$apiHeadPlain|[:[$code| {cssSubClass} | {code} $]:]$]
<div class="api-def">
<p>
Identifies a section of text as being code.
</p>
<p>
Suggested use: [$code|inline|[:The C++ statement [$code|inline|[:a=b+c;:]:[:]:][:$] performs addition.:]$]
</p>
<p>
In most cases, this is a shorthand for the following:
</p>
[$code|plain|[:&lt;span class="code-{cssSubClass}"&gt;{code}&lt;/span&gt;:]$]
<p>
However, any tabs in [$ident|{code}$] are converted to four spaces.
Also, if [$ident|{cssSubClass}$] is "highlight", then any C++/D-style line-comments
are highlighted (by surrounding with a span of class "code-comment").
</p>
</div>

[$apiHeadPlain|[:[$file| {filename} $]:]$]
<div class="api-def">
<p>
Includes the content of another template file.
</p>
<p>
Leading and trailing whitespace in the filename gets trimmed.
</p>
<p>
This is analogous to C/C++'s [$code|inline|#include$] or PHP's [$code|inline|require()$].
</p>
</div>

[$apiHeadPlain|[:[$page| {content} $]:]$]
<div class="api-def">
<p>
Creates a sub-page. The [$ident|{content}$] will only be shown in the sub-page,
not in the current page.
</p>
<p>
See the [$pageLink|#Example|Example$] section above for an example of the page tag.
</p>
</div>

[$apiHeadPlain|[:[$pageTitle| {pageName} $]:]$]
<div class="api-def">
<p>Creates a link to another page within the generated documentation.</p>
<p>The link's label is the title of the page.</p>
<p>
The [$ident|{pageName}$] can either be the page's fullName
(see [$code|inline|[:[$fullName$]:]$] above),
or if no other page shares the same regular name,
then it can be the page's regular name instead
(see [$code|inline|[:[$name$]:]$] above).
</p>
</div>

[$apiHeadPlain|[:[$pageName| {pageName} $]:]$]
<div class="api-def">
<p>Creates a link to another page within the generated documentation.</p>
<p>The link's label is the name of the page.</p>
<p>
The [$ident|{pageName}$] can either be the page's fullName
(see [$code|inline|[:[$fullName$]:]$] above),
or if no other page shares the same regular name,
then it can be the page's regular name instead
(see [$code|inline|[:[$name$]:]$] above).
</p>
</div>

[$apiHeadPlain|[:[$pageLink| {target} | {label} $]:]$]
<div class="api-def">
<p>
Creates a link to target within the generated documentation.
The link's label is specified by [$ident|{label}$].
</p>
<p>
The [$ident|{target}$] can be in one of three formats:
</p>
<div class="code-plain">{pageName}
#{anchor}
{pageName}#{anchor}
</div>
<p>
The [$ident|{pageName}$] can either be the page's fullName
(see [$code|inline|[:[$fullName$]:]$] above)
or, if no other page shares the same regular name,
the page's regular name 
(see [$code|inline|[:[$name$]:]$] above).
</p>
<p>
The [$ident|{anchor}$] is the name of an anchor within the target page.
If an [$ident|{anchor}$] is used without a [$ident|{pageName}$],
the page is assumed to be the current page.
Like all anchors processed by [$pageName|GenDocs$], the [$ident|{anchorName}$] is
sanitized as described in [$pageLink|#Anchors| A Note About Anchors $] above.</p>
<p>
If [$ident|{pageName}$] is the current page
and there is no [$ident|{anchor}$], then [$ident|{label}$] is
highlighted, but not actually made into a link.
</p>
</div>

[$apiHeadPlain|[:[$typeName| {typeName} $]:]$]
<div class="api-def">
<p>
Highlights [$ident|{typeName}$] as a type and creates a link to the page which documents it.
</p>
<p>
The [$ident|{typeName}$] must be a type recognized by [$pageName|GenDocs$].
This is done by using
[$code|inline|[:[$apiSectionType|...$]:]$] or [$code|inline|[:[$definesType|...$]:]$]
on the page where the type is documented.
</p>
</div>

[$apiHeadPlain|[:[$typeLink| {typeName} | {label} $]:]$]
<div class="api-def">
<p>
Creates a link to the page which documents the type [$ident|{typeName}$].
Uses [$ident|{label}$] as the link's label.
</p>
<p>
The [$ident|{typeName}$] must be a type recognized by [$pageName|GenDocs$].
This is done by using
[$code|inline|[:[$apiSectionType|...$]:]$] or [$code|inline|[:[$definesType|...$]:]$]
on the page where the type is documented.
</p>
</div>

[$apiHeadPlain|[:[$urlLink| {url} $]:]$]
<div class="api-def">
<p>
Turns a URL into a link.
Used for linking to pages outside the generated documentation,
when you want the URL to be shown.
</p>
<p>
This is provided as a shorthand for:
</p>
[$code|plain|[:&lt;a class="extern-link" href="{url}"&gt;{url}&lt;/a&gt;:]$]
</div>

[$apiHeadPlain|[:[$link| {url} | {label} $]:]$]
<div class="api-def">
<p>
Creates a standard HTML link.
Used for linking to pages outside the generated documentation,
when you want a label to be shown instead of the URL.
</p>
<p>
The "Goldie Homepage" link in the upper-left corner of this page is an example
of this tag.
</p>
<p>
This is provided as a shorthand for:
</p>
[$code|plain|[:&lt;a class="extern-link" href="{url}"&gt;{label}&lt;/a&gt;:]$]
</div>

[$apiHeadPlain|[:[$ident| {name} $]:]$]
<div class="api-def">
<p>
Highlights [$ident|{name}$] as an identifier.
Any "meta-params" (ie, text surrounded by curly braces) are highlighted.
</p>
<p>
Sample use: [$code|inline|[:The [$ident|MyLittle{animalName}$] classes represent small animals.:]$]
</p>
<p>
Generated HTML:
</p>
[$code|plain|
[:The
&lt;span class="ident"&gt;
MyLittle
&lt;span class="metaparam"&gt;{animalName}&lt;/span&gt;
&lt;/span&gt;
classes represent small animals.:]$]
<p>
Result: The [$ident|MyLittle{animalName}$] classes represent small animals.
</p>
</div>

[$apiHeadPlain|[:[$attr| {attribute} $]:]$]
<div class="api-def">
<p>
Highlights [$ident|{attribute}$] as an
[$link| http://www.digitalmars.com/d/1.0/attribute.html | Attribute $].
Mainly used in API headings. For instance, on the [$pageTitle|Language$] and
[$pageTitle|Token$] documentation pages,
all of the green "static", "enum", "readonly" and "property" are attributes.
</p>
<p>
If your API headings are in a D-style language, then normally you would just
use the [$code|inline|[:[$apiHead|...$]:]$] tag which highlights attributes
automatically. This [$code|inline|[:[$attr|...$]:]$] tag is provided
if you need to do it manually.
</p>
<p>
This is provided as a shorthand for:
</p>
[$code|plain|[:&lt;span class="attr"&gt;{attribute}&lt;/span&gt;:]$]
</div>

[$apiHeadPlain|[:[$paramName| {paramName} $]:]$]
<div class="api-def">
<p>
Highlights [$ident|{paramName}$] as a function parameter.
Mainly used in API headings.
</p>
<p>
If your API headings are in a D-style language, then normally you would just
use the [$code|inline|[:[$apiHead|...$]:]$] tag which highlights parameters
automatically. This [$code|inline|[:[$paramName|...$]:]$] tag is provided
if you need to do it manually.
</p>
<p>
This is provided as a shorthand for:
</p>
[$code|plain|[:&lt;span class="param-name"&gt;{attribute}&lt;/span&gt;:]$]
</div>

[$apiHeadPlain|[:[$apiSection| {sectionName} | {module} | {label} $]:]$]
<div class="api-def">
<p>
Creates an API section to group together related functions, variables, etc.
</p>
<p>
Note: If the section represents a type (such as a class, struct or enum),
then you should use [$code|inline|[:[$apiSectionType|...$]:]$] instead.
</p>
<p>
Example:
[$code|inline|[:[$apiSection| ModuleLevel | mylib.util | Module-Level Members $]:]$]
</p>
<p>
That creates a section header that says "Module-Level Members"
and "module mylib.util" (the "module ..." text can be omitted by leaving the
[$ident|{module}$] parameter blank). It also creates an HTML anchor named "ModuleLevel".
</p>
</div>

[$apiHeadPlain|[:[$apiSectionType| {sectionName} | {module} | {label} $]:]$]
<div class="api-def">
<p>
Creates an API section that represents a type (such as a class, struct or enum).
This is used to group related functions, variables, etc, together.
</p>
<p>
Example:
[$code|inline|[:[$apiSectionType| Foo | mylib.foo | abstract class Foo : FooBase $]:]$]
</p>
<p>
That creates a section header that says "abstract class Foo : FooBase"
and "module mylib.foo" (the "module ..." text can be omitted by leaving the
[$ident|{module}$] parameter blank). It also creates an HTML anchor named "Foo".
</p>
<p>
Additionally, it registers "Foo" as a known type so that if "Foo" is used in an
[$code|inline|[:[$apiHead|...$]:]$] anywhere in the documentation,
it will automatically be turned into a link that points to this section header.
</p>
<p>
Note: If the section does NOT represent a type,
then you should use [$code|inline|[:[$apiSection|...$]:]$] instead.
</p>
</div>

[$apiHeadPlain|[:[$apiHead| {data} $]:]$]
[$apiDef|
Creates an API definition header for such things as functions and variables.
Automatically highlights according to D-style grammar for function headers
and variable declarations.
$]

[$apiHeadPlain|[:[$apiHeadPlain| {data} $]:]$]
[$apiDef|
<p>Creates an API definition header without any highlighting.</p>
<p>This is used by the tag name section headers in this documentation page.</p>
$]

[$apiHeadPlain|[:[$apiDef| {data} $]:]$]
<div class="api-def">
<p>
Creates an API definition. Generally used immediately
following [$code|inline|[:[$apiHead|...$]:]$] or
[$code|inline|[:[$apiHeadPlain|...$]:]$].
This is a shorthand for [$code|inline|[:[$div|api-def|...$]:]$].
</p>
<p>
Unfortunately, this tag is of very limited use since tags can't currently
contain other tags.
</p>
</div>

[$apiHeadPlain|[:[$definesType| {typeName}$]:]$]
<div class="api-def">
<p>
Registers [$ident|{typeName}$] as a known type so that if [$ident|{typeName}$]
is used in an [$code|inline|[:[$apiHead|...$]:]$] anywhere in the documentation,
it will automatically be turned into a link that points to this page header.
</p>
<p>
This tag is not frequently needed since
[$code|inline|[:[$apiSectionType|...$]:]$] does this automatically.
But if you define a type in a page without using
[$code|inline|[:[$apiSectionType|...$]:]$], then this tag can be useful.
</p>
</div>

[$apiHeadPlain|[:[$urlToRoot$]:]$]
<div class="api-def">
<p>
Inserts a relative URL path from the current page to the main root page directory.
</p>
<p>
Using [$code|inline|[:[$urlToRoot$]:]$] inside your main root page results in
an empty string. Using it in an immediate
child of the main root page results in [$code|inline|[:../:]$]. Etc...
</p>
<p>
As an example, on this particular Goldie documentation page, 
[$code|inline|[:[$urlToRoot$]:]$] results in
<span class="code-inline">[$urlToRoot$]</span>
</p>
<p>
This is useful for referring to things such as an common image directory:
</p>
<div class="code-plain">&lt;img src="[:[$urlToRoot$]:]images/mainlogo.jpeg" /&gt;</div>
</div>

[$apiHeadPlain|[:[$urlToBase$]:]$]
<div class="api-def">
<p>
Inserts a relative URL path from the current page to the parent directory
of the main root page directory.
</p>
<p>
This is equivalent to [$code|inline|[:[$urlToRoot$]../:]$]
</p>
<p>
This is useful for referring to things that are outside the documentation's directory tree.
</p>
</div>

[$apiHeadPlain|[:[$breadcrumbs$]:]$]
<div class="api-def">
<p>
Displays a "breadcrumb" trail to the current page.
</p>
<p>
Example:
</p>
<p>
[$breadcrumbs$]
</p>
</div>

[$apiHeadPlain|[:[$pageMenu$]:]$]
[$apiDef|
Displays a list of links to all immediate sub-pages (not recursive).
Page titles and (if defined) descriptions are shown.
$]

[$apiHeadPlain|[:[$pageMap$]:]$]
[$apiDef|
Displays a recursive tree-style list of links to all sub-pages.
Page titles are shown, but not descriptions.
$]

[$apiHeadPlain|[:[$siteMap$]:]$]
<div class="api-def">
<p>
Much like [$code|inline|[:[$pageMap$]:]$], except this starts from
the root page instead of the current page and the top-level pages
aren't bulleted.
</p>
<p>
The left-navigation bar in this documentation is an
example of [$code|inline|[:[$siteMap$]:]$]
</p>
</div>

[$apiHeadPlain|[:[$siteMapRooted$]:]$]
<div class="api-def">
<p>
Much like [$code|inline|[:[$siteMap$]:]$], except this includes the root page
in the displayed tree.
</p>
</div>

[$apiHeadPlain|[:[$parentPageLink$]:]$]
<div class="api-def">
<p>
Creates a link to the parent page. The page title is used as the link's label.
</p>
</div>

[$apiHeadPlain|[:[$pageTitle| {pageName} $]:]$]
<div class="api-def">
<p>
Displays the title of page [$ident|{pageName}$] as a link
(unless [$ident|{pageName}$] is the current page, in which case the title
is shown, but not as a link).
</p>
</div>

<a name="CSSList" />
<h2>CSS Classes</h2>
<p>
These are the CSS classes that [$pageName|GenDocs$] uses:
</p>
[$apiHeadPlain|[:api-head:]$]
[$apiDef|  $]

[$apiHeadPlain|[:api-def:]$]
[$apiDef|  $]

[$apiHeadPlain|[:api-section:]$]
[$apiDef|  $]

[$apiHeadPlain|[:module-decl:]$]
[$apiDef|  $]

[$apiHeadPlain|[:breadcrumb-link:]$]
[$apiDef|  $]

[$apiHeadPlain|[:extern-link:]$]
[$apiDef|  $]

[$apiHeadPlain|[:page-link:]$]
[$apiDef|  $]

[$apiHeadPlain|[:pagemenu-link:]$]
[$apiDef|  $]

[$apiHeadPlain|[:ident:]$]
[$apiDef|  $]

[$apiHeadPlain|[:attr:]$]
[$apiDef|  $]

[$apiHeadPlain|[:metaparam:]$]
[$apiDef|  $]

[$apiHeadPlain|[:code:]$]
[$apiDef|  $]

[$apiHeadPlain|[:code-comment:]$]
[$apiDef|  $]
