6.4.  Callout Annotation for Program or Markup Listing

A How-To Recipe

Jeff Elpern

Task
Solution
Discussion
Reference Material

Task

Stuff goes here

Solution

Stuff goes here.

Placement in Code Technique

Example 1. Markup for Embedded Callouts

 
<programlisting>
  <co id="co_rootPage" linkends="rootPage"/> HowToBook -|---- DocumentSettings
                |
                |---- ChapSystem -|
                |                 
                |---- ChapText -| 
                +               |---- highlight
                +
                +
</programlisting>
<calloutlist>
  <callout id="rootPage" arearefs="co_rootPage">
    <para>this is the root, or master, page. It is a DocBook markup with a 
    document <code>&lt;book&gt;</code> or <code>&lt;article&gt;</code> 
    tag.</para>
  </callout>
</calloutlist>

Figure 1. Published output of Example 1, “Markup for Embedded Callouts”

Published output of

  1 HowToBook -|---- DocumentSettings
                |
                |---- ChapSystem -|
                |                 
                |---- ChapText -| 
                +               |---- highlight
                +
                +

1

this is the root, or master, page. It is a DocBook markup with a document <book> or <article> tag.

[Note]Note

Callouts are Links. The advantage of the <co> tag embedded in the code or markup listing is the creation of a hyperlink between the callout bug in the text and the full description provided. The alternative, Placement Map to Code Technique, does not create hyperlinks.

An issues with the embedded <co> tag is the clutter created, in the xml, with within the actual listing. If the callouts are at the end if the line this have almost no effect. If the callouts are within the listing then the uses of the section called “Placement Map to Code Technique” is advised

Placement Map to Code Technique

Description here ????

Example 2. Markup for Placement Map

<programlistingco>
  <areaspec>
    <area id="co_rootPage2" linkends="rootPage2" coords="2 3"/>
  </areaspec>
  <programlisting>
   HowToBook -|---- DocumentSettings
                |
                |---- ChapSystem -|
                |                 
                |---- ChapText -| 
                +               |---- highlight
                +
                +
  </programlisting>
  <calloutlist>
    <callout id="rootPage2" arearefs="co_rootPage2">
      <para>this is the root, or master, page. It is a DocBook markup with a 
      document <code>&lt;book&gt;</code> or <code>&lt;article&gt;</code> 
      tag.</para>
    </callout>
  </calloutlist>
</programlistingco>

Figure 2. Published output of Example 2, “Markup for Placement Map”

Published output of

   HowToBook -|---- DocumentSettings
                |
                |---- ChapSystem -|
                |                 
                |---- ChapText -| 
                +               |---- highlight
                +
                +

1

this is the root, or master, page. It is a DocBook markup with a document <book> or <article> tag.

Discussion

Stuff goes here

Reference Material

Stuff goes here

Univ/CIE/KA/StrucDoc/HowToBookProto/ChapCode/annotateCallout (last edited 2008-10-20 01:09:59 by jeff)