Writing documentation with &DB;-XML 4.3

Writing documentation with &DB;-XML 4.3 A documentation system for print and Web &DB;-XML 4.3 John Shipman

john@nmt.edu

$Revision: 1.11 $ $Date: 2006/08/12 23:36:24 $

Advantages of &DB; The &DB; system has these advantages over other methods of creating documentation: The same document can be translated mechanically to both Web-based and printable formats. You as an author can concentrate on the content of your document, without worrying about how it will appear. The Tech Computer Center supplies a locally-customized installation of the &DB; translation software for output to PDF or Web form. You can use our installation, or install and customize &DB; yourself (see the &DB; Modular Style Sheets web site). However, this mechanical translation to various formats can be improved and tuned independently of the writing process. These improvements do not at all affect the &DB; files you write. This document assumes you are using &DB;-XML revision 4.3. If your document was done under the SGML versions, see and below.

How to get this publication This publication is available in Web form and also as a PDF document. Please forward any comments to tcc-doc@nmt.edu.

Setting up your directory for &DB; The &DB; software runs only under the Linux operating system. Also, the process of document creation is much, much easier with a validating XML editor. For an emacs-based validating XML editor, see XML document authoring with emacs nxml-mode. If all else fails, you can always use a regular text editor, but you will have to type every character of every tag yourself. The make system is a great timesaver in carrying out the steps of the &DB; document development cycle. Refer to the man page for make if you are not familiar with this product. Here is the procedure for setting up your directory: Create the directory with mkdir if it does not already exist. Use the cd command to move to the directory. Copy this “tarball” archive into the directory: cp /u/www/docs/tcc/doc/docbook43/tcc.tgz . Unpack it with this shell command: tar -xvzf tcc.tgz This adds three necessary files to your directory: Makefile operates the make utility to rebuild your output HTML, PostScript, and PDF files. model is a skeletal &DB; XML file to serve as the initial contents of your &DB; document file. logo.gif is the TCC logo in GIF format, which appears on the top right corner of all TCC publications. Feel free to replace this with your own image if you're not writing an Official TCC Document. Edit the Makefile. Find the line that looks like this: TARGET = your-document-base-name-here and replace the part after the = with the name of the file you will be creating, without its .xml suffix. For example, if you are writing a manual on stunting trees, you might name the source file bonsai.xml. In that case, you would replace the line above with: TARGET = bonsai Rename the model file as your starting XML file. To continue the previous example: mv model bonsai.xml

Creating and translating your document

What is &DB; and how does it relate to XML? &DB; is a document type derived from an ISO standard called XML (eXtensible Markup Language). (HTML, used to write World Wide Web pages, is also a markup language, and XML is similar in syntax.) All XML document types use the idea of tags to structure a document. A tag always starts with < and ends with >. Most tags are used in pairs. The start tag has the form <tag-name options> and the end tag has the form </tag-name> where the tag-name is some name that describes what the tag does. Some tags may also have options that change the way the tag works; some tags have no options. For example, major sections of a document are always enclosed between section and section tags. Some tags are called “empty” because they are used by themselves, not in pairs. Empty tags must have a forward slash (/) after the tag name. For example, the colspec/ gives information on a table column (See Section 10). There is no such thing as a colspec ending tag.

The &DB; workflow cycle Here is the basic workflow for the creation and maintenance of a document using &DB;. Use a validating XML editor or other editor to add the content of your document to the XML file. Follow the directions given in comments in the skeleton file. You will need to fill in the document's overall title, information on who you (the author) are, and so on. Once the model is filled in, add the title of the first section where indicated, and begin writing the body of the document. The writing process mainly proceeds by: Adding XML tags that describe the structure of the document. Placing the content of the document inside these tags. To render it into Web form as a group of HTML files, use: make web To translate your document into one of the final forms, use the make utility, which is driven by the Makefile you prepared above in . To render into print form using PDF (Adobe Page Description Format) file, use the Unix command: make pdf Or just type a make command by itself with no arguments to build both: make

Overall section structure Here is the model file discussed in :

### ### ###

###

$Revision: 1.11 $ $Date: 2006/08/12 23:36:24 $

]]> Note the last few lines above. This is the skeleton of the first section of your document. Place the section's title inside the <title> element, and add the section's content after the closing </title> tag. Each section element is a top-level section. They will be numbered as sections 1, 2, 3, and so on. To add subsections, use a section element inside the section element. For example: Main section title Main section content...

First subsection title First subsection content...

Second subsection title Second subsection content...

]]> If the main section were section 3, then the two subsections inside it would be numbered 3.1 and 3.2. You can include more section elements for sub-sub-sections, and so on.

The <code >titleabbrev</code > element: Short title The title element inside your articleinfo group will appear in the running footer on every page in the PDF version of the document. If your title is too long, it will be folded into two or more lines inside the footer. To cure this problem, place a titleabbrev element just after the main title element, containing a shorter version of the title that will fit inside the running footer. For example:

Exegesis of archetypal content and pataphysical normatives in <citetitle >Monty Python and the Holy Grail</citetitle > Monty Python and pataphysics ...]]>

