Examples and screen snapshots

Examples involving plain text

Command line examples are rather straightforward, since they present a linear progression. The main elements to keep in mind are example, programlisting, screen, literal, prompt and userinput. Program listings will be discussed in the section called Code samples.

As an example, here's how I wrote the beginning of the anonymous ftp session in the section called UNIX in the appendix called Obtaining and installing DocBook tools:

<!doctype screen PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
]>
<screen>
  <prompt>$</prompt> <userinput>ncftp ftp://ftp.cygnus.com/pub/home/rosalia/</userinput>
  <prompt>ncftp></prompt> <userinput>cd docware/RPMS/i386/</userinput>
  <prompt>ncftp></prompt> <userinput>mget *.rpm</userinput>
  <prompt>ncftp></prompt> <userinput>quit</userinput>
</screen>
	  

If you process and view this snippet, you will see that the HTML code has a nice gray shading for screenshots. For now the TeX/postscript output does not have a similar cartouche, but it does use a typewriter font.

Describing GUIs

I have never described a GUI using screen shots or anything like that, so I will skip this one for now. All I know is that you use tags like callout. I'll take a screen dump from xv running on a Dilbert strip and experiment.

Code samples

In writing technical documentation you frequently need to show pieces of program source code. You can do this with DocBook's programlisting tag:

<example>
<title>A simple C program</title>
  <programlisting role="C">
  #include <stdio.h>
  main()
  {
    printf("Hello, world!\n");
  }
  </programlisting>
</example>
	  

Here's what it would look like:

#include <stdio.h>
main()
{
  printf("Hello, world!\n");
}