Appendix H. The Handbook

Version 3.0 beta

This is a preliminary version which can be changed or updated at any time.
The appendix has been written by Marco Bianchi.

H.1 Introduction

Version 3 of the Menota handbook is transformed to html with the stylesheet handbook_v3.xsl. The stylesheet outputs clean box-based html5. Genereally, all @rend are converted to html classes. All styling is taken care of by menota_handbook_3.css.

H.2 The html

handbook_v3.xls produces clean html5 without any form styling in html-code. The html-skeleton:


<!DOCTYPE html>
<html>
   <head>
      <body>
   	  <div id="page">
            <div id="main-wrapper">
      			<div id="header-wrapper">
      				<header> </header>
      				<nav> Site-navigation</nav>
      			</div>
      			<div id="content-wrapper">
      				<section id="sidebar" role="navigation">Page-MENU</section>
      				<main id="content">
      					<article>HANDBOOK ENTRIES</article>
      				</main>
      			</div>
   		    </div>
   		    <footer></footer>
   	    </div>
      </body>
   </head>
</html>

H.3 The css

The css-sheets use css3 but should degrade gracefully in non-compliant browsers. The main typeface for handbook v3 is Andron, which is read in with css @font-face and thus does not need to be installed on users' computers. @font-face is supported in all major modern browsers. Non compliant browsers will display a serif-font.

Handbook v3 uses one css-sheet: menota_handbook_3.css

Breaking points for small screens are set at 960px (width of header items and main content 100%) and 450px in portrait mode (larger main font-size).

H.4 Xml-markup

In the tables below supported xml markup and its corresponding html output is listed. All values of @rend and @xml:id will be passed to html @class and @id respectively, unless otherwise noted.

H.4.1 CSS Block elements

tei:xml html function Comment
<code> <pre> <code> Code example Read more about styling of code
@rend
'inline' Inline code example
<eg> <pre> <code> Example of code Read more about styling of code
@rend
'inline' Inline code example
<egXML> <pre> <code> Example of xml code Read more about styling of code
@rend
'inline' Inline code example
<figure> <figure> Illustration Typically, a <figure> -element contains a <graphic> and a <figDesc> -element. Read more about styling of images
@rend
'leftalign' The figure is placed to the left, with text floating to the right
'rightalign' The figure is placed to the right, with text floating to the left
'center' The figure is placed in the center. No floating occurs.
<Figure> / <figDesc>

<figcaption span class="imagelabel">Fig. 
Figure caption Should be used together with a sibling <graphic> and a parent <figure>
@n
'[number]'

<figcaption><span class="imagelabel">Fig. <span class="imageid">2.1<>/span>. </span>Caption</figcaption>
Usage in xml: <figDesc n="2.1">Caption</figDesc>, i.e. the figure's number should passed through @n and not be put between the <figDesc> -tags
<graphic> <img> Image If used together with a parent element <figure> , the image element will be wrapped in a <figure> -element together with its caption. It may, however, also be used alone.
@rend
<head> <h1> , <h2> , <h3> , <h4> , <head> Heading <h1> <h4> are chosen according to their position in the dom. If the position does not match, a generic <div class="head"> is output.
@rend
@xml:id When no @xml:id is passed, the xsl will introduce an @id with a random value
<l> <li> List item
<lg> <ul> Unordered list
<list> <ul> List Unordered list
@rend
'numbered' <ol> Ordered list Ordered (= numbered) list
@type @type is converted to a css- @class for backwards compatibility with earlier style sheets
@xml:id
<list> / <item> <li> List item
<p> <p> Paragraph
@rend
'sample' <blockquote> Blockquote
@xml:id
<quote> <blockquote> Blockquote
<table> <table> Table Read more about table styling
@rend
'xml-elements' This value can be used for tables with lists of xml-elements and their attributes. Read more below
@xml:id
<table> / <row> <tr> Table row
@rend
@xml:id
@role
'label' <tr> / <th> Table header i.e. table header
<table> / <cell> <td> or <th> Table cell <th> when the parent <row> @role= 'label'
@rend

H.4.2 CSS Inline elements

tei:xml html Function Comment
<att>

<code><span class="attribute">@att</span></code>
xml/html attribute Read more about styling of code. In a table with @rend= 'xml-elements' attributes in the first columns are automatically indented 1em
<emph> <em> Emphasis
<gi>

<code><span class="tag">@att</span></code>
xml/html element Read more about styling of code
<hi> <span> Highlighted
@rend
'bold' <b> If @rend contains multiple values, 'bold' is passed to <span class="bold [othervalue]">
'italic' <i> If @rend contains multiple values, 'italic' is passed to <span class="italic [othervalue]">
'code' <code> If @rend contains multiple values, 'code' is passed to <span class="code [othervalue]">Read more about styling of code
'red'