Ordinary prose paragraphs For everyday text paragraphs, enclose each paragraph in a simpara element. Here's an example from the Declaration of Independence: <simpara> He has abdicated Government here, by declaring us out of his Protection and waging War against us. </simpara> <simpara> He has plundered our Seas, ravaged our Coasts, burnt our Towns, and destroyed the Lives of our People. </simpara> For paragraphs which include other complex structures such as bullet lists, screen shots, and such, it is necessary to use the para element. These will look the same in the final form as a simpara paragraph.

Inline markup &DB; has a number of elements that are useful for marking up content within a paragraph. By inline markup, we refer to tags that appear within a paragraph and do not change or interrupt its basic paragraph shape. <acronym>…</acronym> An abbreviation, generally made from the initial letters of words, and sometimes pronounceable. For example: PEBKAC stands for: Problem exists between keyboard and chair ]]> PEBKAC stands for: Problem exists between keyboard and chair. <application>…</application> Names of packages. Example: emacs.]]> Start emacs. <citetitle>…</citetitle> Used for citing works by their title. Example: Ringworld?]]> Have you read Ringworld? <code>…</code> For program source code. Example: panic() function.]]> Next we define the panic() function. <computeroutput>…</computeroutput> Computer-generated output. Example: OA210I OLD PSW WAS FF04230C 1200234B]]> OA210I OLD PSW WAS FF04230C 1200234B <emphasis>…</emphasis> Used for emphasized text. Example: do that then.]]> Don't do that then. <filename>…</filename> For file names and path names. Example: /fs/packages.]]> Packages live in /fs/packages. <foreignphrase>…</foreignphrase> Used to set off words in a different language than the surrounding text. Squalus.]]> These sharks are in genus Squalus. <guibutton>…</guibutton> Buttons in a graphical user interface. Example: Quit button.]]> To exit, click on the Quit button. <guiicon>…</guiicon> An icon in a graphical user interface. <guilabel>…</guilabel> A label in a graphical user interface. <guimenu>…</guimenu> A menu in a graphical user interface. Example: Team menu.]]> Pull down the Team menu. <keysym>…</keysym> For names of keys on a keyboard. Example: Enter.]]> Press Enter. <quote>…</quote> For in-line quotations. Example: common sense isn't. ]]> As Carol Schaffer used to say, common sense isn't. <replaceable>…</replaceable> Use this tag for parts of a template, pattern, or general case that will are to be replaced with specific items in practice. Example: f.tex, where f is some name of your choice.]]> Call your input file f.tex, where f is some name of your choice. <sgmltag>…</sgmltag> For the display of any XML or SGML tag. Use the attribute class="starttag" for a starting tag, and class="endtag" for an ending tag. Example: title...title tags.]]> Enclose the page title within title...title tags. <subscript>…</subscript> Displays the contents below the baseline. Example: 2O.]]> Drink more H2O. <superscript>…</superscript> Displays the contents above the baseline. Example: th of July.]]> Celebrate the 4th of July. <userinput>…</userinput> For commands or other user input. Example: make trouble.]]> Type the command make trouble. <varname>…</varname> For variable names in programs. Example: sheepCount.]]> Add one to sheepCount.

Links: connecting your document to itself and elsewhere The advent of hypertext technology gives us the opportunity to make it much easier for the reader to jump around when looking for information. However, &DB;'s ability to create both Web pages and paper copy complicates the task of linking. We want the Web versions to be hot-clickable, but keep in mind that the paper version must still be useful even though we can't click on it. The paper equivalent of a hyperlink is a cross-reference. A cross-reference within the same work might say something like “See the section on frog identification below.” If you phrase your document in this way and use the right tags carefully, this will read normally in the print version and the Web version will read the same way and also be a link. For cross-references to other locations in the same document, refer to and . For references to a Web page outside the document, see . the section on the ulink tag below. Both Web and paper documents may refer to external works: printed books or documents. For this kind of linking, use the citetitle tag under .

The <sgmltag class="starttag">link</sgmltag> and <sgmltag class="starttag">xref</sgmltag> tags: Linking within your document To refer to another location in the same document: Invent a unique identifier name, made from letters, numbers, hyphens, and the underscore (_) character. For example, you might use the identifier flute-tuning for a section on how to tune a flute. Find the start tag for the element to which you want to refer, and attach an id="I" attribute to that tag, where I is the identifier name you invented in the previous step. Any &DB; start tag can carry an id= attribute. For example, to refer to a main section, add the attribute to the section tag. At the location where you want to cross-refer, use a tag of the form: <link linkend="I">T</link> where I is the identifier defined in the previous step and T is the text of the link. For example: <section id="thule-history"> <title>The History of Thule</title> ... <section> ... <para>For more amusing folk traditions of Greenland, see <link linkend="thule-history">History of Thule</link> above. </para> In the HTML output, this will produce a clickable link. In the PostScript output, the content of the link element will be underlined. You can also use the empty (non-paired) tag anchor id="I" to define a target location, where I is the same unique identifier. Cross-references won't be correct the first time you build your PostScript file. Remove your .dvi file and rebuild it twice, and references should be correct the third time. You may find it easier to use the xref element to link to other locations within your document. This element is empty (has no content), since the link text is generated automatically. There are three ways to use this tag. All three require that you assign a unique id attribute to the tag to which you are linking: Just say xref linkend="I", where I is the target identifier. The link text will depend on the type of element. For example, a reference to a chapter element may generate link text containing the chapter number and title. If there is an element somewhere near the target identifier whose content you would like to use as the link text, use this construct: <xref linkend="I" endterm="J"> where I is the identifier of the element you want to link to, and the link text will be taken from the content of the element with id="J". For example, suppose a chapter starts like this: The <emphasis id="ch11-abbr">Last Chapter<emphasis>]]> Then this reference would use “Last Chapter” as the link text: ]]> You can specify what link text you want to use for a specific target by adding an xreflabel attribute to the target element. Any xref element that refers to that target will automatically use that attribute's value as its link text. For example, suppose you start a chapter like this: ...]]> then any reference of the form xref id="ch14" would use “The Silly Chapter” as its link text.

