7.3.��Headings in Chapter "Front" Content

A How-To Recipe

Jeff Elpern


Task

The chapter introduction content is long enough to need headings. However, you can not use a <section> tag because that would trigger a full section layout.

Figure��1.��Example of First <section> Formating

Example of First <section> Formating

Figure��1, ���Example of First <section> Formating��� shows the page layout triggered by the first section tag - in this case the How-To title format for the 3.1 Links Within a Page. It also shows the page layout and introduction material for Chapter 3. Links with heading for the chapter "front" content.

Solution

The <brigdehead> tag with renderas attribute provide the capability to create a free-floating heading that does not trigger the full page layout processing of a normal section. It does invoke the position and style of the associated section title.

Figure��2.��DocBook Markup for "Free-Floating" Headings

<chapter>
    <title> Title Goes Here </title>
    <bridgehead renderas="sect2"> 
        "Free-floating" heading goes here
    </bridgehead>
    <para> Introduction to chapter stuff here.  <para>
        <bridgehead renderas="sect3"> 
           "Free-floating"  sub-heading goes here
        </bridgehead>
        <para> Stuff goes here. <para>
</chapter>

1

<bridgehead> is the DocBook tag used to create a heading font look without creating a <section> type processing in the flow control. The renderas attribute determines which heading format is used.

[Note]Note

The <bridgehead> is just a "title" type tag. It does not contain any associated content like the <section> tag.

2

The renderas value of sect3 of this <bridgehead> tag generates a sub-heading format.


Markup Fragment

Listed below is a "clean" (without callout numbers) DocBook markup fragment for creating headings in Chapter "front" material.

Figure��3.��Markup Fragment for Creating Heading without <section> tag

<chapter>
    <title> Title Goes Here </title>
    <bridgehead renderas="sect2">
        "Free-floating" heading goes here
    </bridgehead>
    <para> Introduction to chapter stuff here.  <para>
        <bridgehead renderas="sect3">
           "Free-floating"  sub-heading goes here
        </bridgehead>
        <para> Stuff goes here. <para>
</chapter> 

Discussion

The SQI microPublishing environment uses <secton> tag, and nested tags, <secton>. This make content portable. In the case of the <bridgehead> tag the renderas attribute has to be a sect# value. Thus the system needs to map the requested renderas level into the associated section level.

So the heading format of a renderas="sect1" is formated like the title of a top level <section>. And, the heading format of a renderas="sect2" is formated like the title of a <section><section>. The heading format of a renderas="sect3" is formated like the title of a <section><section><section>. Etc.

In Figure��2, ���DocBook Markup for "Free-Floating" Headings��� the first "free-floating" heading is specified to be sect2. This is because the "How-To" page layout scheme use the top level <section> tag with a chapter to trigger the How-To title look (see the right hand image in Figure��1, ���Example of First <section> Formating���) The text headings really start with the second level section and thus match the sect2 attribute.

Reference Material

  • <bridgehead> element reference in DocBook: The Definitive Guide

Univ/CIE/KA/StrucDoc/HowToBookProto/ChapChapters/bridgeHeads (last edited 2015-03-06 18:11:26 by localhost)