<span class="red">
'blue'

<span class="blue">
'initial'

<span class="initial">
<lb /> <br /> Line break
<q> <q> Quoted
<ref> <a> Reference
@target @href
@rend
<tag>

<code><span class="tag">@att</span></code>
Tagged content Read more about styling of code
<title> <q> Title of a work
<val>

<span class="value">'value'</span>
Value of a xml/html element Read more about styling of code. In a table with @rend= 'xml-elements' values in the first columns are automatically indented 2em

H.4.3 Generic values for @rend

The following @rend-values can be given to any xml-element with support for @rend:

  • 'blue' (blue font color)
  • 'bold' (bold style)
  • 'code' (monospace font)
  • 'red' (red font color)
  • 'style' (italic style)

The following @rend-values can be given to any xml-element that translates into a block-element in html/css and supports the @rend-attribute. Percentages are always relative to the width of the parent element's width. The available values for @rend behave the following way at different screen resolutions:

@rend=... Large screens Medium screens Small screens
'alignleft' align:left align:left align:left
'alignright' align:right align:right align:right
'aligncenter' centered centered centered
'center' text-align:center text-align:center text-align:center
'width10' width:10% width:50% width:100%
'width20' width:20% width:50% width:100%
'width25' width:25% width:50% width:100%
'width30' width:30% width:50% width:100%
'width33' width:33,33% width:50% width:100%
'width40' width:40% width:50% width:100%
'width50' width:50% width:50% width:100%
'width60' width:60% width:100% width:100%
'width66' width:66,66% width:100% width:100%
'width70' width:70% width:100% width:100%
'width80' width:80% width:100% width:100%
'width90' width:90% width:100% width:100%
'width100' width:100% width:100% width:100%

H.5 Styling tables

Tables are structured according to the following pattern in html:


<table>
   <colgroup>
      <col style="width20">
      <col style="width80">
   </colgroup>
   <thead>
      <tr>
         <th></th>
         <th></th>
      </tr>
   </thead>
   <tbody>
      <tr>
         <td></td>
         <td></td>
      </tr>
   </tbody>
</table>

The <colgroup> -element is created dynamically if the first row contains cells with the attribute @rend. This means that the column widths of the html-table can be controlled with the attribute @rend in the cells of the first table row. Below is the xml-code of the html-table above:


<table>
   <row rend="label">
      <cell rend="width20"></cell>
      <cell rend="width80"></cell>
   </row>
   <row>
      <cell></cell>
      <cell></cell>
   </row>
</table>

H.5.1 Styling tables with explanations of xml-elements

A table with explanations of xml-elements and their attributes (such as the one above) can be given @rend= 'xml-elements' in the <table> -element. The xls-style sheet tries to wrap all rows with a <gi> in the first cell into a <tbody> -element together with the following rows. Such tables must adhere to the following principles:

  • The <table> -tag must have a @rend with the value 'xml-elements'
  • The first cell of the first row in each block must contain a <gi> -element
  • The first cells of all other rows in a block must not contain any <gi> -element (otherwise, the respective row will be treated as the first row in a block)

Strings marked with <att> and <val> in the first cell of each row are indented automatically.

H.6 Styling images

An image and its caption should be structured as follows:


<figure rend="leftalign width33">
   <graphic url="path/to/image.jpg" />
   <figDesc n="1.2">Figure Caption</figDesc>
</figure>

The position and width of the image can be controlled with <rend> in the wrapping <figure> -element. By default, <figure> is displayed centered at a width of 50% with a border around the containing elements. The figure's number should passed through @n in <figDesc> . The xslt adds automatically a figure label. The above <figDesc> will thus be rendered as "Fig. 1.2: Figure Caption".

If used without a wrapping <figure> -element, images placed in a <graphic> -element are displayed at their original size without any border

H.7 Styling code

Block level code elements are wrapped into a html <pre> -tag that preserves linebreaks, white spaces and indentations. Such elements should thus not follow the indentation of surrounding xml. The following coding of a CDATA-section with surrounding xml...


            <p>Some text before the code</p>
            <egXML><![CDATA[
<figure rend="leftalign width33">
   <graphic url="path/to/image.jpg" />
   <figDesc n="1.2">Figure Caption</figDesc>
</figure>]]></egXML>
            <p>Some text after the code</p>

... will be output as:


<figure rend="leftalign width33">
   <graphic url="path/to/image.jpg" />
   <figDesc n="1.2">Figure Caption</figDesc>
</figure>

By default, code within <eg> , <egXML> and <code> is displayed as a block element. With @rend= 'inline' it can be forced to be treated as an inline element. Alternatively, the markup <hi rend="code"> or <tag> may be used for inline code.

Xml elements, attributes and values should be tagged with their respective semantic markup: <gi> , <att> and <val> .