The <sgmltag class="starttag">ulink</sgmltag> tag: Linking outside your document To refer to a location on a Web page outside the current document, use the tag ulink url="U" tag, where U is the URL (Uniform Resource Locator) of the location to which you are referring. In the HTML output this will result in a clickable link. In print output, &DB; will include the URL after the link text so that readers can find the reference. Example: See the ulink url="http://www.nmt.edu/tcc/"TCC Help System at codehttp://www.nmt.edu/tcc/codeulink...” would display as: “See the TCC Help system at http://www.nmt.edu/tcc/...”

Special paragraph shapes

Bullet lists: <sgmltag class="starttag">itemizedlist</sgmltag> A bullet list is a set of narrower paragraphs shown with a round dot (the bullet) before each one. Typical uses are lists of features, lists of important points, and such. Enclose the entire bullet list inside an itemizedlist...itemizedlist element. Each item is then enclosed within a listitem...listitem element containing one or more para or simpara elements. For example, this input: Mangos. Chirimoya. ]]> produces this output: Mangos. Chirimoya. Normally, bullet lists have a fairly generous amount of space between the bullets. To reduce this space, add a spacing="compact" attribute to the itemizedlist element. Here is the example list again in compact spacing: Mangos. Chirimoya.

Numbered lists: <sgmltag class="starttag">orderedlist</sgmltag> To produce a numbered list of items, use the orderedlist construct. Here's an example: DocBook renders documents in both print and Web form. It frees the author from most concerns of presentation. Here's how the above list looks in source form: DocBook renders documents in both print and Web form. It frees the author from most concerns of presentation. ]]> There are a number of attributes you can add to the orderedlist element to change the way the entries are numbered: numeration The default value is numeration="arabic", with entries numbered 1., 2., 3., …. Other possible values include: numeration="loweralpha" for a., b., … numeration="lowerroman" for i., ii., iii., … numeration="upperalpha" for A., B., C., … numeration="upperroman" for I., II., III., … inheritnum="inherit" Normally, when you use an ordered list inside another ordered list, the inner list has its own numbering. However, if you specify inheritnum="inherit", each item number in the inner list will have the item number from the next outer list prepended to it. For example, if an inner list is under an outer-list item numbered 17, and the inner list had the inheritnum="inherit" attribute, its items would be numbered 17.1, 17.2, 17.3, …. spacing="compact" Normally the items of an ordered list are separated by generous amounts of space. Use the spacing="compact" attribute to squeeze out most of the space between the items. continuation="continues" Sometimes you have to break an ordered list into multiple pieces, with text paragraphs or other material between the pieces. This attribute allows you to start the numbering of a new list where the old one left off. For example, suppose the first chunk of an ordered list ended with item XIV, and another ordered list followed it starting with: ]]> That second list would start with item XV.

Procedures A step-by-step procedure is generally presented in a form similar to the bullet list, but with step numbers taking the place of bullets. Enclose the entire procedure within a procedure...procedure element. Each step is enclosed within a step...step element containing one or more para or simpara elements. For example, this input: Throw the football. Pick it up first. ]]> produces this output: Throw the football. Pick it up first. If the steps of your procedure refer to other steps, you can get &DB; to insert the step number into each reference automatically. To do this: Invent a name I for each step, and add an attribute id=I to the corresponding step tag. Wherever you want to refer to a step, use this tag: xref linkend=I where I is the name from the step you are referring to. This tag will be replaced by the text “step N” where N is the step number. Here's an example. This is a (facetious) solution to the famous Halting Problem. First, in output form: Has the program halted? If so, go to . Go to . Done: we now know that the program halts. And now the source for the above: Has the program halted? If so, go to . Go to . Done: we now know that the program halts. ]]>

