ems

aephea-base(7)							  MISCELLANEOUS 						    aephea-base(7)

  NAME
      aephea-base - a description of Aephea base definitions

      The macros in this package have been ported to both html and troff.

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

  INTRODUCTION TO THE ITEMIZE ENVIRONMENT
      The itemize environemnt is the Aephea workhorse for lists, enumerations, itemizations, and other tailed creatures. A simple and valid use is
      for example

	egin{itemize}
	    item{f{foo}}
	    car{
	       For I am foo.
	       }
	    items{
	       {f{barra}}
	       {f{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 set-
      tings 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.

     o	A bullet item.
     o	Now  interitem is set to 0 (affecting the current list), and a new list is started contiguous to the present text (by having its margin-
	top set to 0).
	a.  Hubris
	b.  Laziness
	c.  Impatience
	Are the three virtues of programming.
     o	This concludes a listing showing most of the itemize capabilities.

  USING THE ITEMIZE ENVIRONMENT
      You steer the itemize environment by providing it with tag-value pairs like so:

	 egin{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}

  THE SPACING ENVIRONMENT
      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.

  MACROS
      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  presum-
	ably  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:
	o After an environment that always carries a bottom margin.
	o 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.

      f#1
      it#1
      	t#1
      v#1
      ftinc#2
      ftdec#2
	The first four items set their argument in the font specified.		t#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.

  ISSUES
      Nesting
	Do not nest f#1, it#1, 	t#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.

  aephea-base 1.002, 10-008					      8 Jan 2010						      aephea-base(7)