Sectional Units in GELLMU

1.  Introduction

In classical LaTeX one writes simply

to begin a new section. While this markup specifically delineates the section title, LaTeX understands that a section has begun. The section command has an option whose content is an alternate title for the table of contents, and the starred form of the command suppresses an otherwise automatic section number.

With SGML the classical approach is something along the following lines:

<section><sectiontitle>Some title for a section</sectiontitle>

<para> A paragraph.

<para> Another paragraph.

     . . .

</section>

Basic GELLMU markup corresponding to this would be:¹

\begin{section}\sectiontitle{Some title for a section}

\para A paragraph.

\para Another paragraph.

    . . .

\end{Section}

If, moreover, the markup is to be conforming XML markup, then each para tag would need explicit closure with </para>.

The main point here is that the open and close tags for a section in a classical SGML document type encompass the whole contents of a section, and separate markup is required for the section title.²

The didactic SGML document type under regular GELLMU seeks to model classical LaTeX as closely as possible in order to provide a bridge for authors from LaTeX to SGML (and, indeed, XML). For this reason a command section similar to the classical LaTeX command that delineates a section title is provided in the didactic SGML document type. At the same time this document type has a whole section container Section (upper case S) that in the simplest case consists of a shead container for its title (or header) followed by any number of paragraphs. The XML form of the didactic document type supports only this latter tag, which means that the translation script that converts SGML to XML has an unambiguous way of performing the conversion from section to Section provided that the author's source leads to an SGML instance which is valid³ under the didactic document type.

2.  Labeling and Referencing

The next sections demonstrate various ways of making sections. They also demonstrate how sections interact with labels, references, and the GELLMU table of contents.⁴

The markup for the first section of this document was simply the classical LaTeX-like

There are various combinations of sectional markup that may be used.

The markup for the present section is:

In the didactic GELLMU production system this is equivalent at the point of XML generation to the more LaTeX-like markup

This sentence contains a label, marked up with the usage \label{first}, that is invisible and not part of the section header. While it is the first author-provided label in this document and the first label in the source file, it is not the first label in the XML version of the document since the translator from SGML to XML in the didactic production system writes a label automatically in every shead. At any “inline” location in the document the label may be referenced by using the markup \ref{first}, and with this simple usage its value is 2, i.e., the identifier of the sectional unit in which the label is located.

The didactic production system also provides “visible key” label and reference commands klabel and kref. For example, a kref reference to the last section is [last], which is provided with the markup [\kref{last}]. In a print-only format there might be little difference between writing “\kref{last}” and simply writing the key “last”. But in a hypertext format kref may be used to generate an anchor.

3.  Anchor References and the Handling of Section Titles when the Section Title is Long Enough to Require a Linebreak Under Most Formattings

This section is opened with the LaTeX-like usage:

\section[Anchoring and Long Section Titles]{\label{longtitle}Anchor

References and the Handling of Section Titles when the Section Title

is Long Enough to Require a Linebreak Under Most Formattings}

The purpose of the option string, as with LaTeX is to provide a shorter section title for listing in the table of contents.

Here is an ordinary ref reference back to section 2. This sentence contains an anchor (with anch) back to section 2. If, as is the case here, the anchor uses an iref rather than an href, with the markup

then the anchor might be unnoticeable in a print-only formatting while “active” in an online formatting. This anchor, using the markup

which is for general web references, might produce a footnote in a print-only formatting.

