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