Question-and-answer sets &DB; supports sets of questions and answers, such as Frequently Asked QUestions (FAQ) documents. The top-level element for a set of questions and answers is qandaset. Here is a very simple set of two Q&A pairs: At the Bridge of Death What is your favorite color? Blue. What is the air-speed velocity of an unladen swallow? What do you mean? An African or European swallow? Here's how that list is encoded: At the Bridge of Death What is your favorite color? Blue. What is the air-speed velocity of an unladen swallow? What do you mean? An African or European swallow? ]]> To specify the format, in the qandaset start tag, include a defaultlabel attribute with one of these values: defaultlabel='qanda' Label the questions with “Q:” and the answers with “A:”. defaultlabel='number' Number the entries. defaultlabel='label' Each question element and each answer element must have a label attribute containing the string to be used as a label. For a simple list of questions and answers, enclose each item in a qandaentry element. Inside the qandaentry, enclose each question in a question element and each answer in an answer element. You can have any number of question elements in a qandaentry element. You can have any number of answer elements in a qandaentry element, even none at all (for questions with no answer). If you want to structure your Q&A set into sections, you can use a qandadiv element inside your qandaset element, with one or more qandaentry elements inside that. To give the section a title, use a title element after the qandadiv element. Here's a partial example: Frequently axed questors Trolls I have put down ... ... Castle Anthrax ... ... ]]> You can even use qandadiv elements inside other qandadiv elements to divide your list into sublists, sub-sublists, and so on.

Definition lists: <sgmltag class="starttag">variablelist</sgmltag> Another commonly used special paragraph shape is to display a list of terms to be defined, each followed by an indented paragraph containing the description. For this shape, enclose the entire list in a variablelist tag. Each term-definition pair is enclosed in a varlistentry element. Inside that element, enclose the term to be defined inside a term element, and enclose the paragraph or paragraphs defining the term inside a listitem element. Here is an example of a list containing two terms: .__abs__(self) Defines the behavior of the abs() function when applied to an object of your class. .__add__(self,other) Defines the behavior of this class for self+other. ]]> And here is how that looks when formatted: .__abs__(self) Defines the behavior of the abs() function when applied to an object of your class. .__add__(self,other) Defines the behavior of this class for self+other.

Notes, warnings, cautions, etc. Sometimes you need to make some text stand out against the background. &DB; has several tags for such purposes: note warning important caution tip Typically you will put one or more regular paragraphs (using the para tag) inside such elements. Here's an example: Do not touch the electric fence! And here's that warning in source form: Do not touch the electric fence! ]]>

Block quotations Two different elements are used to present quotations set off in separate blocks: Use epigraph when the quotation starts a new chapter or section. Use blockquote for quotations elsewhere. In either case, the content of the element consists of an optional attribution element that tells the reader who said this. The actual quotation follows, typically wrapped in one or more para elements. Generally the attribution will be presented after the quotation. Here's an example:

C. A. R. Hoare There are two ways of constructing a software design. One way is to make it so simple that there are obviously no deficiencies. And the other way is to make it so complicated that there are no obvious deficiencies.

The source for the quote looks like this: C. A. R. Hoare There are two ways of constructing a software design. One way is to make it so simple that there are obviously no deficiencies. And the other way is to make it so complicated that there are no obvious deficiencies. ]]>

Verbatim displays By displays we mean the presentation of information in some form other than a paragraph: illustrations, representations of computer screens, and so on. To present one or more lines in a monospaced (fixed-width) font, as in a computer program, enclose the lines within programlisting...programlisting. For example, this input: <programlisting> 10 PRINT "BASIC IS OVER 40 YEARS OLD" 20 GOTO 10 30 END </programlisting> produces this output: 10 PRINT "BASIC IS OVER 40 YEARS OLD" 20 GOTO 10 30 END You can also use the element screen...screen to display something that appears on a screen. The formatting is the same as for the programlisting element. Line breaks are preserved starting immediately after the opening screen or programlisting tag; so, if you start your code display on the line following that tag, the display will start with a blank line.

Callouts in verbatim displays Sometimes you want to present a program listing or screen shot with callouts, little numbered graphic tags that appear within the display. Then, following the display, you present textual discussions for each callout. Here's an example: AWAKE! for Morning in the Bowl of Night Has flung the Stone that puts the Stars to Flight: And Lo! the Hunter of the East has caught The Sultan's Turret in a Noose of Light. Note the gratuitous capitalization. It appears that someone has struck the Sultan on the turret with an alarm clock. In order to use callouts, you must have a subdirectory named callouts in the same directory as your document, containing the actual callout images in two formats (PNG for web pages, PDF for print presentation). There are two ways to make these callouts available under Linux. Make a soft link from your directory: ln -s /u/www/docs/tcc/help/image/callouts . Or, copy an archive file containing that whole directory and unpack it in your directory: cp /u/www/docs/tcc/help/image/callouts.tgz . tar -xvzf callouts.tgz That directory currently contains graphics for twenty callouts numbered 1 to 20. If you don't like their appearance or need more than 20, see the README in that directory to see how to create your own. Once you have installed the callout graphic files, to use callouts in your screen or programlisting element: Add an element of the form

<co
            id="I">