The option of an anchor, which is not an attribute option but rather becomes the element anchref in XML (while the anchor's argument -- its “presented content” -- becomes anchv), is expected to contain whitespace separated strings of the form name="value"⁵ where name is one of the following:

fref

A footnote reference. Value is a string that becomes the content of an automatically created footnote to the text in anchv. This usage is deprecated; use \footnote instead.

href

A web reference as with href in HTML. That is, value is a URI. It could be of the form “#labelkey” where “labelkey” is the name of a label key that could just as well be used with iref. For this the ‘#’ needs to be escaped, i.e., marked up as “\#”. In a non-hypertext formatting the URI may be presented as a note or footnote associated with the text in anchv.

Href

Same as href except that the author wishes to suppress any note or footnote presentation of the URI. For example, the URI might be obviously deducible from the anchv content.

iref

An internal reference; value must be a label key arising from label or klabel.

Note also that there is a command urlanch (probably should have been urianch), taking a single argument, used for URIs, which is intended to have the same effect as a newcommand with one argument for creating a web anchor with the URI as presented content.

Sec. 4.  A Fourth Section

This section is introduced with the markup

(this time an upper case “S”) followed at its terminus by

It makes use of the first two of the three options for Section (and for Subsection, …, section, subsection, …). The options, in order, are sopt, sprefix, and sunit. They are explained in section 8 below.

Sec. 5.  Another Section

For this section the markup style of the previous section is used except that the options are replaced by commands bearing their explicit names. The section opening construction is

\begin{Section}\sopt{Another section}

\sprefix{Sec.\ }\shead{\label{begin2}Another Section}

followed at its terminus by \end{Section}.

6.  Sequencing

Although one could provide SGML modeling for LaTeX’s counters, it would not be very much along the lines of main track XML document types.

Sequencing may be handled under the GELLMU didactic artice document type using labels and references. Toward this end one makes use of three SGML attributes that are provided with the label tag:

series

The value is the name of a sequenced family of labels. A label may belong to at most one family, but there may be multiple labels at the same location. There is no default value of series.

serseq

The value is the sequence number of the label in its series if a series is defined. It is meaningless if no series is specified for the label.

refkey

The name of a label key from which to spawn an automatically generated value for the attribute serseq of the current label.

Every label has a reference value that is normally accessed with the ref command. This results in the creation, when the XML version is generated, of an XML entity reference with name based on the reference's key argument, that matches a CDATA entity definition at the top of the XML document. The use of indirection provided by this entity technique means that it is immaterial whether the reference is forward or backward.

The evalref command gives access to the literal value of a reference without indirection, and places that value as a literal in the XML version of an article. Thus, evalref is the name of a tag only in the SGML version. An evalref invocation will be succesful only with a backward reference. This is extremely useful for managing non-default numbering of sectional units. For ordinary label references its use is undesirable even though it is possible for backward references.

The reference value of a label is determined as follows:

1. Basic reference values are positive integers. Upper and lower case alphabetic values and upper and lower case roman numeral values may be obtained by applying the series command (not to be confused with the series attribute for the label command) with the type attribute set to one of ‘A’, ‘a’, ‘I’, or ‘i’ to a basic reference value.

2. If the label is assigned to a label series and is given a refkey attribute, then the reference value of the label is the reference value of the label referenced by the key that is the value of the refkey. (This mechanism is used to re-start the sequencing of the sectional unit id's at the end of this document.)

3. Else if the label is assigned to a label series and the author supplies an explicit literal numeric value for the serseq attribute, then the value of serseq is its referenced value. (Markup -- in particular, evalref -- cannot be used in defining an attribute value.)

4. Else if the label is assigned to a label series, the reference value of the label is the next (positive integer) value for a label in that series. (This mechanism is used to control the sectional id of the last section of this document. It may also be used to run parallel interleaved sequences of sectional units, such as, for example, questions and answers, within a document.)

5. Else the reference value of the label is the sectional unit id of the smallest sectional unit containing the label.

Here is where a label, which is invisible, is planted with the markup “\label{conmark}” so as to record the sectional unit id for the current section. It evaluates to the sectional unit value, in this case 6. If that label were placed in a series, it would pick up as value the next value in the sequence associated with the series. So a second label is planted with the markup

to prime a new label series with the value (6) of the current sectional unit id for later use in continuing the current sequence of sectional unit id's.

Division A.  Special Sectional Units

This sectional unit, which is parallel to top-level sections, is specially sequenced by “hand”. The markup for opening this unit is:

In regular GELLMU a LaTeX-like first option in which the first character is ‘:’ is a sequence of SGML attribute specifications. It is important to realize that attributes cannot contain markup. In regular GELLMU, where one is allowing characters such as ‘-’, ‘/’, ‘#’, and ‘=’ to serve as markup (because of their classical overloading⁷), only alpha-numeric characters are safe in attribute values when entered this way. For the most common situations, such as, for example, what might be the href attribute of anch⁸, a LaTeX-like option can be provided. LaTeX-like options handle what might be regarded as plain inline markup.

One could also use for this a very similar syntax with Section, i.e., “\begin{Section} ... \end{Section}”.

Make note of the secret phrase: valid markup.

7.  A Non-Special Section

To avoid having to feed section numbers manually in the following or else spawning them from a label series, the opening of this section manually sets the section unit id.

8.  General Usage for Sectional Units

This describes the content model in the didatic GELLMU document type for the “whole” sectional units Section, Subsection, … as fully tagged.