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.
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.
Subsection 4.2.3 Other Blocks
There are other blocks which can be achieved using just one element. Examples are
<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.
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:
<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.
<docinfo>section use a
<rename>element. The content should be the new name (“Laboratory” above), while the
@elementattribute should be the name of the element renamed (
@xml:langattribute 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-USis 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:
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.22), and you may decide later to use other properties of the element you have chosen.