Layout.txt 10 KB
Newer Older
1 2 3 4 5
----------------------------------------------------------------------
Intro
----------------------------------------------------------------------

This document describes briefly the configuration options to specify
6 7
the layout of the generated HTML pages. (Layouts are only available in
the HTML generator, not in the Latex generator.)
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

In general, the layout string for the document element is taken and
evaluated. The string may contain variables (written @VARNAME@) which
have different meanings for every element.

For example, to set the layout of <em> such that the text is printed
in italics, declare:

<layout name="em"><![CDATA[<it>@CHILDREN@</it>]]></layout>

For <em>, the variable CHILDREN is substituted by the resulting HTML
texts of the children nodes of <em>.

For many simple elements, the layout options are described in the DTD.

23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
For the syntax @MSG:foo@ see the document I18N.txt.

----------------------------------------------------------------------
Layout as macros
----------------------------------------------------------------------

Layouts are also a simple form of macros.

<layout name="foo">FOO</layout>

<layout name="bar">@foo@ @foo@</layout>

This would expand to "FOO FOO".

By convention, names of custom layouts are all lowercase, whereas the
parameters of the built-in layouts are all uppercase.

40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
----------------------------------------------------------------------
The layout for <page>
----------------------------------------------------------------------

The page layout is the "root layout" for the whole generated page. It
is the most complicated layout option, because the navigation tree is
part of the page layout.

The page layout has the following variables:

- CHILDREN: This variable is substituted by the contents of the page. 
  IF OMITTED, NOTHING IS DISPLAYED IN THE GENERATED HTML PAGES!

- TITLE: The title of the page

- UPURL: The URL of the parent page

- UPTITLE: The title of the parent page

- NAVIGATION or LEVEL: The navigation tree. See below for how it is
  constructed

- RELATED: The box with related links. See below for how it is
  constructed.

- FOOTER: The footer area. See below for how it is constructed

- PREVLINK: The LINK element of the previous page

- NEXTLINK: The LINK element of the next page

71 72 73
- LANGSELECT: The language selector box. See below for how it is
  constructed.

74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
----------------------------------------------------------------------
The navigation tree
----------------------------------------------------------------------

In a first step, it is determined which part of the page tree is
displayed in the navigation tree. The page hierarchy is defined
by the <hierarchy> element, e.g.

<hierarchy>
  <plevel idref="rootpage">
    <plevel idref="chapter1"></plevel>
    <plevel idref="chapter2">
      <plevel idref="ch2section1"></plevel>
      <plevel idref="ch2section2"></plevel>
    </plevel>
  </plevel>
</hierarchy>

The current page is normally part of the navigation tree. The question
is now how many ancestor pages are taken into account. In a simple
navigation layout, only the parent of the current page is shown in the
navigation tree (so the user can only move to the direct ancestor). In
a more complex layout, more ancestors are shown, and often also
sibling pages.

The algorithm determines the starting point of the navigation tree by
moving up on the path from the parent of the current page to the root
page, and by checking whether the inspected page is the starting
point. A page is the starting point when the navstart attribute of the
<plevel> element is "yes". (When the navstart attribute is omitted,
the default is taken from <hierarchy>; and if also omitted here, the
default is "yes" - for compatibility with old versions of the
program.)

Example: Only the rootpage is starting point. This means that the
whole page tree is shown in the navigation tree:

<hierarchy navstart="no">
  <plevel idref="rootpage" navstart="yes">...</plevel>
</hierarchy>

Example: Every page is starting point. This means that the parent of
the current page is the starting point:

<hierarchy navstart="yes">
  <plevel idref="rootpage">...</plevel>
</hierarchy>

(Note: The special case when the current page is the root is discussed
below.)

After the starting point is clear, there is now the question how the
HTML code is generated that shows the part of the tree from the
starting point down to the current page. Generally, the algorithm
walks on the direct path from the starting point down to the
page, or better, the algorithm must allow such a walking.

First, the layout option "navigator.start" is evaluated. This option
can be used to establish an environment for the other HTML constructs,
e.g. a table. "navigator.start" may contain the variable
SUBLEVELS (and should contain it), and the variables LEVELTITLE,
LEVELURL, UPTITLE, UPURL (see below). The default for this option is:

<layout name="navigator.start">@SUBLEVELS@</layout>

