aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>2000-07-16 16:40:09 +0000
committerNik Clayton <nik@FreeBSD.org>2000-07-16 16:40:09 +0000
commit112fe8d1081d4f9dcbd11599c09b0c0b37299539 (patch)
treeb800db49d4106649b090112ed9ef85ef798258c0
parent9cb54004db698cff408b8ff81c2a20706156d6f0 (diff)
downloaddoc-112fe8d1081d4f9dcbd11599c09b0c0b37299539.tar.gz
doc-112fe8d1081d4f9dcbd11599c09b0c0b37299539.zip
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;".
Notes
Notes: svn path=/head/; revision=7632
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml92
-rw-r--r--en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml92
2 files changed, 158 insertions, 26 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 332bd5ab8b..9c58f2fd68 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO8859-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>
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>