From 112fe8d1081d4f9dcbd11599c09b0c0b37299539 Mon Sep 17 00:00:00 2001
From: Nik Clayton <nik@FreeBSD.org>
Date: Sun, 16 Jul 2000 16:40:09 +0000
Subject: Remove the text saying "I don't know how to do callouts", because now
 I do.  Replace it with some examples showing how to do callouts.

Replace "&amp;man.sendmail.8;" with "&man.sendmail.8;".
---
 .../books/fdp-primer/sgml-markup/chapter.sgml      | 92 +++++++++++++++++++---
 1 file changed, 79 insertions(+), 13 deletions(-)

(limited to 'en_US.ISO_8859-1/books')

diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 332bd5ab8b..9c58f2fd68 100644
--- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -27,7 +27,7 @@
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
-     $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.12 2000/07/07 18:38:37 dannyboy Exp $
+     $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.13 2000/07/15 07:47:55 alex Exp $
 -->
 
 <chapter id="sgml-markup">
@@ -1275,17 +1275,83 @@ main(void)
     printf("hello, world\n");
 }</programlisting>	    
 	</example>
-	  
-	<note>
-	  <para>There is a mechanism within DocBook for referring to sections
-	    of a previously occuring <sgmltag>programlisting</sgmltag>, called
-	    callouts (see <sgmltag>programlistingco</sgmltag> for more
-	    information).  I don't fully understand (i.e., have never used)
-	    this feature, so can't document it here.  For the mean time, you
-	    can include line numbers within the content, and then refer to
-	    them later on in your description.  That will change, as soon as I
-	    find the time to understand and document callouts.</para>
-	</note>
+      </sect3>
+
+      <sect3>
+	<title>Callouts</title>
+
+	<para>A callout is a mechanism for referring back to an earlier piece
+	  of text or specific position within an earlier example without
+	  linking to it within the text.</para>
+
+	<para>To do this, mark areas of interest in your example
+	  (<sgmltag>programlisting</sgmltag>,
+	  <sgmltag>literallayout</sgmltag>, or whatever) with the
+	  <sgmltag>co</sgmltag> element.  Each element must have a unique
+	  <literal>id</literal> assigned to it.  After the example include a
+	  <sgmltag>calloutlist</sgmltag> that refers back to the example and
+	  provides additional commentary.</para>
+	
+	<example>
+	  <title><sgmltag>co</sgmltag> and
+	    <sgmltag>calloutlist</sgmltag></title>
+
+	  <programlisting><![ CDATA[<para>When you have finished, your program should look like
+  this;</para>
+
+<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">
+
+int <co id="co-ex-return">
+main(void)
+{
+    printf("hello, world\n"); <co id="co-ex-printf">
+}</programlisting>
+
+<calloutlist>
+  <callout arearefs="co-ex-include">
+    <para>Includes the standard IO header file.</para>
+  </callout>
+
+  <callout arearefs="co-ex-return">
+    <para>Specifies that <function>main()</function> returns an
+      int.</para>
+  </callout>
+
+  <callout arearefs="co-ex-printf">
+    <para>The <function>printf()</function> call that writes
+      <literal>hello, world</literal> to standard output.</para>
+  </callout>
+</calloutlist>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>When you have finished, your program should look like
+	    this;</para>
+
+	  <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">
+
+int <co id="co-ex-return">
+main(void)
+{
+    printf("hello, world\n"); <co id="co-ex-printf">
+}</programlisting>
+
+	  <calloutlist>
+	    <callout arearefs="co-ex-include">
+	      <para>Includes the standard IO header file.</para>
+	    </callout>
+	    
+	    <callout arearefs="co-ex-return">
+	      <para>Specifies that <function>main()</function> returns an
+		int.</para>
+	    </callout>
+	    
+	    <callout arearefs="co-ex-printf">
+	      <para>The <function>printf()</function> call that writes
+		<literal>hello, world</literal> to standard output.</para>
+	    </callout>
+	  </calloutlist>	  
+	</example>
       </sect3>
       
       <sect3>
@@ -1610,7 +1676,7 @@ This is the file called 'foo2'</screen>
   <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
-  </citerefentry>, &amp;man.sendmail.8;, and &man.newaliases.8;
+  </citerefentry>, &man.sendmail.8;, and &man.newaliases.8;
   programs.</para>
 
 <para>One of the command line parameters to <citerefentry>
-- 
cgit v1.2.3