diff options
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml')
-rw-r--r-- | en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml | 92 |
1 files changed, 79 insertions, 13 deletions
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 <stdio.h> <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 <stdio.h> <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>, &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> |