Blocks

Section 4.2 Blocks

Subsection 4.2.1 Introduction to Blocks

A division (Section 3.1), that is not further subdivided, is primarly, but not exclusively, composed of paragraphs and blocks. We document the types of blocks here, even though we do not intend to ever provide a rigorous definition of the term. Here is a list of characteristics, which is not prescriptive.

List 4.2.1. Characteristics of a Block

Visually set-off from a run of “plain” paragraphs. Often earning a number, and ideally provided a title or caption (Best Practice 4.8.1).
Reflowable lines of text, such as an <example>, or a more rigid, more spatial, more planar object, such as a <figure> or <table>.
Usually a child of a division (Section 4.6). But see just below.
Typically a block does not contain another block, except that the more planar ones can appear as part of a more textual one.
When numbered, all blocks generally run consecutively. (In LaTeX-speak, “on the same counter.”) Numbering FIGURE-LIKE and PROJECT-LIKE independently is in transition at this writing (2021-07-07).
Depending on the output format of your document, some block types may be initially hidden to improve the visual flow. The reader must click on the heading for the block to reveal its contents. You can change this behavior by configuring your publication file. See Section 44.4. We will make note of the elements that are hidden by default for HTML output.

The following is somewhat general, and we have not extensively cross-referenced to the particular types of blocks, so use the Table of Contents or the Index to learn more specifics.

Subsection 4.2.2 Isomorphic Blocks

The structure of a block is described carefully in the schema (Chapter 6). There are approximately forty blocks that are arranged into ten groups, within which they behave identically, except for their displayed names. An exception is the group of four “figure-like” items which are very similar, but have differences beyond just their displayed names. These groupings are defined in the xsl/entities.ent file, which we summarize in the next table. The category name is taken from the entities file, and the notes are meant to describe the distinctive capabilities of the category.

List 4.2.2. Summary of Blocks

REMARK-LIKE: <remark>, <convention>, <note>, <observation>, <warning>, <insight>

The most basic, generic, block.
EXAMPLE-LIKE: <example>, <question>, <problem>

A worked problem meant as exposition. It can be structured with <task>, <hint>, <answer>, and <solution> just like an <exercise> or PROJECT-LIKE, but the <hint>, <answer>, and <solution> cannot be electively removed from output, and they do not migrate to collections of solutions elsewhere. Hidden by default for HTML output formats.
PROJECT-LIKE: <project>, <activity>, <exploration>, <investigation>

These are similar to an <exercise>, but the name suggests a slightly different undertaking, and they cannot be placed in an <exercises> division. The current default is that they are numbered independently from other blocks, but this is planned to switch to elective behavior. The <hint>, <answer>, and <solution> behave more like those for an <exercise> and can be removed from output, and can migrate to collections of solutions.
FIGURE-LIKE: <figure>, <table>, <listing>, <list>

An object that is a container for other atomic objects, which are typically somewhat rigid (not reflowable) or two-dimensional. Typically with a number, and provided with a title or caption. But each is slightly different in what it can contain and how it is rendered. A <table> can only hold a <tabular>, while a <listing> is meant for <program> and <console>. A <list> is not the list itself, but a container for one of the three possible lists (see Section 4.11 and especially Section 4.20). A <figure> is the most liberal, allowing a wide variety of contents, with <image> being the prototypical example. These are not designed with the expectation that they can be renamed.
THEOREM-LIKE: <theorem>, <corollary>, <lemma>, <algorithm>, <proposition>, <claim>, <fact>, <identity>

Mathematical results, which can have an (optional) <proof>. Proofs are hidden by default in HTML output.
AXIOM-LIKE: <axiom>, <conjecture>, <principle>, <heuristic>, <hypothesis>, <assumption>

A mathematical statement, which does not have a proof.
DEFINITION-LIKE: <definition>

A definition of a (mathematical) object.
ASIDE-LIKE: <aside>, <biographical>, <historical>

Parenthetical content that is structured beyond what a footnote can contain.
COMPUTATION-LIKE: <computation>, <technology>, <data>

For descriptions of activities or data for use with computers, calculators, or other devices.
GOAL-LIKE: <objectives>, <outcomes>

These are structured primarily as lists, and may only appear early (<objectives>) or late (<outcomes>) within a division.

Subsection 4.2.3 Other Blocks

There are other blocks which can be achieved using just one element. Examples are <poem> and <assemblage>. An <exercise> can take on different behaviors, depending on its placement (see Section 4.3). One such placement is as a child of a division, which we call an inline exercise, and this would be regarded as a block, very similar to a PROJECT-LIKE. Inline exercises are hidden by default in HTML output.

A paragraph (<p>) can appear many places and is a primary component of blocks. But when it is a child of a division, it shares some charateristics with other blocks. There are a number of peers of a <p> which would then also qualify: <pre>, <blockquote>, <image>, <video>, <program>, <console>, and <tabular>. None of these can have a title or number, making them less useful, but widening the possibilities for placement.

Subsection 4.2.4 Renaming Blocks

A common desire of authors new to PreTeXt is a new block. Authors extending PreTeXt to add a new one is not supported, and it is not even straightforward for a PreTeXt developer to provide comprehensive support for a new block. One of the reasons for multiple versions of blocks, with common behaviors, is that you can appropriate one for use with your project and give it a new name. So for example, a biology textbook might want to use <activity> for a laboratory, but rename it to “Laboratory”. Of course, this means you will forego having any “Activity” in your book. (But if you are the first to write a biology textbook in PreTeXt perhaps you should talk to us about a real <laboratory> element that behaves well for all the physical and biological sciences!) Here is the procedure:

Choose a block from List 4.2.2 that has behavior similar to your intended use, and which you do not forsee using as-is in your project.
In the <docinfo> section use a <rename> element. The content should be the new name (“Laboratory” above), while the @element attribute should be the name of the element renamed (activity above).
The @xml:lang attribute should be used to specify a value of the code for use with documents authored in languages other than US English. If absent, the default vslue en-US is used. Multiple <rename> elements for the same element, in different languages, is supported.

So, continuing and extending our example, an author would use

<rename @element="activity" xml:lang="fr-FR">Laboratoire</rename>

The most popular block to rename is <exercise>. We have exercises inside <exercises> divisions, which we call divisional exercises, and exercises inside divisions, which we call inline exercises. It is possible to have one of each that have identical numbers. So in cross-references the former is an “Exercise”, while the latter is a “Checkpoint”. If you only have inline exercises, you might prefer that they be called Exercise rather than Checkpoint. For the @element attribute of the <rename> element, use a pseudo-element, in this case inlineexercise. Other pseudo-elements which can be used to distinguish the various types of exercises are: divisionexercise, worksheetexercise, and readingquestion.

Choose the element you rename carefully, trying to match it to the purpose of your content. It can be useful for other purposes, such as automatic lists (Section 4.28), and you may decide later to use other properties of the element you have chosen.

Prev Top Next