within the display where you want a callout to appear. Invent a unique identifier I to be used later. When you have decorated your display with co elements, add a calloutlist element after the end of the display. Within that calloutlist element, for each callout that you used in the display, add one element of the form <callout arearefs="I"> for each callout you used above. Add your textual description (or graphics or whatever) within the callout element. If you need to put anything other than ordinary text inside the callout element, wrap it inside a para element. Here's how the above example looks in source form: AWAKE! for Morning in the Bowl of Night Has flung the Stone that puts the Stars to Flight: And Lo! the Hunter of the East has caught The Sultan's Turret in a Noose of Light. Note the gratuitous capitalization. It appears that someone has struck the Sultan on the turret with an alarm clock. ]]>

Poetry When formatting poetry and similar text, use the literallayout tag. Like the programlisting element, it presents the content with all whitespace and line breaks intact, but it uses a regular text font. Here's an example from Piet Hein: Problems worthy Of attack Prove their worth By hitting back.

Including graphic images You can easily include images in a &DB; document. However, you may have to produce two different versions of some images so that they will look decent in both print and Web presentation.

Formal and informal figures A formal figure is a graphic image presented with a title. For example, suppose you have scanned a photo and called the result lanai.jpg. Here is how you would include that photo as a formal figure: Lanai from the air ]]> An informal figure is just a figure without the title. To present the same graphic as an informal figure: ]]> If you want to change the displayed size of the image, add an attributes scale="P" to the imagedata element, where P is the percentage size, e.g., 33 for one-third size. Here is an example of a 500x100-pixel panel from Pokey the Penguin shown first at half size (scale="50"), then at one-quarter size (scale="25").

Tuning graphics for different roles For some types of graphics, such as photos or screenshots, the technique above will work fine. However, due to the different resolutions of screens and printers, some types of graphics—especially diagrams and other vector-type drawings—will not look right both in Web and print presentation. Consider the case of a graphic prepared using a drawing program such as xfig. If the graphic is exported as a JPEG or GIF image, it must be rasterized. If it rasterized at its design size, it might look okay on a screen, but in print it is likely to suffer from aliasing, the “stairstep” effects caused by not enough dots. A solution that works for print presentation is to export the figure at some large magnification, like 200% or 400%, and then use scale="50" or scale="25" to shrink it down so it fits into the right space on the printed page. However, the problem with that approach is that the graphic will now be two or four times too large in its Web form. The solution is to prepare two different forms of the original graphic, one optimized for print presentation and one for Web use. For Web presentation, prepare the graphic as one of the common rasterized formats: JPEG, PNG, or GIF. If possible, use PDF format for print presentation. PDF format is a scalable vector representation that allows the graphic to be scaled in a way optimized for the specific printer being used to render it. Once you have prepared the two forms, you can then include them in the same document as two different imageobject elements within the same mediaobject element. Tag the mediaobject element with the Web version with an attribute role="html", and tag the print mediaobject with an attribute role="fo". For example, suppose you have produced a diagram in the xfig drawing program and called it flow.fig. For HTML, export it as in PNG format as flow.png; then export it in PDF format as flow.pdf. To include both figures, you might use this construct: Mill flow diagram ]]> Once you have this dual presentation in place, you can adjust the size of each figure independently by using scale="…" attributes on the imagedata elements.

Scaling a figure When sizing a figure for presentation, there are two different areas involved: The image size is the size of the image itself. The viewport is the area in which the figure is supposed to be presented. If one dimension of the image is smaller than that dimension of the viewport, the result will be empty space around the figure. But what if the viewport is smaller than the image? In print presentation, the image will be cropped; but in Web presentation the image will not be cropped. In general there are six different attributes of imagedata that affect scaling: contentwidth and contentdepth These attributes set the desired image size. The attribute value must be a number, optionally followed by one of the dimension codes px (pixels, the default), pt (points), cm (centimeters), mm (millimeters), pc (picas), in (inches), em (ems), or % (percent, relative to the page width for horizontal dimensions). For example, if you want the image to be 125mm×75mm, use: ]]> You need only specify one of these two attributes; if only one dimension is specified, the other dimension will be scaled to preserve the aspect ratio (ratio of height to width). width and depth These attributes size the viewport. If you specify the width as a percentage (%), it will be treated as a percentage of the available page width. scale Resizes the graphic as a percentage of the original; omit the % symbol from the attribute value. For example, to render a graphic half-size, use scale="50". scalefit If you specify scalefit="1", the graphic will be scaled to fit the available area—either the graphic size or the viewport size, whichever is filled first. If you specified no other sizing attributes, the graphic will be scaled to fit the page width.

Inline graphics To include an inline figure in the middle of a paragraph, use the inlinemediaobject element. Inside this element, place an imageobject as above to specify the image, and also include a textobject element with the text that should appear in situations where the image cannot be displayed, such as browsers for the visually impaired. Here is an example: Use this icon Icon for circle by diameter to create a circle by specifying its diameter. And here is the source for this paragraph: Use this icon Icon for circle by diameter to create a circle by specifying its diameter. ]]>

How to get screen shots (Windows, MacOS, and Linux) To capture an image from your screen, follow the procedure below for your operating system.

How to get a Windows screen shot On Windows 2000 and later systems, press the PrintScrn button. This will take a shot of the entire screen. You can then use the paste function in your favorite photo editor to make a copy of this screen shot, crop out the part you want, and so forth.

