<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Copyright (c) 2010 Stijn van Dongen --> <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; } /* 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; } 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 } /* END aephea.base.css */ /* START aephea.asd.css */ .asd_title { text-align: center; font-size: 40px; margin-top: 1em; } .asd_subtitle { text-align: center; font-size: 25px; margin-top: 1em; } .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_and_date { margin-top: 0em; margin-bottom: 0em; position: relative; right: 0px; left: 0px; top: 0px; } .toc_and_date_TOC { margin-top: 0em; margin-bottom: 0em; position: relative; left: 0px; } .toc_and_date_DATE { margin-top: 0em; position: absolute; vertical-align: top; right: 0px; top: 0px; } .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 */ body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; } body { text-align: justify; margin-left: 8%; margin-right: 8%; } acronym.ucase, abbr.ucase { font-size: smaller; text-transform: uppercase; text-decoration: none; border-style: none; } .wordlist { font-size: 121%; font-style: italic; } .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 } .verbatim { margin-top: 1em; margin-bottom: 1em; font-size: 10pt; margin-left: 2em; font-family: courier; white-space: pre; } </style> <title>A text-based authoring tool for HTML</title> </head> <body> <div class="toc_and_date"> <div class="toc_and_date_TOC"><a class="intern" href="#toc">Table of Contents</a></div> <div class="toc_and_date_DATE">January 8, 2010</div> </div> <div class="asd_title">Aephea</div> <div class="asd_subtitle">A text-based authoring tool for HTML</div> <div class="toc_toplevel"> <a name="thetoc"></a> <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_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="toc3">3</a>.</div> <div class="toc_title toc_title1"><a name="toc_short"></a><a class="intern" href="#short">Costs, shortcomings and limitations</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_install"></a><a class="intern" href="#install">Installing Aephea</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_example"></a><a class="intern" href="#example">Example source of an Aephea document</a></div> </div> </div> <a name="aepheanutshell"></a><div class="sec_leader sec_lev1"><div class="sec_title">Aephea in a nutshell</div><div class="sec_num"><a class="intern" href="#toc1"><span class="sec_num">1</span></a></div></div> <p style="margin-bottom:0" 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. It enforces <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> well-formedness with a simpler and stricter syntax, provides useful extensions and abstractions and facilities for adding new ones, all in a single unified approach that 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. </p> <p style="margin-bottom:0" 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. It has the following features. </p> <div class=" itemize " style="margin-top:1em; font-size:100%"> <div class=" item_cascade"><div class=" item_leftalign nowrap wordlist" >strict</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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 & sundry} suggested strongly.}</div> <div class="example"><p style="margin-bottom:0" class="asd_par">A paragraph with <strong>some & sundry</strong> suggested strongly.</p></div> <p style="margin-bottom:0" 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, and that Aephea introduces its own set of authoring primitives. The syntax has only a single meta-character, the backslash. The set of Aephea authoring elements is quite limited, and very much designed to be adapted and extended, as discussed later. 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">\<p class="myclass">{A paragraph with \<strong>{some & sundry} suggested strongly}</div> <p style="margin-bottom:0" 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 style="margin-bottom:0" 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> ± 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 style="margin-bottom:0" class="asd_par">A paragraph with <strong>± some & sundry</strong> suggested strongly.</p></div> <p style="margin-bottom:0" 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 style="margin-bottom:0" 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>\<tag attr="value" title="device scope here">{ 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="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist" >cascading</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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 style="margin-top:0em; margin-bottom:0em"> 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">\<div class="myclass">{ ... }</div> <p style="margin-bottom:0" 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}{\<div class="\1">{\2}} \def{span#2}{\<span class="\1">{\2}} </div> </div> <div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist" >lay-out abstractions</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist" >structuring abstractions</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> Aephea provides document structuring abstractions such as sections and subsections at arbitrary levels, table of contents, counters, labels and more. </p> </div> <div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist" >thin</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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 style="margin-bottom:0" 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">\<h1>{Opening statements}</div> <p style="margin-bottom:0" class="asd_par"> This results in an <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> <tt><h1></tt> element. On the other hand Aephea provides <tt>sec1</tt>, <tt>sec2</tt>, <tt>sec3</tt> … 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 style="margin-bottom:0" class="asd_par"> Aephea does not introduce a new element for block quotes. Instead one simply uses the <tt><blockquote></tt> element, wrapped in <abbr class="ucase" title="Aephea Hyper Text Markup Language">A-HTML</abbr>. </p> <div class="verbatim">\<blockquote>{ 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 style="margin-bottom:0" 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><blockquote></tt> element) either in an Aephea document itself or in a definition file to be loaded by the document. </p> </div> <div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist" >adaptable</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist" >encapsulation</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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 style="margin-bottom:0" 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="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap wordlist" >expressive</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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="aim"></a><div class="sec_leader sec_lev1"><div class="sec_title">Aims and constraints</div><div class="sec_num"><a class="intern" href="#toc2"><span class="sec_num">2</span></a></div></div> <p style="margin-bottom:0" 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; font-size:100%"> <div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> Output <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> should be fully conforming. </p> </div> <div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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">Costs, shortcomings and limitations</div><div class="sec_num"><a class="intern" href="#toc3"><span class="sec_num">3</span></a></div></div> <div class=" itemize " style="margin-top:1em; font-size:100%"> <div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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 style="margin-bottom:0" 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="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> Attribute syntax is not yet verified. </p> </div> <div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> 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. </blockquote> <div class="quote_attribution"> <i>A Triumph of Simplicity: James Clark on Markup Languages and XML</i>, July 01, 2001, Dr.Dobb's Journal.</div> <p style="margin-bottom:0" class="asd_par"> This is true enough. However, 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. </p> </div> <div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">–</div></div> <div class=" item_text " style="margin-left:2em"> <p style="margin-top:0em; margin-bottom:0em"> In the short term, it is anticipated that Aephea may undergo changes that are not backward compatible. Such changes, if any, will be well documented. </p> </div> </div> <a name="install"></a><div class="sec_leader sec_lev1"><div class="sec_title">Installing Aephea</div><div class="sec_num"><a class="intern" href="#toc4"><span class="sec_num">4</span></a></div></div> <p style="margin-bottom:0" class="asd_par"> Download Aephea <a class="local" href="src/aephea-latest.tar.gz">here</a>. It is recommended to install with </p> <div class="verbatim">./configure --prefix=$PREFIX</div> <p style="margin-bottom:0" 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 style="margin-bottom:0" 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 style="margin-bottom:0" class="asd_par"> In order to have zoem find the Aephea definition and CSS files automatically, install it (from the unpacked zoem sources) with</p> <div class="verbatim">./configure --with-includepath=$PREFIX/share/aephea --prefix=$OTHERPREFIX</div> <p style="margin-bottom:0" 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">Example source of an Aephea document</div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5</span></a></div></div> <p style="margin-bottom:0" class="asd_par"> As a comprehensive example, this last section contains the entire source for the page you are now reading. </p> <div class="verbatim"> \import{../aephea/simpledocument.zmm} \: eat own dogfood. \: normally one uses \import{aephea/simpledocument.zmm} \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. } \begin{simpledocument}{ {$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}{A text-based authoring tool for HTML} {$author}{Stijn van Dongen} {$css_import}{} \: not used. \: example of usage would be {$css_import}{{url1}{url2}...{urlN}} {$css_append}{ body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; } body { text-align: justify; margin-left: 8%; margin-right: 8%; } acronym.ucase, abbr.ucase { font-size: smaller; text-transform: uppercase; text-decoration: none; border-style: none; } .wordlist { font-size: 121%; font-style: italic; } .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; } } } \"aephea::maketoc" \set{m#1}{\v{\protect{\1}}} \set{example#1}{\div{example}{\1}} \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. It enforces \html well-formedness with a simpler and stricter syntax, provides useful extensions and abstractions and facilities for adding new ones, all in a single unified approach that stays close to \html itself and utilizes \css extensively. } \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. It has the following features. } \begin{itemize}{ {$flow}{cascade} {$interitem}{1} {$align}{left} {$class_item}{wordlist} } \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 & sundry} suggested strongly.}}} \example{\par{A paragraph with \strong{some & 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, and that Aephea introduces its own set of authoring primitives. The syntax has only a single meta-character, the backslash. The set of Aephea authoring elements is quite limited, and very much designed to be adapted and extended, as discussed later. It is possible to write the preceding example in the same syntax in a style reflecting raw \html. } \verbatim{\protect{\:/ \<p class="myclass">{A paragraph with \<strong>{some & 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;}}. However, arbitrarily long stretches of \html may be inserted. Another valid example is \v{\\@{<hr noshade size="1">}}. The prefered form is in \ahtml however, and is written \v{\\<*hr noshade size="1">}, where the asterisk is used to indicate that the element does not need to be closed. The difference between \ahtml (\v{\\<tag attr="value">{content}}) and raw \html (\v{\\@{<tag attr="value">content</tag>}} or \v{\\@{<tag attr="value">} content \\@{</tag>}}) 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{\\<tag attr="value" title="device scope here">{ 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{\:/ \<div class="myclass">{ ... }}} \par{ For this particularly common case, a shorthand form \v{\protect{\div{myclass}{...}}} exists. Its definition is simple: } \verbatim{\protect{\:/ \def{div#2}{\<div class="\1">{\2}} \def{span#2}{\<span class="\1">{\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{\<h1>{Opening statements}}} \par{ This results in an \html \v{<h1>} element. On the other hand Aephea provides \m{sec1}, \m{sec2}, \m{sec3} \@{&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{<blockquote>} element, wrapped in \ahtml. } \verbatim{\protect{\:/ \<blockquote>{ 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{<blockquote>} 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{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}{\@{&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} \begin{itemize}{ {flow}{compact} {align}{right} {mark}{\@{&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. } \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: } \<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 \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. } \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. However, it is nonetheless not very pleasant to write \html or \xml directly due to their repetitiveness, verbosity, and lack of programmability. } \item \car{ In the short term, it is anticipated that Aephea may undergo changes that are not backward compatible. Such changes, if any, will be well documented. } \end{itemize} \sec1{install}{Installing Aephea} \par{ Download Aephea \lref{src/aephea-latest.tar.gz}{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, 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}{\@{&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. } \verbatim{\finsert{webindex.azm}} \end{simpledocument} \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> </body> </html>