Indentation

rendition indentation
indent first-indent right-indent

Overview of the encoding of indentation, including absolute and relative indentation, first-line indentation, and negative indentation

Indentation is the displacement of a textual feature inward from the margin (usually the left margin but sometimes from the right). It may apply to an entire text chunk (such as a line of poetry or a block quotation) or to the first line of a text chunk (such as the first line of a paragraph) or to all but the first line (as in a hanging indent on an epigraph). It may be absolute (measured from some given margin) or relative (measured relative to the indentation of some enclosing textual feature). It is usually significant, in the sense that it reflects the printer’s sense of the text’s structural boundaries and is a tool for communicating them; however, it is rarely meaningful in a specific way that would require a careful measurement. In encoding indentation it is usually sufficient to indicate that it is present, without indicating exactly how much. One important exception is the indentation of poetry, which in some genres (such as certain forms of ode) may reflect the metrical and rhythmic scheme of the poem.

Indentation should be represented using the rend attribute on the element affected, never with spaces or tabs typed into the text. It should be encoded at the highest relevant level of granularity: on the whole poem rather than its individual lines. In the rendition ladder method of encoding rendition that we recommend, there are three distinct keywords for indentation: indent, first-indent, and right-indent. The indent and first-indent keywords are understood to mean indentation from the left margin. First-line indentation from the right margin is so rare that we do not include a keyword for it, but one could easily be created if necessary.

For all three keywords having to do with indentation, the parenthetical value may be expressed in any units you find convenient. We have found the most useful to be something akin to a tab stop: a single unit roughly corresponding to a typical paragraph indentation, measured relative to the general margin for the document as a whole. The concept of a tab stop is an anachronism in this context, but it expresses a unit of indentation which is fairly constant and which is explicitly relative, not absolute (that is, it is not a fixed measurable quantity but a unit which operates within a given text). Thus for lines of poetry, for instance, the first increment of indentation should be encoded as indent(1), the next additional increment of indentation should be encoded as indent(2), etc., regardless of the exact size of each indent (which might vary with tightly or loosely spaced lines). We do not recommend measuring indentation or distinguishing between minutely different levels of indentation.

Values for the indentation keywords

For most purposes, a simple number will suffice. However, in a text with complex encoding it may be useful to have more detailed options available and we spell these out here for the sake of clarity and completeness. For most projects, these details will be unnecessary:

For all three indentation keywords, an absolute number (that is, a number without a + or - sign) as a value indicates that the element is indented by that much from the margin.

A relative number (one modified by a + or -) indicates that the element is indented by that much from the meaningful parent element (except with first-line indentation; see below). Meaningful parent element here means the most immediate block-level parent element, i.e. an element which can meaningfully govern indentation. Note that relative indentation indicates indentation from the parent, not the previous sibling. Thus for a line of poetry within a stanza, relative indentation indicates indentation relative to the stanza, not the previous line.

A value of zero for indent is always absolute; that is, it indicates that the element is flush at the left margin. A value of plus (or minus :-) zero for indent is always relative; that is, it indicates that the element is indented the same as its (meaningful)parent.

A positive indentation should be assumed unless a negative number is specified, so the + sign is not strictly necessary. Positive indentation is indentation which shrinks the text block; negative indentation is indentation which expands the text block.

Specific keywords

The indent keyword indicates that the entire element designated is shifted to the right by the specified amount. A negative value indicates a shift to the left (i.e. out into the margin).

The first-indent keyword indicates that the first line of the element is shifted by the expressed amount relative to the other lines in the element. A positive value indicates a shift to the right (i.e. indentation), and a negative value indicates a shift to the left (i.e. an overhanging line). An absolute value for first-indent indicates indentation relative to the left margin; a relative value (has + or -) indicates indentation relative to the rest of the element itself. Since it indicates relative indentation, the first-indent keyword should not be used for elements which only include a single line, since it is meaningless in this context.

The right-indent keyword indicates that the entire element is shifted to the left (away from the right margin) by the specified amount. Strictly speaking this is equivalent to a negative value of indent; it should be used only for elements that are right-justified.

Examples

Example 1.

A typical hanging indent:

<p rend="indent(1)first-indent(-1)">

Example 2.

An indented closer to a letter:

[end of last para in a letter] ... to imagine any Person more to any one than I am,
  MADAM,
  Your Ladiships most faithful Servant,
      and passionate Friend,
          Orinda.


<p>...to imagine any Person more to any one than I am,</p>
<closer rend="indent(1)">
<salute>Madam,
<lb/>Your Ladiships most faithful Servant,
<lb rend="indent(+1)"/>and passionate Friend,</salute>
<signed rend="indent(+3)><persName>Orinda</persName></signed>
</closer>
     

Relative indentation has been used here: the closer as a whole is indented by one, and relative to the closer the salute is indented one further increment. The second line of the salute is further indented by one, and the signature is indented relative to the closer by three.