How to get a MacOS screen shot To capture an image of a specific rectangular area, press Apple-shift-4 (that is, while holding down the Apple and shift keys, press 4). The cursor will turn into a crosshair symbol. Move the mouse to one corner of the desired area, press and hold the left button, drag the mouse to the opposite corner of the area, and release the button. An icon named “Picture 1” (or other number) will appear in your desktop; this will contain the image of the selected area in PNG (Portable Network Graphics) format. To capture an image of one window, press Apple-shift-4, and when the cursor turns into a crosshair symbol, press the space bar. The cursor turns into a picture of a camera. Move the mouse into the window you want to photograph, and that window will turn slightly gray. Click the left button and the image icon will appear on your desktop. To capture an image of the entire screen, use Apple-shift-3.

How to get a screen shot under Linux Gimp, a public-domain package similar to Photoshop, makes it easy to get a screen shot. Bring up Gimp. From the Start menu, select Graphics, then GIMP Image Editor. From the Gimp menu, select File, then Acquire, then Screen Shot.... To capture an image of one window, select the radiobutton for a Single Window, increase the delay time under Select Window After...Seconds Delay, and click OK. After the delay you have specified, the cursor will turn into a crosshair symbol. Move the cursor into the desired window and click the left mouse button. To capture an image of the entire screen, select the radiobutton for the Whole Screen, increase the delay time under Grab After ... Seconds Delay, and click OK. After the delay you have specified, Gimp will take a snapshot of the whole screen. A window containing your snapshot will appear on your screen. You can use Gimp to crop the image, adjust color and contrast, and the other usual photo processing options. Most operations start by right-clicking on the image. To save the image to a file, move the mouse into the image window and right-click. Then select File, then Save. You can navigate to any directory by clicking in the Folder window. Click on “../” to go up one directory; to move down into a directory, click on that directory's name in the Folder window. Once you are in the right directory, type the name you want to give the graphics file in the Selection field, including the file type suffix such as .png or .jpg, and press Enter.

Tables &DB; has extensive features that help you present data in a tabular form. Here is an example of a small table: All-time NBA free throw percentages Player FTA FTM Pct. Rick Barry 4,243 3,818 .900 Calvin Murphy 3,864 3,445 .892

Here is how the XML source for the table looks: All-time NBA free throw percentages Player FTA FTM Pct. Rick Barry 4,243 3,818 .900 Calvin Murphy 3,864 3,445 .892 ]]> Let's look at these tags and their attributes in detail: The table element encloses the entire table. The attribute frame="topbot" specifies that ruled lines be placed over the top and bottom of the table as a while. The attribute pgwide="0" tells &DB; to place the table within the current paragraph width. If a page break falls in the middle of a table, the heading will be repeated on the new page. Every table must be titled, so the next thing after the table opening tag should be a title...title element. The tgroup element encloses the entire rest of the table. Its cols= attribute gives the number of columns for the table as a whole. There is a colspec element for each column of the table that specifies how the column is to be presented. The colwidth attribute specifies the width of the column. In this example, we want the first column to be three times as wide as the other columns, so we use a value of "3*" for the first column and "*" for the rest. The align attribute specifies whether the contents of each column are to be positioned to the left or right side. The thead element encloses the heading section of the table. The heading consists of a row element containing one entry element for each heading. Note that the row tag has an attribute rowsep="1" that places a ruled line after that row. The rows in the table body do not have that attribute and are not separated by rules. The tbody element comes after the last colspec element, and encloses the actual body of the table. Each row of the table is enclosed in a row element. Each cell in the table is enclosed within an entry element. The sections below discuss a number of ways you can control the appearance of your table, but not all details of table construction are covered. For the full gory details, see the CALS table model Document Type Definition.

Ruled lines in tables The default table appearance is to have rules (ruled lines) around the outside of the table and between all rows and columns. You can control where rules appear by adding attributes to the various start tags in your table. There is a hierarchy of tags: attributes of the table tag set values for the table as a whole. Attributes of colspec set values for all entries in a column, and may override values set in the table tag. Attributes of the row and entry tag can in turn override those values. The example table above shows this process. The frame="topbot" attribute of the table tag specifies that rules appear only above and below the table as a whole. But the rowsep="1" attribute of the row tag for the first row overrides that specification, forcing a rule to appear below the first row. Here are the tags and attributes that affect ruled lines: In the table tag, the frame= attribute can have any of these values: Value Meaning all Rules are placed above and below the table, on the left and right sides, between columns, and between rows. none No rules are used in the table. sides Rules are placed only at the left and right sides of the table. top A rule is placed only above the table. bottom A rule is placed only below the table. topbot Rules are placed above and below the table. Any of the tags table, tgroup, colspec, and entry can have a colsep="..." attribute. Use colsep=0 to suppress rules to the right of a column, or colsep="1" to place rules to the right of a column. The attribute for table sets the default for the table as a whole; the attribute for tgroup overrides the value for table; and so forth, with the value for deeper elements overriding the values of all shallower elements. Any of the tags table, tgroup, row, and entry can have a rowsep="..." attribute. Use rowsep=0 to suppress the rule below the row (or cell, for entry). Use rowsep="1" to place a rule below the row (or cell). As with the colsep attribute, values of this attribute for deeper elements override values in shallower elements.

