Commit 282a25b6 authored by gerd's avatar gerd

Flexibilized navigation tree (see doc/Layout.txt). Added a number

of examples (in test/) demonstrating the new power.


git-svn-id: https://godirepo.camlcity.org/svn/app-presentation/trunk@16 50e5f3cf-a9f2-0310-83d8-d11ec64cb5ab
parent 4b496b2f
----------------------------------------------------------------------
Intro
----------------------------------------------------------------------
This document describes briefly the configuration options to specify
the layout of the generated HTML pages.
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.
----------------------------------------------------------------------
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
----------------------------------------------------------------------
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.
----------------------------------------------------------------------
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.
......@@ -35,7 +35,7 @@ let convert_to_html no_gifs remove_prefix filename =
if no_gifs then store # no_gifs;
root # extension # enumerate_pages 0;
ignore(root # extension # enumerate_pictures 1);
let hier = root # extension # collect_hierarchy idx in
let hier = root # extension # collect_hierarchy true idx in
store # set_hierarchy hier;
root # extension # print_pages store idx
;;
......
<!-- $Id: presentation.dtd,v 1.4 2003/02/24 01:24:47 gerd Exp $ -->
<!-- $Id$ -->
<!ENTITY % p.like "p|ul|picture">
<!ENTITY % text "br|code|c|em|footnote|a|numref|nameref|html|latex">
......@@ -25,11 +25,14 @@
<!ELEMENT hierarchy (plevel)>
<!ATTLIST hierarchy
parent-href CDATA #IMPLIED
navstart CDATA #IMPLIED
>
<!ELEMENT plevel (related*,plevel*)>
<!ATTLIST plevel
idref IDREF #REQUIRED
navstart CDATA #IMPLIED
layout-prefix CDATA #IMPLIED
>
<!ELEMENT related (#PCDATA)>
......
all:
cd simple_out && make
cd fulltree_out && make
cd partialtree_out && make
cd fixedmenu_out && make
clean:
cd simple_out && make clean
cd fulltree_out && make clean
cd partialtree_out && make clean
cd fixedmenu_out && make clean
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE presentation SYSTEM "../presentation.dtd">
<presentation>
<layout name="indent"><![CDATA[&nbsp;&nbsp;&nbsp;&nbsp;]]></layout>
<layout name="page"><![CDATA[<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!-- WARNING! This is a generated file, do not edit! -->
<html>
<head>
<title>@TITLE@</title>
@PREVLINK@
@NEXTLINK@
</head>
<body bgcolor="#ffffcc"
text="black"
link="#4a708b"
alink="#4a708b"
vlink="#4a708b"
marginwidth="0"
marginheight="0"
style="margin:0px"
>
<table cellpadding="0" bgcolor="#ffffcc">
<tr><td height="20">&nbsp;</td></tr>
<tr>
<td width="10">&nbsp;</td>
<td width="200" valign="top" nowrap>
<font size=2><b>NAVIGATION</b></font><br><br>
<br>
@NAVIGATION@
<br><br>
@RELATED@
<br><br><font size=1><a href="/imprint.html">Contact</a>
</td>
<td width="1" valign="top" bgcolor="#2f4f4f">&nbsp;</td>
<td width="10">&nbsp;</td>
<td valign="top">
@CHILDREN@
@FOOTER@
</td>
<td width="10">&nbsp;</td>
</tr>
</table>
</body>
</html>
]]>
</layout>
<layout name="navigator.topurl">/TOPURL</layout>
<layout name="navigator.toptitle">Top</layout>
<layout name="navigator.start"><![CDATA[
<br><a href="@LEVELURL@">@LEVELTITLE@</a><br>
<table>
@SUBLEVELS@
</table>
]]>
</layout>
<layout name="navigator.root"><![CDATA[
<br><a href="@LEVELURL@"><font color="red">@LEVELTITLE@</font></a><br>
<table>
@SUBLEVELS@
</table>
]]>
</layout>
<layout name="level1.onpath"><![CDATA[
<tr>
<td colspan="2"><a href="@LEVELURL@">@LEVELTITLE@</a></td>
</tr>
@SUBLEVELS@
]]></layout>
<layout name="level1.level"><![CDATA[
<tr>
<td colspan="2"><a href="@LEVELURL@">@LEVELTITLE@</a></td>
</tr>
]]></layout>
<layout name="level1.current"><![CDATA[
<tr>
<td colspan="2"><a href="@LEVELURL@"><font color="red">@LEVELTITLE@</font></a></td>
</tr>
@SUBLEVELS@
]]></layout>
<layout name="level2.onpath"><![CDATA[
<tr>
<td>&nbsp;&nbsp;</td>
<td><a href="@LEVELURL@">@LEVELTITLE@</a></td>
</tr>
@SUBLEVELS@
]]></layout>
<layout name="level2.level"><![CDATA[
<tr>
<td>&nbsp;&nbsp;</td>
<td><a href="@LEVELURL@">@LEVELTITLE@</a></td>
</tr>
]]></layout>
<layout name="level2.current"><![CDATA[
<tr>
<td>&nbsp;&nbsp;</td>
<td><a href="@LEVELURL@"><font color="red">@LEVELTITLE@</font></a></td>
</tr>
@SUBLEVELS@
]]></layout>
<layout name="footer"><![CDATA[
<hr align=left noshade=noshade width="30%">
<dl>
@FOOTNOTES@
</dl>
]]></layout>
<!-- ************************************************************ -->
<hierarchy navstart="no">
<plevel idref="book" navstart="yes">
<plevel idref="chapter1" layout-prefix="level1">
<plevel idref="ch1sect1" layout-prefix="level2"/>
<plevel idref="ch1sect2" layout-prefix="level2"/>
</plevel>
<plevel idref="chapter2" layout-prefix="level1">
<plevel idref="ch2sect1" layout-prefix="level2"/>
<plevel idref="ch2sect2" layout-prefix="level2"/>
</plevel>
</plevel>
</hierarchy>
<!-- ************************************************************ -->
<page title="Book" id="book" file="index.html">
<sect1><title>Book</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 1" id="chapter1">
<sect1><title>Chapter 1</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 1 Section 1" id="ch1sect1">
<sect1><title>Chapter 1 Section 1</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 1 Section 2" id="ch1sect2">
<sect1><title>Chapter 1 Section 2</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 2" id="chapter2">
<sect1><title>Chapter 2</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 2 Section 1" id="ch2sect1">
<sect1><title>Chapter 2 Section 1</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 2 Section 2" id="ch2sect2">
<sect1><title>Chapter 2 Section 2</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
</presentation>
all:
../../presentation ../fixedmenu.xml
clean:
rm -f *.html *.gif
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE presentation SYSTEM "../presentation.dtd">
<presentation>
<layout name="indent"><![CDATA[&nbsp;&nbsp;&nbsp;&nbsp;]]></layout>
<layout name="page"><![CDATA[<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!-- WARNING! This is a generated file, do not edit! -->
<html>
<head>
<title>@TITLE@</title>
@PREVLINK@
@NEXTLINK@
</head>
<body bgcolor="#ffffcc"
text="black"
link="#4a708b"
alink="#4a708b"
vlink="#4a708b"
marginwidth="0"
marginheight="0"
style="margin:0px"
>
<table cellpadding="0" bgcolor="#ffffcc">
<tr><td height="20">&nbsp;</td></tr>
<tr>
<td width="10">&nbsp;</td>
<td width="200" valign="top" nowrap>
<font size=2><b>NAVIGATION</b></font><br><br>
<br>
@NAVIGATION@
<br><br>
@RELATED@
<br><br><font size=1><a href="/imprint.html">Contact</a>
</td>
<td width="1" valign="top" bgcolor="#2f4f4f">&nbsp;</td>
<td width="10">&nbsp;</td>
<td valign="top">
@CHILDREN@
@FOOTER@
</td>
<td width="10">&nbsp;</td>
</tr>
</table>
</body>
</html>
]]>
</layout>
<layout name="navigator.topurl">/TOPURL</layout>
<layout name="navigator.toptitle">Top</layout>
<layout name="navigator.start">@navigator.level@</layout>
<layout name="navigator.root">@navigator.current@</layout>
<layout name="navigator.level"><![CDATA[
<table>
<tr><td>o</td>
<td><a href="@LEVELURL@"><font size=2>@LEVELTITLE@</font></a></td>
</tr>
<tr><td>&nbsp;</td>
<td>@SUBLEVELS@</td>
</tr>
</table>
]]></layout>
<layout name="navigator.current"><![CDATA[
<table>
<tr><td>x</td>
<td><b><a href="@LEVELURL@"><font size=2>@LEVELTITLE@</font></a></b></td>
</tr>
<tr><td>&nbsp;</td>
<td>@SUBLEVELS@</td>
</tr>
</table>
]]></layout>
<layout name="footer"><![CDATA[
<hr align=left noshade=noshade width="30%">
<dl>
@FOOTNOTES@
</dl>
]]></layout>
<!-- ************************************************************ -->
<hierarchy navstart="no">
<plevel idref="book" navstart="yes">
<plevel idref="chapter1">
<plevel idref="ch1sect1"/>
<plevel idref="ch1sect2"/>
</plevel>
<plevel idref="chapter2">
<plevel idref="ch2sect1"/>
<plevel idref="ch2sect2"/>
</plevel>
</plevel>
</hierarchy>
<!-- ************************************************************ -->
<page title="Book" id="book" file="index.html">
<sect1><title>Book</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 1" id="chapter1">
<sect1><title>Chapter 1</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 1 Section 1" id="ch1sect1">
<sect1><title>Chapter 1 Section 1</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 1 Section 2" id="ch1sect2">
<sect1><title>Chapter 1 Section 2</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 2" id="chapter2">
<sect1><title>Chapter 2</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 2 Section 1" id="ch2sect1">
<sect1><title>Chapter 2 Section 1</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
<!-- ************************************************************ -->
<page title="Chapter 2 Section 2" id="ch2sect2">
<sect1><title>Chapter 2 Section 2</title>
<p>Blah Blah Blah</p>
</sect1>
</page>
</presentation>
all:
../../presentation ../fulltree.xml
clean:
rm -f *.html *.gif
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE presentation SYSTEM "../presentation.dtd">
<presentation>
<layout name="indent"><![CDATA[&nbsp;&nbsp;&nbsp;&nbsp;]]></layout>
<layout name="page"><![CDATA[<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!-- WARNING! This is a generated file, do not edit! -->
<html>
<head>
<title>@TITLE@</title>
@PREVLINK@
@NEXTLINK@
</head>
<body bgcolor="#ffffcc"
text="black"
link="#4a708b"
alink="#4a708b"
vlink="#4a708b"
marginwidth="0"
marginheight="0"
style="margin:0px"
>
<table cellpadding="0" bgcolor="#ffffcc">
<tr><td height="20">&nbsp;</td></tr>
<tr>
<td width="10">&nbsp;</td>
<td width="200" valign="top" nowrap>
<font size=2><b>NAVIGATION</b></font><br><br>
<br>
@NAVIGATION@
<br><br>
@RELATED@
<br><br><font size=1><a href="/imprint.html">Contact</a>
</td>
<td width="1" valign="top" bgcolor="#2f4f4f">&nbsp;</td>
<td width="10">&nbsp;</td>
<td valign="top">
@CHILDREN@
@FOOTER@
</td>
<td width="10">&nbsp;</td>
</tr>
</table>
</body>
</html>
]]>
</layout>
<layout name="navigator.topurl">/TOPURL</layout>
<layout name="navigator.toptitle">Top</layout>
<layout name="navigator.start">@navigator.onpath@</layout>
<layout name="navigator.root">@navigator.current@</layout>
<layout name="navigator.onpath"><![CDATA[
<table>
<tr><td>o</td>
<td><a href="@LEVELURL@"><font size=2>@LEVELTITLE@</font></a></td>
</tr>
<tr><td>&nbsp;</td>
<td>@SUBLEVELS@</td>
</tr>
</table>
]]></layout>
<layout name="navigator.level"><![CDATA[
<table>
<tr><td>o</td>
<td><a href="@LEVELURL@"><font size=2>@LEVELTITLE@</font></a></td>
</tr>
</table>
]]></layout>
<layout name="navigator.current"><![CDATA[
<table>
<tr><td>x</td>
<td><b><a href="@LEVELURL@"><font size=2>@LEVELTITLE@</font></a></b></td>
</tr>
<tr><td>&nbsp;</td>
<td>@SUBLEVELS@</td>
</tr>
</table>
]]></layout>
<layout name="footer"><![CDATA[
<hr align=left noshade=noshade width="30%">
<dl>
@FOOTNOTES@
</dl>
]]></layout>
<!-- ************************************************************ -->
<hierarchy navstart="no">
<plevel idref="book" navstart="yes">
<plevel idref="chapter1">
<plevel idref="ch1sect1"/>
<plevel idref="ch1sect2"/>
</plevel>
<plevel idref="chapter2">
<plevel idref="ch2sect1"/>
<plevel idref="ch2sect2"/>
</plevel>
</plevel>
</hierarchy>
<!-- ************************************************************ -->
<page title="Book" id="book" file="index.html">
<sect1><title>Book</title>
<p>Blah Blah Blah</p>
</sect1>