September 5, 2012
aephea-12-248
Aephea
Effective and adaptable HTML authoring

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.

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.

Aephea is pronounced ay - 'fee - ah, or 'ee - fee - ah, or any amalgam of the two, and stands somewhat grandiosely for 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.

pud::man

A format in the 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.

pud::faq

A format in the 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.

simpledocument

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 aephea/simpledocument to be an example format, to be extended, varied, and replaced wholesale.

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

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; } } }

The file contrib/reaper2.css can be viewed here. The result of omitting these rules from the document can be seen here.

Aephea has the following features.

thorough

As opposed to 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 this list of macro and mark-up languages. As for Aephea, its claim to thoroughness is advocated below.

strict

Aephea makes it nearly impossible to write HTML that is not conforming. Closing tags are enforced by a strict syntax, as accepted by by 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:

\par{A paragraph with \strong{some & sundry} suggested strongly.}

A paragraph with some & sundry suggested strongly.

This example uses Aephea definitions for paragraph and 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.

\<p class="myclass">{A paragraph with \<strong>{some & sundry} suggested strongly}

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

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 plus-minus ± character entity and uses the same syntax for writing the ampersand character.

\par{A paragraph with \strong{\@e{plusmn} some \@e{amp} sundry} suggested strongly.}

A paragraph with ± some & sundry suggested strongly.

The \@e{txt} syntax expects 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 tidy. No errors or warnings should occur when using tidy.

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 device scope and plain scope. Device scope is introduced by syntax such as \<tag attr="value" title="device scope here">{ content; plain scope here }, \@e{entity}, and \@{raw html}. For more information refer to the Zoem User's Manual.

cascading

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 wordlist class to style the listing of Aephea characteristics (of which you are now reading cascading). The class is defined in the preamble, and the listing is introduced as follows.

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

If a particular element needs styling and no Aephea hook exists, the preferred way of styling it is to enclose it in an A-HTML div tag, as below. The class myclass can either be styled in the document preamble or in a style sheet that is imported.

\<div class="myclass">{ ... }

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

\def{div#2}{\<div class="\1">{\2}} \def{span#2}{\<span class="\1">{\2}}
lay-out abstractions

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.

structuring abstractions

Aephea provides document structuring abstractions such as sections and subsections at arbitrary levels, table of contents, counters, labels and more.

thin

Aephea introduces just a few convenient authoring constructs and interposes HTML in a more succinct, powerful and expressive syntax called A-HTML, 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 A-HTML is used or the means exist to encode them.

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.

\<h1>{Opening statements}

This results in an HTML <h1> element. On the other hand Aephea provides sec1, sec2, sec3 … 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 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.

\sec1{os}{Opening statements}

Aephea does not introduce a new element for block quotes. Instead one simply uses the <blockquote> element, wrapped in A-HTML.

\<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.}

Aephea documents are thus a hybrid of higher-level Aephea elements and A-HTML. If desired, it is possible to encode a new element for a specific purpose (that could for example map to a styled <blockquote> element) either in an Aephea document itself or in a definition file to be loaded by the document.

adaptable

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.

encapsulation

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.

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

expressive

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.

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

The package 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 simpledocument2.zmm.

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:

Output HTML should be fully conforming.

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 Example source of an Aephea document.

Aephea source should be compact and easy to read.

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.

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.

Importantly, Aephea for now only offers extended support for a single type of document called 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 simpledocument is pleasant to use, extensible and customisable, and that other document types are easy to develop.

Attribute syntax is not yet verified. For this and other cases it is recommended to validate Aephea output with an HTML checker such as tidy.

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.

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:

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.
A Triumph of Simplicity: James Clark on Markup Languages and XML
July 01, 2001, Dr.Dobb's Journal.

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 … I've found zoem's 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.

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 MIT Technology review interview for which I have failed to find the original source so far), HTML was never intended to be encoded manually.

My current belief system includes the premise that only one other person (identified only as J.) uses Aephea, specifically the PUD macros. If you want to convince me otherwise, have questions to ask or contributions to share, please 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.

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. devices) by a built-in character filtering mechanism that distinguishes between content scope and device scope.

The macro/programming facilities with character filtering capabilities resulted in zoem, which was fun and instructive to create. The micro-format to create manual pages in HTML and troff ended up as 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.

Download Aephea here. It is recommended to install with

./configure --prefix=$PREFIX

Files will be installed in $PREFIX/share/aephea, e.g.

$PREFIX/share/aephea/aephea/simpledocument.zmm $PREFIX/share/aephea/aephea/simpledocument.css $PREFIX/share/aephea/pud/man.zmm $PREFIX/share/aephea/pud/faq.zmm

Definition files are loaded in Aephea documents like this:

\import{aephea/simpledocument.zmm} \import{pud/man.zmm} \import{pud/faq.zmm}

In order to have zoem find the Aephea definition and CSS files automatically, install it (from the unpacked zoem sources) with

./configure --with-includepath=$PREFIX/share/aephea --prefix=$OTHERPREFIX

Of course, $OTHERPREFIX can be chosen the same as $PREFIX.

As a comprehensive example, this last section contains the entire source for the page you are now reading.

\: 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}} \: ----- ::: ----- ::: ----- ::: ----- ::: ----- ::: ----- :/ \<div id=asd_leftcolumn>{ \"asd::maketoc" } \<div id=asd_document_outer>{ \"asd::add-toc-start"{Start} \<div id=asd_document>{ \<div class="asd_date">{\$toc_date} \<div class="asd_version">{aephea-\finsert{stamp.stamp}} \<div class="asd_title">{\$title} \<div class="asd_subtitle">{\$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{<head>} 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 & 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. 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{\:/ \<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{versioning}{Versioning} \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}{\@{&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}{\@{&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: } \<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. 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 \<abbr class="ucase">{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. } \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}{\@{&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.