File: webindex.html

package info (click to toggle)
aephea 12-248-3
links: PTS, VCS
area: main
in suites: bookworm, bullseye, buster, forky, sid, trixie
size: 1,092 kB
sloc: sh: 774; makefile: 66
file content (1669 lines) | stat: -rw-r--r-- 69,488 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (c) 2012 Stijn van Dongen and Moniek Hopman -->
<head>
<meta name="keywords" content="html abstraction and extension language,
html with macros,
html authoring framework
">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<style type="text/css">
.slartibartfast { background-color: pink; text-decoration: blink; }

   /* open base2 */
/* start aephea.base.css */

   body
      {  text-align: justify;
         margin-left: 0%;
         margin-right: 0%;
      }

   a:link            { text-decoration: none; }
   a:active          { text-decoration: none; }
   a:visited         { text-decoration: none; }

   a:link            { color: #1111aa; }
   a:active          { color: #1111aa; }
   a:visited         { color: #111166; }
   a.local:link      { color: #11aa11; }
   a.local:active    { color: #11aa11; }
   a.local:visited   { color: #116611; }
   a.intern:link     { color: #1111aa; }
   a.intern:active   { color: #1111aa; }
   a.intern:visited  { color: #111166; }
   a.extern:link     { color: #aa1111; }
   a.extern:active   { color: #aa1111; }
   a.extern:visited  { color: #661111; }
   a.quiet:link      { color: black; }
   a.quiet:active    { color: black; }
   a.quiet:visited   { color: black; }

   p.asd_par         {  margin-bottom:0em }
   p.asd_cpar        {  margin-bottom:0em }
   span.asd_cpar_caption  {  font-weight: bold; display: block }

   p.asd_car         {  margin-top:0em; margin-bottom:0em }
   p.asd_ccar        {  margin-top:0em; margin-bottom:0em }
   span.asd_ccar_caption  {  font-weight: bold; display: block }

   div.verbatim
      {  font-family: monospace;
         margin-top: 1em;
         margin-bottom: 1em;
         font-size: 10pt;
         margin-left: 2em;
         white-space: pre;
      }

   div.indent
      {  margin-left: 8%;
         margin-right: 0%;
      }

   .right   { text-align: right; }
   .left    { text-align: left; }
   .nowrap  { white-space: nowrap; }

   .item_leader 
      {  position: relative;
         margin-left: 8%;
      }
   
   .item_compact     {  position: absolute; vertical-align: baseline; }
   .item_cascade     {  position: relative; }

   .item_leftalign   {  text-align: left; }

   .item_rightalign
      {  width: 2em;
         text-align: right;
      }
   .item_compact .item_rightalign
      {  position: absolute;
         width: 52em;
         right: -2em;
         text-align: right;
      }

   .item_text
      {  position: relative;
         margin-left: 3em;
      }  

   .smallcaps { font-size: smaller; text-transform: uppercase }
   .underline { text-decoration: underline }

   acronym.ucase { font-size: smaller; text-transform: uppercase }
   abbr.ucase { font-size: smaller; text-transform: uppercase }

/* end aephea.base.css */
/* close base2 */
/* open simpledocument2 */
/* start aephea.asd.css */

   body {
      margin:0px;
      padding:0px;
      border: 0px;
   }


   .sec_leader
      {  margin-top: 1em;
         margin-bottom: 0em;
         position: relative;
         right: 0px;
         left: 0px;
         top: 0px;
      }

   .sec_title
      {  color: black;
         position: relative;
         margin-bottom: 0px;
         margin-top: 0px;
         margin-right: 5em;
         margin-left: 5em;
         text-align: center
      }

   .sec_num
      {  color: black;
         position: absolute;
         right: 0px;
         text-align: right;
         width: 5em;
         top: 0px;
      }

   .sec_lev1 { font-size: 20px; }
   .sec_lev2 { font-size: 18px; }
   .sec_lev3 { font-size: 16px; }
   .sec_lev4 { font-size: 14px; }
   .sec_lev5 { font-size: 12px; }
   .sec_lev6 { font-size: 12px; }

   .toc_toplevel
      {  margin-top: 1em;
      }

   .toc_leader
      {  margin-top: 0em;
         margin-bottom: 0em;
         position: relative;
         right: 0px;
         left: 0px;
      }

   .toc_title { position: relative; }

   .toc_num
      {  position: absolute;
         text-align: left;
         top: 0px;
         left: 0px;
      }

   .toc_title1 { margin-left: 3em; }
   .toc_title2 { margin-left: 6em; }
   .toc_title3 { margin-left: 9em; }
   .toc_title4 { margin-left: 12em; }

   .toc_num1   { left: 1em; }
   .toc_num2   { left: 3em; }
   .toc_num3   { left: 6em; }
   .toc_num4   { left: 9em; }

   div.box { border:solid; border-width:thin; width:100%; padding:1em}
   div.flushright { text-align: right }

/* end aephea.asd.css */
/* close simpledocument2 */
/* open css_append */

      
      body {
         font-size: 12pt;
      }

/* aephea general hooks: */

      acronym.ucase, abbr.ucase {
         font-size: smaller;
         text-transform: uppercase;
         text-decoration: none;
         border-style: none;
      }

      .wordlist   {  font-size: 121%; font-style: italic; }
      .namelist   {  font-size: 121%; }
      .example    {  margin-left: 2em; }
      .sec_title  {  text-align: left; margin-left: 0em; }
      .sec_lev1   {  font-size: 30px; }
      .sec_lev2   {  font-size: 25px; }
      .sec_lev3   {  font-size: 20px; }
      .toc_and_date_TOC a.intern { visibility: hidden; }
      .sec_num    {  display: auto; }
      .quote_attribution {  text-align: right; font-size: smaller; }
      .smallcaps  {  font-size: smaller; text-transform: uppercase }
                               /* .smallcaps  {  font-variant: small-caps } */

      .verbatim {
         margin-top: 1em;
         margin-bottom: 1em;
         font-size: 10pt;
         margin-left: 2em;
         font-family: courier;
         white-space: pre;
      }

      #asd_leftcolumn {
         position: fixed;
         text-align: left;
         width: 200px;
         left: 0px; top: 0px; bottom: 0px;

         background-color: pink;
         border-right:6px solid green;
      }

      #asd_document_outer {
         position: absolute;
         top: 0px;
         left: 200px;
         width: 724px;
         border-right:6px solid pink;
      }

      #asd_document {
         width: 640px;
         overflow: visible;
         margin: 40px auto;
      }

      #asd_toc {
         width: 200px;
         margin-top: 100px;
         background-color: pink;
         position: relative;
      }

/* document specific hooks: */

      #asd_title
         {  text-align: center;
            font-size: 40px;
            margin-top: 4em;
         }

      #asd_subtitle
         {  text-align: center;
            font-size: 25px;
            margin-top: 1em;
         }

      #asd_date {
         position: absolute;
         right: 20px;
         top: 30px;
      }

      #asd_version {
         position: absolute;
         left: 26px;
         top: 30px;     
      }

      .recipe {
         width: 620px;
         overflow: auto;
         border: 3px solid red;
         padding: 1em;
         margin-top: 1em;
         margin-bottom: 1em;
         font-size: 10pt;
         margin-left: 1ex;
         font-family: courier;
         white-space: pre;
      }


      body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
   
/* close css_append */
</style>
<title>A text-based authoring tool for HTML</title>
</head>
<body>
<div id=asd_leftcolumn>
<div id=asd_toc>
<div class="toc_toplevel">
<a name="thetoc"></a>
<div class="toc_leader">
<div class="toc_num toc_num1"><a class="intern" href="#asd_body_start">Start</a>.</div>
<div class="toc_title toc_title1"><a name="toc_asd_body_start"></a><a class="intern" href="#asd_body_start">&nbsp;</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc1">1</a>.</div>
<div class="toc_title toc_title1"><a name="toc_aepheanutshell"></a><a class="intern" href="#aepheanutshell">Aephea in a nutshell</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc2">2</a>.</div>
<div class="toc_title toc_title1"><a name="toc_feat"></a><a class="intern" href="#feat">Features</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc3">3</a>.</div>
<div class="toc_title toc_title1"><a name="toc_versioning"></a><a class="intern" href="#versioning">Versioning</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc4">4</a>.</div>
<div class="toc_title toc_title1"><a name="toc_aim"></a><a class="intern" href="#aim">Aims and constraints</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc5">5</a>.</div>
<div class="toc_title toc_title1"><a name="toc_short"></a><a class="intern" href="#short">Costs, shortcomings and limitations (annotated)</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc6">6</a>.</div>
<div class="toc_title toc_title1"><a name="toc_question"></a><a class="intern" href="#question">Questions and contributions</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc7">7</a>.</div>
<div class="toc_title toc_title1"><a name="toc_history"></a><a class="intern" href="#history">History</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc8">8</a>.</div>
<div class="toc_title toc_title1"><a name="toc_install"></a><a class="intern" href="#install">Installing Aephea</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc9">9</a>.</div>
<div class="toc_title toc_title1"><a name="toc_example"></a><a class="intern" href="#example">Example source of an Aephea document</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a class="intern" href="#asd_body_end">End</a>.</div>
<div class="toc_title toc_title1"><a name="toc_asd_body_end"></a><a class="intern" href="#asd_body_end">&nbsp;</a></div>
</div>
</div>
</div>
</div>
<div id=asd_document_outer>
<a name="asd_body_start"></a>
<div id=asd_document>
<div id="asd_date">September 5, 2012</div>
<div id="asd_version">aephea-12-248
</div>
<div id="asd_title">Aephea</div>
<div id="asd_subtitle">Effective and adaptable HTML authoring</div>

<a name="aepheanutshell"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#aepheanutshell">Aephea in a nutshell</a></div><div class="sec_num"><a class="intern" href="#toc1"><span class="sec_num">1</span></a></div></div>
<p class="asd_par">
The Hyper Text Markup Language, abbreviated and more commonly known as <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>,
in conjunction with Cascading Style Sheets (<abbr class="ucase" title="Cascading Style Sheets">CSS</abbr>), is well equipped
to deliver documents with beautiful layout,
consistent styling, good typography, and last but not least support
for enhanced accessibility.
Its use as a document typesetting technology will
only increase, off-line as well as on-line.
It is however cumbersome (although certainly possible) to
write <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> directly. Reasons for this are its verbosity, repetitiveness,
and lack of abstraction mechanisms for authors. Aephea is a text-based
authoring tool that aims to fill this gap.
</p>
<p class="asd_par">
Aephea enforces <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> well-formedness
with a simpler and stricter syntax. It provides useful extensions and
abstractions as well as facilities for adding new ones. Aephea
stays close to <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> itself and utilizes <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> extensively.
It is possible to write near-raw <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and to build powerful
abstractions in a single unified framework.
</p>
<p class="asd_par">
Aephea is pronounced <i>ay - 'fee - ah</i>, or <i>'ee - fee - ah</i>, or any
amalgam of the two, and stands somewhat grandiosely for <em>Adaptable
Exo-skeleton for Practical <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> Extension and Abstraction</em>.
It is a thin, expressive, and programmable framework
for creating <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> documents, aimed at people who are familiar with
<abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and Cascading Style Sheets, or intending to become so.
Three micro-formats are currently shipped with it.
</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_cascade"><div class=" item_leftalign nowrap namelist"
style="">pud::man</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A format in the <a class="local" href="http://micans.org/pud">Portable Unix Documentation</a>
section for writing manual pages with output in both <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and troff, with
further troff-derived outputs in <abbr class="ucase" title="Portable Document Format">PDF</abbr>, PostScript, and plain text.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap namelist"
style="">pud::faq</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A format in the <a class="local" href="http://micans.org/pud">Portable Unix Documentation</a>
section for writing FAQ documents with output in both <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and troff, with
further troff-derived outputs in <abbr class="ucase" title="Portable Document Format">PDF</abbr>, PostScript, and plain text.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap namelist"
style="">simpledocument</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A base format for writing <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> documents. The first goal is to push
as much control to <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> rules that are closely tied to the document.
The second goal is for <tt>aephea/simpledocument</tt> to be an example
format, to be extended, varied, and replaced wholesale.
</p>
<p class="asd_par">
The updated version is now called <tt>aephea/simpledocument2</tt>, and
is used by this document. All the lay-out rules are contained in
a separate style file with the idiosyncratic name <tt>reaper2.css</tt>.
It is shipped with aephea and can be accessed as <tt>contrib/reaper2.css</tt>.
The code below shows the essential make-up of an aephea document.
The <span class="smallcaps">CSS</span> rules are included in the <span class="smallcaps">HTML</span> <tt>&lt;head&gt;</tt> element
so that the document is entirely self-contained.
</p>
<div class="verbatim">begin{simpledocument2}{

   {$toc_anchor}{Table of Contents}
   {$day}{\system{date}{{+%e}}}
   {$month}{\system{date}{{+%B}}}
   {$year}{\system{date}{{+%Y}}}
   {$toc_date}{\!$month \!$day, \!$year}
   {$keywords}{html abstraction and extension language,
         html with macros,
         html authoring framework
   }
   {$html_title}{A text-based authoring tool for HTML}
   {$title}{Aephea}
   {$subtitle}{Effective and adaptable HTML authoring}
   {$author}{Stijn van Dongen and Moniek Hopman}

   {$css_import}{}
      
   {$css_append}{
      \zinsert{contrib/reaper2.css}
      body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
   }
}</div>
<p class="asd_car">
The file <tt>contrib/reaper2.css</tt> can be
<a class="local" href="src/aephea-latest/mac/contrib/reaper2.css">viewed here</a>.
The result of omitting these rules from the document can be
<a class="local" href="index-bare.html">seen here</a>.
</p>
</div>
</div>

<a name="feat"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#feat">Features</a></div><div class="sec_num"><a class="intern" href="#toc2"><span class="sec_num">2</span></a></div></div>
<p class="asd_par">
Aephea has the following features.
</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">thorough</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
As opposed to <i>ad hoc</i>. Lightweight mark-up languages are a dime a dozen,
but nearly all of them have staggeringly improvised, free-style and brittle
syntaxes. You can find many such languages on
<a class="local" href="http://micans.org/zoem/ecosphere.html">this list of macro and mark-up languages</a>.
As for Aephea, its claim to thoroughness is advocated below.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">strict</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Aephea makes it nearly impossible to write <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> that is not conforming.
Closing tags are enforced by a strict syntax, as accepted by
by <a target="_parent" class="extern" href="http://micans.org/zoem">zoem</a>.
Aephea files are processed by zoem and the latter will
complain if scopes are not properly nested. Characters that are special to
<abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> are recognized by virtue of zoem's scoping design and are
automatically escaped. An example with its rendering is this:
</p>
<div class="verbatim">\par{A paragraph with \strong{some &amp; sundry} suggested strongly.}</div>
<div class="example"><p class="asd_par">A paragraph with <strong>some &amp; sundry</strong> suggested strongly.</p></div>
<p class="asd_par">
<a name="ahtml">This</a> example uses Aephea definitions for <i>paragraph</i> and
<i>strong</i>. It can be gleaned from the example that zoem syntax is
reminiscent of TeX syntax. It has only a single meta-character, the
backslash. Aephea introduces a limited number of convenience authoring
elements, and is very much designed to be adapted and extended. It is
possible to write the preceding example in the same syntax in a style
reflecting raw <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>.
</p>
<div class="verbatim">\&lt;p class="myclass"&gt;{A paragraph with \&lt;strong&gt;{some &amp; sundry}
suggested strongly}</div>
<p class="asd_par">
The syntax enforces correct nesting and closing of <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> elements. In
Aephea-related documentation this syntax is for ease of reference
called <abbr class="ucase" title="Aephea Hyper Text Markup Language">A-HTML</abbr>, for Aephea-<abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>. The <abbr class="ucase" title="Aephea Hyper Text Markup Language">A-HTML</abbr> abbreviation is not used in any
other way. In particular, Aephea documents are commonly given a <tt>.azm</tt>
file name suffix, which is the established suffix for files processed by
zoem.
</p>
<p class="asd_par">
These examples also show that ampersands do not require special
treatment, as they, and angle brackets, are automatically escaped by zoem,
Aephea's processor.
It is however possible to inject raw <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> if desired. The following
example introduces the <i>plus-minus</i> &plusmn; character entity
and uses the same syntax for writing the ampersand character.
</p>
<div class="verbatim">\par{A paragraph with \strong{\@e{plusmn} some \@e{amp} sundry}
suggested strongly.}</div>
<div class="example"><p class="asd_par">A paragraph with <strong>&plusmn; some &amp; sundry</strong>
suggested strongly.</p></div>
<p class="asd_par">
The <tt>\@e{txt}</tt> syntax expects <tt>txt</tt> to be the name of a valid <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>
character entity. The existence of such an element is currently unchecked.
For this and a few other cases it is recommended
to follow Aephea document processing always with an <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>
checker such as <a target="_parent" class="extern" href="http://tidy.sourceforge.net/">tidy</a>. No
errors or warnings should occur when using tidy.
</p>
<p class="asd_par">
Aephea is able to recognize ampersands and other characters that are
special to <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> because zoem distinguishes different scopes
while it processes text. These are respectively called <em>device scope</em>
and <em>plain scope</em>. Device scope is introduced by syntax such as
<tt>\&lt;tag attr="value" title="device scope here"&gt;{ content; plain scope here }</tt>,
<tt>\@e{entity}</tt>, and <tt>\@{raw html}</tt>.
For more information refer to the
<a target="_parent" class="extern" href="http://micans.org/zoem/doc/zum.html">Zoem User's Manual</a>.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">cascading</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Use of <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> style rules and classes is favoured wherever possible.
<abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> files can be imported and exported. The current listing for
example, uses a <i>wordlist</i> class to style the listing of
Aephea characteristics (of which you are now reading <i>cascading</i>).
The class is defined in the preamble, and the listing is
introduced as follows.
</p>
<div class="verbatim">\begin{itemize}{
   {$flow}{cascade}
   {$interitem}{1}
   {$align}{left}
   {$class_item}{wordlist}
}</div>
<p class="asd_car">
If a particular element needs styling and no Aephea hook exists,
the preferred way of styling it is to enclose it in an <abbr class="ucase" title="Aephea Hyper Text Markup Language">A-HTML</abbr> div tag,
as below. The class <tt>myclass</tt> can either be styled in the document
preamble or in a style sheet that is imported.
</p>
<div class="verbatim">\&lt;div class="myclass"&gt;{
 ...
}</div>
<p class="asd_par">
For this particularly common case, a shorthand form
<tt>\div{myclass}{...}</tt> exists. Its definition is simple:
</p>
<div class="verbatim">\def{div#2}{\&lt;div class="\1"&gt;{\2}}
\def{span#2}{\&lt;span class="\1"&gt;{\2}}
</div>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">lay-out abstractions</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Aephea supports lay-out abstractions such as lists for which the appearance
can be styled to a great extent in a convenient, unobtrusive and localized
manner, as indicated in the example above. These abstractions can nest, and
their display properties are controlled using <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> properties and classes.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">structuring abstractions</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Aephea provides document structuring abstractions such as
sections and subsections at arbitrary levels,
table of contents, counters, labels and more.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">thin</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Aephea introduces just a few convenient authoring constructs and interposes
<abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> in a more succinct, powerful and expressive syntax called
<a class="intern" href="#ahtml"><abbr class="ucase" title="Aephea Hyper Text Markup Language">A-HTML</abbr></a>, for ease of reference.
The authoring constructs are written in the same syntax and present only a thin
abstraction layer by virtue of being small and simple. The
result stays close to raw <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and new abstraction layers are easily created.
Rather than introducing an entire ontology of document elements,
Aephea introduces the ones most needed. For document elements
not provided by Aephea either <abbr class="ucase" title="Aephea Hyper Text Markup Language">A-HTML</abbr> is used or the means exist to
encode them.
</p>
<p class="asd_par">
On the one hand it is possible to use Aephea or zoem itself as a thin
convenience layer and generate <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> directly. An example of this is to
simply write the following.
</p>
<div class="verbatim">\&lt;h1&gt;{Opening statements}</div>
<p class="asd_par">
This results in an <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> <tt>&lt;h1&gt;</tt> element. On the other hand Aephea provides
<tt>sec1</tt>, <tt>sec2</tt>, <tt>sec3</tt> &hellip; macros that create anchors to the
introduced element, keep track of section counters, update the table of
contents, and that can be styled using style sheets. The corresponding usage
would be equally simple however.
In the next example the string <tt>os</tt> defines the label for this element. It
can be used elsewhere in the document to link to the element, in
a variety of ways.
</p>
<div class="verbatim">\sec1{os}{Opening statements}</div>
<p class="asd_par">
Aephea does not introduce a new element for block quotes. Instead one
simply uses the <tt>&lt;blockquote&gt;</tt> element, wrapped in <abbr class="ucase" title="Aephea Hyper Text Markup Language">A-HTML</abbr>.
</p>
<div class="verbatim">\&lt;blockquote&gt;{
   There has grown up in the minds of certain groups in this country the
   notion that because a man or a corporation has made a profit out of the
   public for a number of years, the government and the courts are charged
   with the duty of guaranteeing such profit in the future, even in the face
   of changing circumstances and contrary public interest. This strange
   doctrine is not supported by statute nor common law. Neither individuals
   nor corporations have any right to come into court and ask that the clock
   of history be stopped, or turned back, for their private benefit.}
</div>
<p class="asd_par">
Aephea documents are thus a hybrid of higher-level Aephea elements
and <abbr class="ucase" title="Aephea Hyper Text Markup Language">A-HTML</abbr>. If desired, it is possible to encode a new element
for a specific purpose (that could for example map to a styled
<tt>&lt;blockquote&gt;</tt> element) either in an Aephea document itself
or in a definition file to be loaded by the document.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">adaptable</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The full set of Aephea definitions, as written in zoem, comprises
approximately 600 instructions. New Aephea definitions are easy to write.
Repetitive elements and tasks can be controlled in zoem.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">encapsulation</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A zoem facility called an environment is used to encapsulate larger scopes
that require more state such as lists and enumerations. Environments may
nest and the associated states are tracked automatically. Environment states
are encoded in visually distinctive key-value lists.
</p>
<p class="asd_par">
Zoem provides the means to fully separate content from mark-up in
the <tt>apply</tt> primitive, which takes a macro and applies it to a list.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist"
style="">expressive</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Programmable macro facilities provide abstraction and standard control operators
including branching and iteration. Dictionary stacks provide nested namespaces.
Comprehensive IO, arithmetic, system commands, regular expressions
and other facilities make zoem a rich development platform and the Aephea
definitions hopefully succinct and readable.
</p>
</div>
</div>

<a name="versioning"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#versioning">Versioning</a></div><div class="sec_num"><a class="intern" href="#toc3"><span class="sec_num">3</span></a></div></div>
<p class="asd_par">
The <a class="local" href="src/aephea-latest/ChangeLog">Change Log</a> may be of interest.
</p>
<p class="asd_par">
The Aephea packages <tt>pud/man.zmm</tt> and <tt>pud/faq.zmm</tt> are very stable. For
now there is just a single stable version.
</p>
<p class="asd_par">
The package <tt>simpledocument.zmm</tt> is more actively developed. Changes that
are not compatible with existing documents lead to a new version of the package.
It is still early days, so the latest version is <tt>simpledocument2.zmm</tt>.
</p>

<a name="aim"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#aim">Aims and constraints</a></div><div class="sec_num"><a class="intern" href="#toc4"><span class="sec_num">4</span></a></div></div>
<p class="asd_par">
The Aephea framework for now provides a small set of authoring
components that should cover most if not all basic authoring needs.
The design goals are:
</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&ndash;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Output <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> should be fully conforming.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&ndash;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
All authoring aspects of the output <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> should be subject and amenable to
styling by style sheets, either by <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> preambles or import files.
Note that <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> preambles are visible in the Aephea documents themselves;
for an example refer to <a class="intern" href="#example">Example source of an Aephea document</a>.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&ndash;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Aephea source should be compact and easy to read.
</p>
</div>
</div>

<a name="short"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#short">Costs, shortcomings and limitations (annotated)</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5</span></a></div></div>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&ndash;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The current set of Aephea definitions can undoubtedly be improved. It is the
work of a single person, not nearly knowledgeable enough about document styling
frameworks, with bad taste, working in their spare time. Without a doubt it
would benefit from contributions and modifications by others, and these are
very much welcome.
</p>
<p class="asd_par">
The <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> specifications offer a very rich document description
and accession model.
It is for example possible to generate section counters
automatically via style sheet rules, and to control enumerations
and lists to a great extent using style properties.
The current Aephea definitions do not take advantage of this. It is
conceivable that in these and other areas Aephea will increasingly use
mechanisms provided by pure <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr>. In most cases this should only
affect the internal Aephea definitions rather than the Aephea elements
themselves.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&ndash;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Importantly, Aephea for now only offers extended support for a single type
of document called <tt>simpledocument</tt>, which can to some extent be styled
using <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr>. The current document is an example of this type. Aephea's claim
is, hopefully rightfully, that <tt>simpledocument</tt> is pleasant to use,
extensible and customisable, and that other document types are easy to
develop.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&ndash;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Attribute syntax is not yet verified. For this and other cases it
is recommended to validate Aephea output with an <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> checker such
as <a target="_parent" class="extern" href="http://tidy.sourceforge.net/">tidy</a>.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&ndash;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Aephea is not Unicode-enabled in the sense that it cannot represent
Unicode characters internally. It operates on simple byte streams.
Documents encoded in UTF-8 should pass through Aephea without any issues.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&ndash;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Aephea source is defined in macros. The mechanistic process of correct
replay of macro definition and expansion is much more magical than pure <abbr class="ucase" title="Extensible Markup Language">XML</abbr>
transformational processing. James Clark, the author of groff and expat,
and contributor to various <abbr class="ucase" title="Extensible Markup Language">XML</abbr>-related standards, offered the following on
this subject:
</p>
<blockquote>
The problem with TeX and troff is that you're trying to use one language to
do three rather different things. You're using it to mark up your documents,
like <abbr class="ucase" title="Extensible Markup Language">XML</abbr>; you're using it as a style language, like <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr> or <abbr class="ucase" title="Extensible Stylesheet Language">XSL</abbr>; and
you're using it to write programs to do the formatting. Using one language
for all three separate requirements makes it suboptimal for all of them, in
my view.
It's suboptimal for markup because, if you have a document written in TeX or
troff, it's very hard to do anything with it other than run it through TeX
or troff, so that limits reuse.
It's suboptimal for writing formatting programs because it got this bizarre
syntax with backslashes all over the place, which makes the whole thing
unreadable. And it's not a real programming language. One lesson I drew from
TeX and groff is that you want a real programming language, not a macro
processing language.
</blockquote>
<div class="quote_attribution">
<i>A Triumph of Simplicity: James Clark on Markup Languages and XML</i><br>
July 01, 2001, Dr.Dobb's Journal.</div>
<p class="asd_par">
This is true enough. It is nonetheless not very pleasant to write <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> or
<abbr class="ucase" title="Extensible Markup Language">XML</abbr> directly due to their repetitiveness, verbosity, and lack of
programmability, the issues addressed by Aephea. Regarding syntax,
convenience is probably a matter of taste, and one person's bizarre is
another person's favourite. Regarding formatting, Aephea is not a markup
language, but simply extends and supports <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>. Regarding a real
programming language &hellip; I've found zoem's <i>dictionary stacks</i> a
veritable programmability boon. Finally, I realise that James Clark was
addressing the titans troff and TeX, not the miniscule project that is
presently aephea.
</p>
<p class="asd_par">
The gap between magical macro processing and transformational processing is
very real, and provides a view on the gaping abyss between ease-of-writing
for humans and ease-of-processing for programs. As Tim Berners-Lee once said
(in an <abbr class="ucase">MIT</abbr> Technology review interview for which I
have failed to find the original source so far), <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> was never intended to
be encoded manually.
</p>
</div>
</div>

<a name="question"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#question">Questions and contributions</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6</span></a></div></div>
<p class="asd_par">
My current belief system includes the premise that only one other person
(identified only as <tt>J.</tt>) uses Aephea, specifically the PUD macros.
If you want to convince me otherwise, have questions to ask or contributions
to share, please <a target="_parent" class="extern" href="http://micans.org/stijn/contact.html">contact me</a>.
If at some point it seems that more than a handful of people use it, it would
probably be a good idea to instigate a news group or mailing list.
</p>

<a name="history"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#history">History</a></div><div class="sec_num"><a class="intern" href="#toc7"><span class="sec_num">7</span></a></div></div>
<p class="asd_par">
The preceding section may sound like a sorry state of affairs, but
the history of Aephea is simply that of a goal pursued and achieved
(a.k.a. itch scrutinized and scratched).
The goal I pursued was to have manual pages written in <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and troff for
various bits of software I had written. Being unhappy about existing
solutions, most of which utilised transformations of one format to another,
I envisioned a bottom-up solution where micro-formats can be created at
will. The formats derive expressive power from macro and programming
facilities, and can be mapped to different external formats (a.k.a.
<i>devices</i>) by a built-in character filtering mechanism that distinguishes
between content scope and device scope.
</p>
<p class="asd_par">
The macro/programming facilities with character filtering capabilities
resulted in <a class="local" href="http://micans.org/zoem">zoem</a>, which was fun and
instructive to create. The micro-format to create manual pages in <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and
troff ended up as <a class="local" href="http://micans.org/pud"><acronym class="ucase" title="Portable Unix Documentation">PUD</acronym></a> (Portable Unix
Documentation), and it does exactly what it needs to do. Having written
<acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> macros that output to <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> manual pages, I began to use them to write
web pages as well. This gradually took shape as a different authoring tool,
unpublished, with many loose ends. For a long time zoem and <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> were
shipped together, and the web page macros began to resemble spaghetti. The
loose ends started to annoy, the web page macros were wrapped up and spun
off as Aephea, with the <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> package shipped along. The end result is
easier to maintain for me, the low-level language zoem finally separated
from the micro-formats shipped in Aephea.
</p>
<p class="asd_par">
The <a class="local" href="src/aephea-latest/ChangeLog">Aephea Change Log</a> contains
a succinct summary of Aephea changes.
</p>

<a name="install"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#install">Installing Aephea</a></div><div class="sec_num"><a class="intern" href="#toc8"><span class="sec_num">8</span></a></div></div>
<p class="asd_par">
Download Aephea <a class="local" href="src">here</a>.
It is recommended to install with
</p>
<div class="verbatim">./configure --prefix=$PREFIX</div>
<p class="asd_par">
Files will be installed in $PREFIX/share/aephea, e.g.
</p>
<div class="verbatim">$PREFIX/share/aephea/aephea/simpledocument.zmm
$PREFIX/share/aephea/aephea/simpledocument.css
$PREFIX/share/aephea/pud/man.zmm
$PREFIX/share/aephea/pud/faq.zmm</div>
<p class="asd_par">
Definition files are loaded in Aephea documents like this:</p>
<div class="verbatim">\import{aephea/simpledocument.zmm}     
\import{pud/man.zmm}                   
\import{pud/faq.zmm}                   
</div>
<p class="asd_par">
In order to have zoem find the Aephea definition and CSS files
automatically, <a class="local" href="http://micans.org/zoem/src">install it</a>
(from the unpacked zoem sources) with
</p>
<div class="verbatim">./configure --with-includepath=$PREFIX/share/aephea --prefix=$OTHERPREFIX</div>
<p class="asd_par">
Of course, <tt>$OTHERPREFIX</tt> can be chosen the same as <tt>$PREFIX</tt>.
</p>

<a name="example"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#example">Example source of an Aephea document</a></div><div class="sec_num"><a class="intern" href="#toc9"><span class="sec_num">9</span></a></div></div>
<p class="asd_par">
As a comprehensive example, this last section contains the entire source for
the page you are now reading.
</p>
<div class="recipe">
                        \: normally one uses \import{aephea/simpledocument.zmm}
\import{../aephea/simpledocument2.zmm}

                        \: import some definitions shared with other documents.
\import{aephea.shared}

\: the sequence \: introduces a comment until end of line.
\: Another way of commenting is this:

\""{
   Larger comments that span multiple lines can be made like this.  This can be
   used to quickly outcomment portions of a document. At the end of
   this document it is shown how to outcomment a trailing portion
   with \done.
   }


\set{{modes}{c}}{COLOUR1}{#F2E6E6}
\set{{modes}{c}}{COLOUR2}{#006600}

\begin{simpledocument2}{

   {$toc_anchor}{Table of Contents}
   {$day}{\system{date}{{+%e}}}
   {$month}{\system{date}{{+%B}}}
   {$year}{\system{date}{{+%Y}}}
   {$toc_date}{\!$month \!$day, \!$year}
   {$keywords}{html abstraction and extension language,
         html with macros,
         html authoring framework
   }
   {$html_title}{A text-based authoring tool for HTML}
   {$title}{Aephea}
   {$subtitle}{Effective and adaptable HTML authoring}
   {$author}{Stijn van Dongen and Moniek Hopman}

               \: not used.
               \: example of usage would be {$css_import}{{url1}{url2}...{urlN}}
   {$css_import}{}
      
   {$css_append}{
      \zinsert{contrib/reaper2.css}
      body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
   }
}


\set{m#1}{\v{\protect{\1}}}
\set{example#1}{\div{example}{\1}}


\:  -----  :::  -----  :::  -----  :::  -----  :::  -----  :::  -----  :/


\&lt;div id=asd_leftcolumn&gt;{
   \"asd::maketoc"
}

\&lt;div id=asd_document_outer&gt;{
                                       \"asd::add-toc-start"{Start}
\&lt;div id=asd_document&gt;{

   \&lt;div id="asd_date"&gt;{\$toc_date}
   \&lt;div id="asd_version"&gt;{aephea-\finsert{stamp.stamp}}

   \&lt;div id="asd_title"&gt;{\$title}
   \&lt;div id="asd_subtitle"&gt;{\$subtitle}

\:. .:. .:. .:. .:. .:. .:. .:. .:. .:. .:. .:/


\sec1{aepheanutshell}{Aephea in a nutshell}

\par{
   The Hyper Text Markup Language, abbreviated and more commonly known as \html,
   in conjunction with Cascading Style Sheets (\css), is well equipped
   to deliver documents with beautiful layout,
   consistent styling, good typography, and last but not least support
   for enhanced accessibility.
   Its use as a document typesetting technology will
   only increase, off-line as well as on-line.
   It is however cumbersome (although certainly possible) to
   write \html directly. Reasons for this are its verbosity, repetitiveness,
   and lack of abstraction mechanisms for authors.  Aephea is a text-based
   authoring tool that aims to fill this gap.
   }

\par{
   Aephea enforces \html well-formedness
   with a simpler and stricter syntax. It provides useful extensions and
   abstractions as well as facilities for adding new ones. Aephea
   stays close to \html itself and utilizes \css extensively.
   It is possible to write near-raw \html and to build powerful
   abstractions in a single unified framework.
   }

\par{
   Aephea is pronounced \it{ay - 'fee - ah}, or \it{'ee - fee - ah}, or any
   amalgam of the two, and stands somewhat grandiosely for \em{Adaptable
   Exo-skeleton for Practical \html Extension and Abstraction}.
   It is a thin, expressive, and programmable framework
   for creating \html documents, aimed at people who are familiar with
   \html and Cascading Style Sheets, or intending to become so.
   Three micro-formats are currently shipped with it.
   }

\begin{itemize}{
   {$flow}{cascade}
   {$interitem}{1}
   {$align}{left}
   {$class_item}{namelist}
}

\item{pud::man}
\car{
   A format in the \lref{http://micans.org/pud}{Portable Unix Documentation}
   section for writing manual pages with output in both \html and troff, with
   further troff-derived outputs in \pdf, PostScript, and plain text.
   }

\item{pud::faq}
\car{
   A format in the \lref{http://micans.org/pud}{Portable Unix Documentation}
   section for writing FAQ documents with output in both \html and troff, with
   further troff-derived outputs in \pdf, PostScript, and plain text.
   }

\item{simpledocument}
\car{
   A base format for writing \html documents. The first goal is to  push
   as much control to \css rules that are closely tied to the document.
   The second goal is for \v{aephea/simpledocument} to be an example
   format, to be extended, varied, and replaced wholesale.
   }

\par{
   The updated version is now called \v{aephea/simpledocument2}, and
   is used by this document. All the lay-out rules are contained in
   a separate style file with the idiosyncratic name \v{reaper2.css}.
   It is shipped with aephea and can be accessed as \v{contrib/reaper2.css}.
   The code below shows the essential make-up of an aephea document.
   The \sc{CSS} rules are included in the \sc{HTML} \v{&lt;head&gt;} element
   so that the document is entirely self-contained.
   }

\verbatim{\protect{begin{simpledocument2}{

   {$toc_anchor}{Table of Contents}
   {$day}{\system{date}{{+%e}}}
   {$month}{\system{date}{{+%B}}}
   {$year}{\system{date}{{+%Y}}}
   {$toc_date}{\!$month \!$day, \!$year}
   {$keywords}{html abstraction and extension language,
         html with macros,
         html authoring framework
   }
   {$html_title}{A text-based authoring tool for HTML}
   {$title}{Aephea}
   {$subtitle}{Effective and adaptable HTML authoring}
   {$author}{Stijn van Dongen and Moniek Hopman}

   {$css_import}{}
      
   {$css_append}{
      \zinsert{contrib/reaper2.css}
      body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
   }
}}}\:/


\car{
   The file \v{contrib/reaper2.css} can be
   \lref{src/aephea-latest/mac/contrib/reaper2.css}{viewed here}.
   The result of omitting these rules from the document can be
   \lref{index-bare.html}{seen here}.
   }


\end{itemize}


\sec1{feat}{Features}
\par{
   Aephea has the following features.
}

\begin{itemize}{
   {$flow}{cascade}
   {$interitem}{1}
   {$align}{left}
   {$class_item}{wordlist}
}
\item{thorough}
\car{
   As opposed to \it{ad hoc}. Lightweight mark-up languages are a dime a dozen,
   but nearly all of them have staggeringly improvised, free-style and brittle
   syntaxes.  You can find many such languages on
\lref{http://micans.org/zoem/ecosphere.html}{this list of macro and mark-up languages}.
   As for Aephea, its claim to thoroughness is advocated below.
   }


\item{strict}
\car{
   Aephea makes it nearly impossible to write \html that is not conforming.
   Closing tags are enforced by a strict syntax, as accepted by
   by \aref{http://micans.org/zoem}{zoem}.
   Aephea files are processed by zoem and the latter will
   complain if scopes are not properly nested.  Characters that are special to
   \html are recognized by virtue of zoem's scoping design and are
   automatically escaped.  An example with its rendering is this:
   }

\verbatim{\protect{\:/
\par{A paragraph with \strong{some &amp; sundry} suggested strongly.}}}
   
\example{\par{A paragraph with \strong{some &amp; sundry} suggested strongly.}}

\par{
   \enref{ahtml}{This} example uses Aephea definitions for \it{paragraph} and
   \it{strong}.  It can be gleaned from the example that zoem syntax is
   reminiscent of TeX syntax.  It has only a single meta-character, the
   backslash.  Aephea introduces a limited number of convenience authoring
   elements, and is very much designed to be adapted and extended. It is
   possible to write the preceding example in the same syntax in a style
   reflecting raw \html.
   }

\verbatim{\protect{\:/
\&lt;p class="myclass"&gt;{A paragraph with \&lt;strong&gt;{some &amp; sundry}
suggested strongly}}}

\par{
   The syntax enforces correct nesting and closing of \html elements.  In
   Aephea-related documentation this syntax is for ease of reference
   called \ahtml, for Aephea-\html.  The \ahtml abbreviation is not used in any
   other way. In particular, Aephea documents are commonly given a \v{.azm}
   file name suffix, which is the established suffix for files processed by
   zoem.

   }

\par{
   These examples also show that ampersands do not require special
   treatment, as they, and angle brackets, are automatically escaped by zoem,
   Aephea's processor.
   It is however possible to inject raw \html if desired. The following
   example introduces the \it{plus-minus} \@e{plusmn} character entity
   and uses the same syntax for writing the ampersand character.
   }

\verbatim{\protect{\:/
\par{A paragraph with \strong{\@e{plusmn} some \@e{amp} sundry}
suggested strongly.}}}
   
\example{\par{A paragraph with \strong{\@e{plusmn} some \@e{amp} sundry}
suggested strongly.}}

\par{
   The \v{\\@e{txt}} syntax expects \v{txt} to be the name of a valid \html
   character entity.  The existence of such an element is currently unchecked.
   For this and a few other cases it is recommended 
   to follow Aephea document processing always with an \html
   checker such as \aref{http://tidy.sourceforge.net/}{tidy}. No
   errors or warnings should occur when using tidy.
   }

\""{     Let's not go into this much detail for now; outcommented.
   Fully raw \html can be
   injected by using \v{\\@{text}} syntax. An equivalent form for \v{\\@e{amp}}
   is thus \v{\\@{&amp;amp;}}. However, arbitrarily long stretches of \html may be
   inserted. Another valid example is \v{\\@{&lt;hr noshade size="1"&gt;}}. The
   prefered form is in \ahtml however, and is written
   \v{\\&lt;*hr noshade size="1"&gt;}, where the asterisk is used to indicate that
   the element does not need to be closed.

   The difference between \ahtml (\v{\\&lt;tag attr="value"&gt;{content}}) and raw
   \html (\v{\\@{&lt;tag attr="value"&gt;content&lt;/tag&gt;}} or \v{\\@{&lt;tag
   attr="value"&gt;} content \\@{&lt;/tag&gt;}}) is that the former ensures correct
   closing and nesting of tags, whereas the latter is not checked.  For that
   reason, \ahtml is recommended wherever possible.
   }

\par{
   Aephea is able to recognize ampersands and other characters that are
   special to \html because zoem distinguishes different scopes
   while it processes text. These are respectively called \em{device scope}
   and \em{plain scope}. Device scope is introduced by syntax such as
\v{\\&lt;tag attr="value" title="device scope here"&gt;{ content; plain scope here }},
\v{\\@e{entity}}, and \v{\\@{raw html}}.
   For more information refer to the
   \aref{http://micans.org/zoem/doc/zum.html}{Zoem User's Manual}.
   }

\item{cascading}
\car{
   Use of \css style rules and classes is favoured wherever possible.
   \css files can be imported and exported. The current listing for
   example, uses a \it{wordlist} class to style the listing of
   Aephea characteristics (of which you are now reading \it{cascading}).
   The class is defined in the preamble, and the listing is
   introduced as follows.
   }

\verbatim{\protect{\:/
\begin{itemize}{
   {$flow}{cascade}
   {$interitem}{1}
   {$align}{left}
   {$class_item}{wordlist}
}}}

\car{
   If a particular element needs styling and no Aephea hook exists,
   the preferred way of styling it is to enclose it in an \ahtml div tag,
   as below. The class \v{myclass} can either be styled in the document
   preamble \""{TODO, css_append} or in a style sheet that is imported.
   }

\verbatim{\protect{\:/
\&lt;div class="myclass"&gt;{
 ...
}}}

\par{
   For this particularly common case, a shorthand form
   \v{\protect{\div{myclass}{...}}} exists. Its definition is simple:
   }

\verbatim{\protect{\:/
\def{div#2}{\&lt;div class="\1"&gt;{\2}}
\def{span#2}{\&lt;span class="\1"&gt;{\2}}
}}

\item{lay-out abstractions}
\car{
   Aephea supports lay-out abstractions such as lists for which the appearance
   can be styled to a great extent in a convenient, unobtrusive and localized
   manner, as indicated in the example above. These abstractions can nest, and
   their display properties are controlled using \css properties and classes.
   }

\item{structuring abstractions}
\car{
   Aephea provides document structuring abstractions such as
   sections and subsections at arbitrary levels,
   table of contents, counters, labels and more.
   }
      
\item{thin}
\car{
   Aephea introduces just a few convenient authoring constructs and interposes
   \html in a more succinct, powerful and expressive syntax called
   \iref{ahtml}{\ahtml}, for ease of reference.
   The authoring constructs are written in the same syntax and present only a thin
   abstraction layer by virtue of being small and simple.  The
   result stays close to raw \html and new abstraction layers are easily created.
   Rather than introducing an entire ontology of document elements,
   Aephea introduces the ones most needed. For document elements
   not provided by Aephea either \ahtml is used or the means exist to
   encode them.
   }

\par{
   On the one hand it is possible to use Aephea or zoem itself as a thin
   convenience layer and generate \html directly. An example of this is to
   simply write the following.
   }

\verbatim{\protect{\&lt;h1&gt;{Opening statements}}}

\par{
   This results in an \html \v{&lt;h1&gt;} element. On the other hand Aephea provides
   \m{sec1}, \m{sec2}, \m{sec3} \@{&amp;hellip;} macros that create anchors to the
   introduced element, keep track of section counters, update the table of
   contents, and that can be styled using style sheets. The corresponding usage
   would be equally simple however.
   In the next example the string \v{os} defines the label for this element. It
   can be used elsewhere in the document to link to the element, in
   a variety of ways.
   }

\verbatim{\protect{\:/
\sec1{os}{Opening statements}}}

\par{
   Aephea does not introduce a new element for block quotes. Instead one
   simply uses the \v{&lt;blockquote&gt;} element, wrapped in \ahtml.
   }

\verbatim{\protect{\:/
\&lt;blockquote&gt;{
   There has grown up in the minds of certain groups in this country the
   notion that because a man or a corporation has made a profit out of the
   public for a number of years, the government and the courts are charged
   with the duty of guaranteeing such profit in the future, even in the face
   of changing circumstances and contrary public interest. This strange
   doctrine is not supported by statute nor common law. Neither individuals
   nor corporations have any right to come into court and ask that the clock
   of history be stopped, or turned back, for their private benefit.}
}}

\par{
   Aephea documents are thus a hybrid of higher-level Aephea elements
   and \ahtml. If desired, it is possible to encode a new element
   for a specific purpose (that could for example map to a styled
   \v{&lt;blockquote&gt;} element) either in an Aephea document itself
   or in a definition file to be loaded by the document.
   }

\item{adaptable}
\car{
   The full set of Aephea definitions, as written in zoem, comprises
   approximately 600 instructions. New Aephea definitions are easy to write.
   Repetitive elements and tasks can be controlled in zoem.
   }

\item{encapsulation}
\car{
   A zoem facility called an environment is used to encapsulate larger scopes
   that require more state such as lists and enumerations. Environments may
   nest and the associated states are tracked automatically.  Environment states
   are encoded in visually distinctive key-value lists.
   }

\par{
   Zoem provides the means to fully separate content from mark-up in
   the \m{apply} primitive, which takes a macro and applies it to a list.
   }

\item{expressive}
\car{
   Programmable macro facilities provide abstraction and standard control operators
   including branching and iteration.  Dictionary stacks provide nested namespaces.
   Comprehensive IO, arithmetic, system commands, regular expressions
   and other facilities make zoem a rich development platform and the Aephea
   definitions hopefully succinct and readable.
   }


\end{itemize}

\sec1{versioning}{Versioning}

\par{
   The \lref{src/aephea-latest/ChangeLog}{Change Log} may be of interest.
   }

\par{
   The Aephea packages \v{pud/man.zmm} and \v{pud/faq.zmm} are very stable. For
   now there is just a single stable version.
   }

\par{
   The package \v{simpledocument.zmm} is more actively developed. Changes that
   are not compatible with existing documents lead to a new version of the package.
   It is still early days, so the latest version is \v{simpledocument2.zmm}.
   }


\sec1{aim}{Aims and constraints}
\par{
   The Aephea framework for now provides a small set of authoring
   components that should cover most if not all basic authoring needs.
   The design goals are:
   }
   
\begin{itemize}{
   {flow}{compact}
   {align}{right}
   {mark}{\@{&amp;ndash;}}
   {interitem}{1}
}
\item
\car{
   Output \html should be fully conforming.
   }

\item
\car{
   All authoring aspects of the output \html should be subject and amenable to
   styling by style sheets, either by \css preambles or import files.
   Note that \css preambles are visible in the Aephea documents themselves;
   for an example refer to \secref{example}.
   }

\item
\car{
   Aephea source should be compact and easy to read.
   }

\end{itemize}


\sec1{short}{Costs, shortcomings and limitations (annotated)}

\begin{itemize}{
   {flow}{compact}
   {align}{right}
   {mark}{\@{&amp;ndash;}}
   {interitem}{1}
}

\item
\car{
   The current set of Aephea definitions can undoubtedly be improved. It is the
   work of a single person, not nearly knowledgeable enough about document styling
   frameworks, with bad taste, working in their spare time.  Without a doubt it
   would benefit from contributions and modifications by others, and these are
   very much welcome.
   }

\par{
   The \html and \css specifications offer a very rich document description
   and accession model.
   It is for example possible to generate section counters
   automatically via style sheet rules, and to control enumerations
   and lists to a great extent using style properties.

   The current Aephea definitions do not take advantage of this. It is
   conceivable that in these and other areas Aephea will increasingly use
   mechanisms provided by pure \html and \css. In most cases this should only
   affect the internal Aephea definitions rather than the Aephea elements
   themselves.

   }


\item
\car{
   Importantly, Aephea for now only offers extended support for a single type
   of document called \v{simpledocument}, which can to some extent be styled
   using \css. The current document is an example of this type.  Aephea's claim
   is, hopefully rightfully, that \v{simpledocument} is pleasant to use,
   extensible and customisable, and that other document types are easy to
   develop.
   }


\item
\car{
   Attribute syntax is not yet verified. For this and other cases it
   is recommended to validate Aephea output with an \html checker such
   as \aref{http://tidy.sourceforge.net/}{tidy}.
   }

\item
\car{
   Aephea is not Unicode-enabled in the sense that it cannot represent
   Unicode characters internally. It operates on simple byte streams.
   Documents encoded in UTF-8 should pass through Aephea without any issues.
   }

\item
\car{
   Aephea source is defined in macros. The mechanistic process of correct
   replay of macro definition and expansion is much more magical than pure \xml
   transformational processing.  James Clark, the author of groff and expat,
   and contributor to various \xml-related standards, offered the following on
   this subject:
   }

\&lt;blockquote&gt;{
   The problem with TeX and troff is that you're trying to use one language to
   do three rather different things. You're using it to mark up your documents,
   like \xml; you're using it as a style language, like \css or \xsl; and
   you're using it to write programs to do the formatting. Using one language
   for all three separate requirements makes it suboptimal for all of them, in
   my view.

   It's suboptimal for markup because, if you have a document written in TeX or
   troff, it's very hard to do anything with it other than run it through TeX
   or troff, so that limits reuse.

   It's suboptimal for writing formatting programs because it got this bizarre
   syntax with backslashes all over the place, which makes the whole thing
   unreadable. And it's not a real programming language. One lesson I drew from
   TeX and groff is that you want a real programming language, not a macro
   processing language.
   }

\div{quote_attribution}{
   \it{A Triumph of Simplicity: James Clark on Markup Languages and XML}\|
July 01, 2001, Dr.Dobb's Journal.}

\par{
   This is true enough. It is nonetheless not very pleasant to write \html or
   \xml directly due to their repetitiveness, verbosity, and lack of
   programmability, the issues addressed by Aephea.  Regarding syntax,
   convenience is probably a matter of taste, and one person's bizarre is
   another person's favourite. Regarding formatting, Aephea is not a markup
   language, but simply extends and supports \html.  Regarding a real
   programming language \@e{hellip} I've found zoem's \it{dictionary stacks} a
   veritable programmability boon.  Finally, I realise that James Clark was
   addressing the titans troff and TeX, not the miniscule project that is
   presently aephea.
   }

\par{
   The gap between magical macro processing and transformational processing is
   very real, and provides a view on the gaping abyss between ease-of-writing
   for humans and ease-of-processing for programs. As Tim Berners-Lee once said
   (in an \&lt;abbr class="ucase"&gt;{MIT} Technology review interview for which I
   have failed to find the original source so far), \html was never intended to
   be encoded manually.
   }


\end{itemize}

\sec1{question}{Questions and contributions}

\par{
   My current belief system includes the premise that only one other person
   (identified only as \v{J.}) uses Aephea, specifically the PUD macros.
   If you want to convince me otherwise, have questions to ask or contributions
   to share, please \aref{http://micans.org/stijn/contact.html}{contact me}.
   If at some point it seems that more than a handful of people use it, it would
   probably be a good idea to instigate a news group or mailing list.
   }

\sec1{history}{History}

\par{
   The preceding section may sound like a sorry state of affairs, but
   the history of Aephea is simply that of a goal pursued and achieved
   (a.k.a. itch scrutinized and scratched).
   The goal I pursued was to have manual pages written in \html and troff for
   various bits of software I had written.  Being unhappy about existing
   solutions, most of which utilised transformations of one format to another,
   I envisioned a bottom-up solution where micro-formats can be created at
   will. The formats derive expressive power from macro and programming
   facilities, and can be mapped to different external formats (a.k.a.
   \it{devices}) by a built-in character filtering mechanism that distinguishes
   between content scope and device scope.

   }

\par{
   The macro/programming facilities with character filtering capabilities
   resulted in \lref{http://micans.org/zoem}{zoem}, which was fun and
   instructive to create.  The micro-format to create manual pages in \html and
   troff ended up as \lref{http://micans.org/pud}{\pud} (Portable Unix
   Documentation), and it does exactly what it needs to do.  Having written
   \pud macros that output to \html manual pages, I began to use them to write
   web pages as well. This gradually took shape as a different authoring tool,
   unpublished, with many loose ends.  For a long time zoem and \pud were
   shipped together, and the web page macros began to resemble spaghetti.  The
   loose ends started to annoy, the web page macros were wrapped up and spun
   off as Aephea, with the \pud package shipped along.  The end result is
   easier to maintain for me, the low-level language zoem finally separated
   from the micro-formats shipped in Aephea.
   }


\par{
   The \lref{src/aephea-latest/ChangeLog}{Aephea Change Log} contains
   a succinct summary of Aephea changes.
   }


\sec1{install}{Installing Aephea}

\par{
   Download Aephea \lref{src}{here}.
   It is recommended to install with
   }

\verbatim{\protect{./configure --prefix=$PREFIX}}

\par{
   Files will be installed in $PREFIX/share/aephea, e.g.
   }

\verbatim{\protect{\:/
$PREFIX/share/aephea/aephea/simpledocument.zmm
$PREFIX/share/aephea/aephea/simpledocument.css
$PREFIX/share/aephea/pud/man.zmm
$PREFIX/share/aephea/pud/faq.zmm}}

\par{
   Definition files are loaded in Aephea documents like this:}


\verbatim{\protect{\:/
\import{aephea/simpledocument.zmm}     \: for HTML document.
\import{pud/man.zmm}                   \: for (Unix) manual page.
\import{pud/faq.zmm}                   \: for FAQ.
}}

\par{
   In order to have zoem find the Aephea definition and CSS files
   automatically, \lref{http://micans.org/zoem/src}{install it}
   (from the unpacked zoem sources) with
   }

\verbatim{\protect{\:/
./configure --with-includepath=$PREFIX/share/aephea --prefix=$OTHERPREFIX}}

\par{
   Of course, \v{$OTHERPREFIX} can be chosen the same as \v{$PREFIX}.
   }


\""{        Bad idea. Docbook bad. Docbook BAD. Aephea good.
\sec1{ideas}{Ideas}

\begin{itemize}{
   {flow}{compact}
   {align}{right}
   {mark}{\@{&amp;ndash;}}
   {interitem}{1}
}

\item
\car{
   Mapping or extending the Aephea definitions to Docbook output. This should
   be doable, and take away a lot of pain from the creation of Docbook
   documents.
   }
\end{itemize}
}



\sec1{example}{Example source of an Aephea document}
\par{
   As a comprehensive example, this last section contains the entire source for
   the page you are now reading.
   }

\recipe{\finsert{webindex.azm}}

\:. .:. .:. .:. .:. .:. .:. .:. .:. .:. .:. .:/

\"asd::add-toc-end"{End}
}}

\end{simpledocument2}

\:. .:. .:. .:. .:. .:. .:. .:. .:. .:. .:. .:/

\done

The zoem \done primitive as used above is not really necessary. What it does is
to quit processing at the current interpretation level. For the preceding use
the interpretation level is file level, so processing of the current file is
stopped. It is possible to use the section after a \done primitive as scratch
area and junk yard. This paragraph thus does not show up in the processed output.

</div>
<a name="asd_body_end"></a>
</div></div>
</body>
</html>