\startcomponent work-en-heads

\product work-en

\chapter[heads]{Heads}

\index{heads}
\index{heads}

\Command{\tex{chapter}}
\Command{\tex{paragraph}}
\Command{\tex{subparagraph}}
\Command{\tex{title}}
\Command{\tex{subject}}
\Command{\tex{subsubject}}
\Command{\tex{setuphead}}
\Command{\tex{setupheads}}

The structure of a document is determined by its division into
sections that each start with a heading.  Heads (heads) are created
with the commands shown in
\in{table}[tab:heads]:

\placetable[here][tab:heads]{Heads.}
\starttable[|l|l|]
\HL
\NC \bf Numbered header   \NC \bf Un-numbered header   \NC\SR
\HL
\NC \type{\chapter}       \NC \type{\title}           \NC\FR
\NC \type{\section}       \NC \type{\subject}         \NC\MR
\NC \type{\subsection}    \NC \type{\subsubject}      \NC\MR
\NC \type{\subsubsection} \NC \type{\subsubsubject}   \NC\MR
\NC $\cdots$              \NC $\cdots$                \NC\LR
\HL
\stoptable

These commands will produce a heading in a
predefined fontsize and fonttype with some vertical
spacing before and after the heading.

The heading commands can take one or two arguments, like in:

\starttyping
\title[hasselt-by-night]{Hasselt by night}
\stoptyping

and

\starttyping
\title{Hasselt by night}
\stoptyping

We will use a special format to document such command descriptions:

\shortsetup{title}

The command \type{\title} has two arguments, of which the first is
optional (illustrated by the word {\sc optional}). Arguments to
commands come in a small number of distinct types.  As we saw earlier,
in this case the first argument is an optional label that marks a
particular spot in the generated document to be used for internal
references. Therefore, the type of the first argument is {\sc reference}.
The comma in the short description means that you can even give a list
of labels.

If you want to refer to this header you type for example
\type{\at{page}[hasselt-by-night]}.

The second argument has type {\sc content}, which simply says
that it is text to be typeset.

The other heading commands have an identical syntax:

\shortsetup{chapter}
\shortsetup{section}
\shortsetup{subsection}
\shortsetup{subject}
\shortsetup{subsubject}

\CONTEXT\ defines more levels of commands than listed above. 
Simply add another \type{sub} to the front of the section or subject
to create a heading that is one level \quote{deeper}. The predefined
heading commands go up to \type{\subsubsubsubsection}.

Of course these heads can be set to your own preferences
and you can even define your own heads. This is done using
the commands \type{\setuphead} and \type{\definehead}.

\startbuffer
\definehead
  [myheader]
  [section]

\setuphead
  [myheader]
  [numberstyle=bold,
   textstyle=bold,
   before=\hairline\blank,
   after=\nowhitespace\hairline]

\myheader[myhead]{Hasselt makes headlines}
\stopbuffer

\typebuffer

A new header \type{\myheader} is defined and first it inherits the
properties of \type{\section}, then some of the settings are
overruled.  Notice that the two arguments to \type{\definehead} and
the first argument to \type{\setuphead} do not start with a backslash.
This is the normal case for all commands that start with
\type{\define...} or \type{\setup...} as it makes handling the
arguments easier internally (we will meet many more commands like this
as we go along).

Meanwhile, the newly defined header would look something like this:

\getbuffer

and here are the short representations of the two used commands:

\shortsetup{definehead}
\shortsetup{setuphead}

While \type{\definehead} is a quite simple command and should not need
further explanation, \type{\setuphead} has a long list of arguments. 

The first argument is of type {\sc section}, meaning that this
command only accepts already defined header names as values for
the first argument. 

The second argument is itself a list of keys and values separated by
comma's.  The words on the left are the keys that can be used, the
possible values are on the right. Words written all in lower case are
predefined keywords, and alternate values are separated by spaces.

A {\sc command} value can be almost any sequence of \CONTEXT\ commands,
as can be seen in the definition \type{\myheader} above.

An {\sc identifier} is based on the same principle as {\sc section} we
saw earlier, but it is context driven: for the \type{color} key, there
a valid (predefined) color name should be given. For the \type{file}
key, it should be a file name, et cetera.

A {\sc number} represents a number, a {\sc list} a list of
comma-separated values, a {\sc file} is an existing file name.

A {\sc text} is a free-form string that is normally used in the
description only when nothing else fits.

Finally, \type{\...#1} is a special case of {\sc command}: the value
should be a single command that takes a single braced argument
(\type{#1#2} means two braced arguments, et cetera).

{\bf TODO: now document the actual keys}

There is one other command you should know now, and that is
\type{\setupheads} (you noticed the {\em inherits from
\type{\setupheads}} at the end of the short display of
\type{\setuphead}). You can use this command to set up the numbering
of the numbered heads. If you type:

\startbuffer
\setupheads
  [alternative=inmargin,
   separator=--]
\stopbuffer

\typebuffer

all numbers will appear in the margin. Section 1.1 would
look like 1--1.

Commands like \type{\setupheads} are typed in the
set up area of your input file.

\shortsetup{setupheads}

\stopcomponent