Controlling table dimensions Normally, your table will be fit into the page width remaining after the current indentation level is subtracted from the total page width. However, if you need more width, use a pgwide="1" attribute in your table tag. This will give you the whole width of the page to work with. Your other job is to distribute this width among the columns of the table. You can do this in two ways: You can assign a specific width to each column of the table. However, this can make life more difficult for people reading the Web version of your document if their window is too narrow for your table. A better way is to specify the relative width of the columns. The advantage of this method is that in Web form your table can be resized to conform to the width of the browser window. Regardless of which method you use, the width of each column is specified in the colspec colwidth="..." attribute, which can take these values: A number followed by a unit of measure. Units include: pt (printer's points, about 1/72 inch), pi (picas, about 1/6 inch), mm (millimeters), cm (centimeters), or in (inches). For example, colwidth="5.5cm" would specify a width of 5.5 centimeters. A number followed by an asterisk. This allows you to specify relative column widths. With this method, all the numbers are added up, and the space is divided according to the coefficients. The numbers can be integers or fixed-point constants such as 5.25. For example, suppose your table has four columns and the values of the colwidth attribute are "3*", "*", "2*", and "2*". The sum of these coefficients (the second value is the same as "1*") is 8. The resulting table would allocate 3/8 of the width to the first column, 1/8 of the width to the second column, and 1/4 of the width to each of the third and fourth columns.

Controlling alignment in tables By alignment, we mean the positioning of elements within the cells of a table. Since most cells will not be filled exactly, we need ways of controlling where the content is placed within the cell, both horizontally and vertically. Horizontal alignment is controlled by the align="..." attribute. This attribute can be used: in a tgroup tag to set the default alignment for the table as a whole; in a colspec tag to set the default alignment for one column; or in an entry tag to set the alignment for a specific cell. Attribute values for deeper elements override those for shallower elements. The value of the align attribute can be any of the following: Value Meaning left Content is aligned to the left side of each cell. right Content is aligned to the right side. center Content is centered. justify Text is shown as a justified paragraph, stretched to the full width of the cell. Vertical alignment is controlled by the valign="..." attribute. This attribute can be used: in a row tag to set the default alignment for that row; or in an entry tag to change the alignment of a single cell. The value of the valign attribute can be any of these: Value Meaning top Content is aligned to the top side of each cell. middle Content is centered vertically in the cell. bottom Content is aligned to the bottom of the cell.

Spanning in tables So far we have talked only about tables with a cell at the intersection of each row and column. In the real world, though, we often need to span cells, that is, to combine two or more cells into a larger area that holds a single item. Here is a small table that demonstrates spanning. Note that the last two column headings are each centered over two columns: Rising and setting of Venus, 1994 20 degrees N. Lat. 30 degrees; N. Lat. Rise Set Rise Set Jan. 1 6:21 17:14 6:43 16:52 11 6:35 17:31 6:56 17:10

Here's the source for the first part of this table: Rising and setting of Venus, 1994 20 degrees N. Lat. 30 degrees; N. Lat. ]]> Note the additional colname attributes within the colspec tags. These attributes give names to the columns of the table. The spanned elements refer to these names in order to specify where the spanning starts and ends. The entry tags for a spanned element have attributes namest="A" and nameend="B", where A is the column name where the span starts and B is the column name where the span ends.

User-defined entities You may wish to abbreviate a frequently-used word or phrase as an entity in your document. This allows you to substitute a short string of the form &n; wherever that word or phrase is used, and the full text will be substituted automatically. The entity's name part n is a symbolic name following the usual XML conventions (starting with a letter, and containing only letters, digits, underbars “_”, and hyphens “-”). Place your entity definitions in the <!DOCTYPE> declaration at the top of your document, enclosed in square brackets and just before the closing “>”. Each declaration looks like this: <!ENTITY n "T"> where n is the entity's name and T is the replacement text. For example, suppose you are developing a product under the internal code name Daisy, and you want to write the manual without having to know the final, public name of the product would be. You can define an entity &Daisy; as the text “DaisyMatic” by changing your document type declaration to look like this: ] >]]> Then, when the marketing department decides that the external product name is going to be “MegaMonsterMatic-3000”, just change the replacement text and rebuild your document, and the new product name will appear everywhere: ] > ]]> You can have any number of entity declarations between the square brackets “[...]”.

Breaking your document into multiple files For larger documents, it is often convenient to break the document into more than one file, so you can work on a specific chapter or section by itself. This is easy to do because of another type of entity declaration that you can put inside your DOCTYPE. Here's the general form: <!ENTITY new-name SYSTEM "filename"> This defines a new entity named “&new-name;”. If this entity appears in your document, the effect is to insert the contents of file filename at that point. Here's an example. Suppose you want to break your document up into four files—a top-level file named mydoc.xml and three subsidiary files named head.xml, body.xml, and tergum.xml. File mydoc.xml might look like this: <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY head SYSTEM "head.xml"> <!ENTITY body SYSTEM "body.xml"> <!ENTITY tail SYSTEM "tergum.xml"> ] > <article> <articleinfo> …  </articleinfo> &head; &body; &tail; </article> There is one drawback to this method. If you are using special character entities such as ° (the degree symbol, °), your HTML and PDF output files will still build normally, but some editing tools (such as emacs nxml-mode) will no longer validate these character entities, because they see only the current file, and in the subsidiary files there is no <!DOCTYPE> declaration to tell them where the entities are defined. The workaround for this problem is to use the alternate form for each entity that uses the hexadecimal Unicode character value. For example, the degree symbol entity “°” can also be expressed as “°”. For a complete list of all special character entities in both name and numeric form, see .

