aephea-base - a description of Aephea base definitions
The macros in this package have been ported to both html and troff.
aephea-base - A description of Aephea base definitions. The macros in
this package have been ported to both html and troff. This package is used by
the Aephea simpledocument class and by the Portable Unix Documentation (pud)
mini-languages for authoring manual pages (
pud-man) and the pud
language for faq authoring (
pud-faq).
There is a small list of known issues in the
ISSUES section, mostly
concerning the troff device. These should generally be of no concern at all,
but if you run into trouble look there first. A quick glance through the list
before you run into trouble may be the wisest thing to do.
The
itemize environemnt is the Aephea workhorse for lists, enumerations,
itemizations, and other tailed creatures. A simple and valid use is for
example
\begin{itemize}
\item{\bf{foo}}
\car{
For I am foo.
}
\items{
{\bf{barra}}
{\bf{zuttelezut}}
}
\car{
For we are bar and zut.
}
\end{itemize}
This source result in the following output:
foo
For I am foo.
barra
zuttelezut
For we are bar and zut.
This is not impressive at all, but it gives an idea of how itemize works. The
following example is a single itemize environment providing a
rollercoasterride through most of the features of the itemize environment. As
shown below, it is possible to change all the itemize settings and styles at
will even within a single itemize instance. Of course this is not useful at
all except for demonstrating the
itemize capabilities, but it goes to
show that the itemize macros are quite robust (by virtue of modularity).
NOTE
The entire listing below was put in Aephea's
spacing environment,
described further below. The environment was used to create extra margins on
the two sides.
1 Spacing modes
compact and
cascade are determined by the key
flow. The current mode is
compact, meaning that the itemize
token and the ensuing text are on the same line. Below, compact mode is
switched off (approximately) halfway. The
interitem key determines the
amount skipped between an item description and the next item.
2 Several item modes (custom, mark, enumeration).
3 Several enumeration modes (roman, arabic, alphabetic).
iv) The style of a list can be changed while in the middle of it.
v) Nuther item.
vi) The list can be 'interupted' and resumed (by means of the \intermezzo#1
macro).
Perhaps you wonder what good is THAT for, and justly so. The \intermezzo#1 macro
should only be used inbetween different items, i.e. it should
not split
content belonging to a single item.
[7] Items can be optionally and automatically right and/or left delimited. The
current item is delimited with square brackets.
[8] Items can be left or right aligned.
[9] Items can be stacked, which is supported only when
flow is set to
cascade.
[10]
Beginning with this item,
flow is set to
cascade.
Implying
That
Stacking
is now possible.
[12]
(back to right-align) The itemcounter just keeps running by the way.
[18] (back to compact) But the counter can be manipulated at will.
• A bullet item.
• Now
interitem is set to 0 (affecting the current list), and a new
list is started contiguous to the present text (by having its margintop set to
0).
a. Hubris
b. Laziness
c. Impatience
Are the three virtues of programming.
• This concludes a listing showing most of the itemize capabilities.
You steer the itemize environment by providing it with tag-value pairs like so:
\begin{itemize}{
{flow}{compact}
{interitem}{1}
{align}{right}
{type}{abc}
{rp}{.}
}
This is the list of tags that you may use.
margintop
Top of table, anomalous unit (ems), default 0.
interitem
Paragraph skip in
ems inbetween items, default 0.
flow
Set to compact or cascade
textindent
Width of text indent in ems.
itemmargin
Width of item margin in ems (for right-aligned items).
mark
E.g. \*{itembullet} (if type=mark), affects \item.
align
One of left or right (item alignment), default left.
class_all
class name assigned to all block-level elements
lp
What's printed immediately to the left of an item.
rp
What's printed immediately to the right of an item.
type
One of mark, roman, abc, arabic, affects \item.
itemcount
The count of items seen so far, e.g. 13 right now.
You need to know that the itemize environment internally maps these tags to
dollar keys simply by prepending a dollar. Thus, if you want to reset one of
the values associated with such a tag, you need to do e.g.
\set{$align}{right}
\set{$itemcount}{30}
A more robust to do this is to ensure that the modified key is retrieved from
the right dictionary, i.e. the top-level
itemize dictionary, as
follows.
\set{{dict}{itemize}}{$align}{right}
\set{{dict}{itemize}}{$itemcount}{30}
Its syntax is identical to that of the
itemize environment. It accepts
tags
left,
right,
top, and
bottom. These should
receive numeric values. The associated unit is
em.
The troff device does not yet support the
top and
bottom tags.
\
enref#2
\
iref#2
\
lref#2
\
aref#2
\
httpref#1
\
sibref#1
\
sibref#2
\
sibref#3
\enref#2
creates a link for which the first argument is the anchor and
for which the second argument is the content (which can be left empty).
\iref#2 takes such an anchor as the first argument and it takes content that
carries the link as the second argument. \lref#2 takes a file name (possibly
including a relative or absolute path) as the first argument and content as
the second argument. \aref#2 takes a URL (later possibly a URI) as the first
argument and content as the second argument. \sibref#2 takes a label as
argument which presumably is the name of some application. It may append an
extension depending on the current device, and it assumes that label +
extension is the name of a file in the current directory. The second argument
is displayed in the text. For \sibref#1 the displayed text is the same as the
label. For \sibref#3 the second argument is an additional anchor within the
file being linked to, and the third argument is the displayed text. \httpref#1
simply prints a URL which will be active when html is output.
\
par#1
\
cpar#2
\
car#1
\
ccar#2
These are all paragraph macros that carry the paragraph content as the last
argument. The first argument of \cpar#2 and \ccar#2 is the caption. These
macros will ensure well-formedness for devices that support it, such as html.
Use \car#1 where you don't need a paragraph skip, but just need to indicate
that you are in text mode again. You can simply always use \par#1 and never
use \car#1. If you care about the details of spacing though, or if you have
particular trouble for example in creating an itemize environment where you do
not want top and bottom margins, then it could be worthwile to turn to \car#1.
Examples for using \car#1 are:
• After an environment that always carries a bottom margin.
• After an environment that does
not carry a bottom margin, and
where you specifically want the environment to be contiguous to the enclosing
text. The listing you are currently reading is an example of this.
As promised. The \car macro may feel a little unusual. If you don't mind
standing the chance of a little spurious vertical white-space just use \par
all the time. If you really need it, such as in an 'inline' listing as above,
the \car macro is ready to do the job.
\
bf#1
\
it#1
\
tt#1
\
v#1
\
ftinc#2
\
ftdec#2
The first four items set their argument in the
font specified.
\tt#1 and \v#1 both denote a typewriter font.
These macros should
not be nested if troff is to be among the output devices. Support for
the last two items is not yet very robust. They temporarily increment
respectively decrement the font by the amount of the first argument and apply
the resulting setting to the second argument.
\
verbatim#1
\
verbatix#1
Make the device output the contents verbatim in a mono-spaced font, obeying
spaces and newlines. This does not prohibit expansion of macros, use
\protect#1 for that. The macro \verbatim#1 will create a non-breaking
environment.
Nesting
Do not nest \bf#1, \it#1, \tt#1, or \v#1 macros if troff is among the output
devices. It will yield unexpected results.
The rest of this list pertains to the
itemize environment.
Margins
Do not use fractional values for textindent and itemmargin in the itemize
environment, if troff is among the output devices. The reason is that the
Aephea macros use the difference between these two values and pass them on to
the output devices. Troff rounds all values it gets and thus the additive
relationship between the values may be lost.