The variable SUBLEVELS is also used for other options, and generally
is

(1) an instruction to generate HTML code for the pages on the level
    below the current one

(2) replaced by the concatenation of the HTML fragments resulting from
    the subordinate levels

As "navigator.start" refers to the start node, the sub nodes are
the children of the start node.

The pages on the sub level fall in one of three categories:

- The page is the current page. In this case, the layout option
  "navigator.current" is used to generate the HTML text

- The page is on the direct path from the starting point to the
  current page. The option "navigator.onpath" is used.

- For all other pages, the option "navigator.level" is used.

The idea is now that the HTML code for the starting page is generated
by checking the category. Of course, only "navigator.current" and
"navigator.onpath" are possible. In the case of "navigator.current",
we are already done. In the case of "navigator.onpath", the navigation
option typically includes the variable SUBLEVELS again. This instructs
the program to look at the sub level, and to determine the layouts of
the sub pages. These can again include SUBLEVELS - in other words,
SUBLEVELS controls the recursive descent.

In addition to SUBLEVELS, the layout definitions can refer to the
following variables:

- LEVELTITLE: The title of the page the layout definition is evaluated
  for

- LEVELURL: The URL of the page the layout definition is evaluated
  for

- UPTITLE: The title of the parent of the page the layout definition is
  evaluated for. For the root page, the UPTITLE is the expanded
  layout option "navigator.toptitle".

- UPURL: The URL of the parent of the page the layout definition is
  evaluated for. For the root page, the UPURL is the expanded
  layout option "navigator.topurl".

The variable SUBLEVELS has a slightly different meaning when it occurs
inside "navigator.current". In this special case, a fourth category is
used, and for all sub pages the layout option "navigator.child" is
taken, if defined, and "navigator.level" else. This feature can be
used to render the direct children of the current page differently.

When the current page is the root page this special case is handled as
follows. Normally, the algorithm starts at an ancestor of the current
page. This is not possible in this case, and because of this, the
starting point is simply the root page. Furthermore, if there is the
layout "navigator.root" it is used instead of "navigator.start".

In order to define special layouts for special levels, one can change
the prefix "navigator" to another string by setting the <plevel>
attribute layout-prefix, e.g.:

<plevel idref="superdooperpage" layout-prefix="emphasis"/>

Now, the layouts "emphasis.level", "emphasis.current" etc. are used
instead of the standard navigator layouts when the rendering algorithm
reaches this page.

----------------------------------------------------------------------
Related links
----------------------------------------------------------------------

In the layout "page", the variable "RELATED" is substituted by the
enumeration of the related links. These links can be set in the page
hierarchy, e.g.

<plevel idref="...">
  <related href="...">...</related>
</plevel>


If such links are declared, RELATED is expanded as follows (otherwise,
it is replaced by the empty string). The layout "related" defines the
environment for the link list. It can contain the variable LINK which
is substituted by the concatenated links. The individual links are
handled by applying the layout "related.link". They may contain the
variables TEXT, replaced by the name of the link, and HREF, replaced
by the URL.

230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
----------------------------------------------------------------------
The language selection box
----------------------------------------------------------------------

In the layout "page", the variable "LANGSELECT" is substituted by
the language selection box. This box may contain links to view
the current page in different languages. LANGSELECT is only
generated when the <languages> element declares languages.

The layout "langselect" defines the environment for the link list.
It can contain the variable LINK which is substituted by the
concatenated links. The individual links are generated by 
applying the layout "langselect.link". Allowed variables:

- CODE: the two-letter language code
- TEXT: The description of the language
- IMGURL: The URL of the optional image (or "")
- HREF: The URL switching the language
- LANG: The current language (two-letter code)


251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
----------------------------------------------------------------------
Footer
----------------------------------------------------------------------

The footer is the area for footnotes. It is generated by expanding
"footnote.foot" for every footnote, and concatenating the resulting
texts.

This layout can contain this variables:

- SYMBOL: The visible footnote number

- TEXTANCHOR: The HTML anchor name for the location in the text
  pointing to the footnote

- FOOTANCHOR: The HTML anchor name for the footnote itself

- CHILDREN: The footnote text nodes

The layout "footnote.text" is used to generate the reference to the
footnote in the text body. Except CHILDREN, the same variables are
supported.