Special characters Entities for these five special characters are always available: < < > > & & ' ' " " DocBook supports a modest set of letters with diacritical marks. Use the entity name shown in the first column to get the character shown in the second column. The third column shows an alternative form using a numeric value; such entities are less user-friendly but may be necessary in some circumstances. Entity Character Equivalent á á á Á Á Á â â â Â Â Â à à à À À À å å å Å Å Å ã ã ã Ã Ã Ã ä ä ä Ä Ä Ä æ æ æ Æ Æ Æ ç ç ç Ç Ç Ç ð ð ð Ð Ð é é é é É É É ê ê ê Ê Ê Ê è è è È È È ë ë ë Ë Ë Ë í í í Í Í Í î î î Î Î Î ì ì ì Ì Ì Ì ï ï ï Ï Ï Ï ñ ñ ñ Ñ Ñ Ñ ó ó ó Ó Ó Ó ô ô ô Ô Ô Ô ò ò ò Ò Ò Ò ø ø ø Ø Ø Ø õ õ õ Õ Õ Õ ö ö ö Ö Ö Ö ß ß ß þ þ þ Þ Þ Þ ú ú ú Ú Ú Ú û û û Û Û Û ù ù ù Ù Ù Ù ü ü ü Ü Ü Ü ý ý ý Ý Ý Ý ÿ ÿ ÿ Also supported are a wide variety of special symbols. Refer to O'Reilly's book DocBook for a complete list. Here is a selection: ¦ ¦ ¦ Broken vertical bar ¢ ¢ ¢ Cents © © © Copyright ¤ ¤ ¤ Currency symbol &dagger; † † Dagger &Dagger; ‡ ‡ Double dagger ° ° ° Degree symbol ÷ ÷ ÷ Division ↓ ↓ ↓ Down arrow … … … Horizontal ellipsis ¡ ¡ ¡ Inverted exclamation point ¿ ¿ ¿ Inverted question mark « « « Left double angle quotes ← ← ← Left arrow “ “ “ Left double quote &ldquor; „ „ Double low-nine quote ‘ ‘ ‘ Left single quote &lsquor; ‚ ‚ Single low-nine quote — — — Em-dash · · · Middle dot     Non-breaking space – – – En-dash ¶ ¶ ¶ Paragraph (pilcrow) symbol ± ± ± Plus or minus £ £ £ Pounds sterling ′ ′ ′ Prime ″ ″ ″ Double prime » » » Right double angle quotes → → → Right arrow ” ” ” Right double quote ® ® ® Registered &rdquor; ” ” Double high reversed quote ’ ’ ’ Right single quote &rsquor; ’ ‟ Single high reversed quote § § § Section symbol × × × Multiplication ™ ™ ™ Trademark ↑ ↑ ↑ Up arrow ¥ ¥ ¥ Yen symbol

FOP: An older, free toolchain This document assumes that you have XEP, a commercial product from RenderX. DocBook can also be processed using an open-source product, FOP from Apache. The Tech Computer Center no longer supports the locally customized DocBook installation that works with FOP, but it is still available. The software is generally reliable, but has the following specific limitations and problems.

FOP limitations These features of XEP won't work in the FOP toolchain: You can't use any of the common entities such as “ for left double-quote. Graphics in PNG format are not supported. User-defined entities will not work.

Bad page breaks Sometimes a section or subsection title will appear at the bottom of a page, with the first line of the following paragraph at the top of the next page.

Using tables inside <sgmltag class="starttag">listitem</sgmltag> If you use a table or informaltable inside a listitem element (which in turn is part of a itemizedlist or variablelist construct), the Flow Object Processor (FOP) will loop endlessly.

Graphics file support PNG (Portable Network Graphics) and EPS (Encapsulated PostScript) graphics files are not currently supported.

Converting &DB;-SGML 4.1 documents If you have a document built under SGML-based &DB;, follow these steps to convert it to XML. Replace the <!DOCTYPE...> declaration at the top of your document with the one from the first two lines of the model file in your working directory (assuming you followed the directory setup procedure above), or use /u/www/docs/tcc/help/pubs/docbook43/user-kit/model. If you use pictures and other graphics, refer to the section above on including graphics. At this writing, only JPG and GIF formats are supported.

Converting &DB; 3.0 documents If you have a document that worked under the old 3.0 version of &DB;, converting it is a simple matter: Move the title element from its old position inside the artheader element, to a position immediately after the article element at the very beginning of the document. Change the artheader tag and its closing artheader tag to articleinfo ... articleinfo.