January 8, 2010
Aephea
A text-based authoring tool for HTML
Aephea in a nutshell
1

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.

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. It has the following features.

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, 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.

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

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.

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.

Aims and constraints
2

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.

Costs, shortcomings and limitations
3

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.

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

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.

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.

Installing Aephea
4

./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.

Example source of an Aephea document
5

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

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