2.8. Screens and program listings

Preparing Cogent Documentation :
	Chapter 2. Making Edits in doc/i/

Our documents often show what a reader might see on the computer screen. There is a special tag for this, <screen>. The output from this tag is indented (as specified in the stylesheet) and in a monospaced (Courier) font.

You must remove all tabs and left-justify all text within the <screen> tags. Any indents or tabs in the original screen or source document should be entered as spaces. Make sure you do not use the Emacs fill-paragraph (Alt-q) command on screen text, or you will lose all formatting. For the same reason, keep the start and end tags separated from adjoining <para> tags by using newlines, so that filling those paragraphs won't reformat your <screen> text.

The SGML source for a <screen> should look like this:

         ...</para>
      <screen>
Screen content goes here.
This line is flush left.
    This line has been indented 4 spaces.
</screen>
      <para>...

To save time and facilitate updates, you don't have to write any source code into SGML. It can be included in much the same way as an inline image. For example:

  <programlisting><inlinemediaobject>
    <imageobject>
      <imagedata format="linespecific" fileref="../../../i/phgamma/ex-PtFlush.g"/>
      </imageobject>
    </inlinemediaobject></programlisting>

At run-time the code in the doc/i/phgamma/ex-PtFlush.g file will be automatically inserted at this point in the document. This is especially useful for examples or any other code that may be revised in the future.

Although there is apparently no difference in the rendered output using our existing tool chain, the DocBook guide recommends that the <inlinemediaobject> tag come right after the <programlisting> tag in the markup.

2.8.1. Program listings in XML

With the switch to XML, we have found that the feature explained above is not supported by XSL stylesheets out-of-the-box, but requires an extension. Unfortunately, our XSL processor (xsltproc) does not currently support extensions. So, we have to use XIncludes, as described in Bob Stayton's book DocBook XSL: The Complete Guide, in the External Code and DTD customizations for XIncludes sections. This involves several things:

We have a DTD customization file named doc/o/config/xinclude.mod that contains the following:

<!ELEMENT xi:include (xi:fallback?) >
<!ATTLIST xi:include
    xmlns:xi   CDATA       #FIXED    "http://www.w3.org/2001/XInclude"
    href       CDATA       #REQUIRED
    parse      (xml|text)  "xml"
    encoding   CDATA       #IMPLIED >

<!ELEMENT xi:fallback ANY>
<!ATTLIST xi:fallback
    xmlns:xi   CDATA   #FIXED   "http://www.w3.org/2001/XInclude" >

<!ENTITY % local.programlisting.char.mix "| xi:include">

<!-- This goes in the top of the XML document.
<!ENTITY % xinclude SYSTEM "xinclude.mod"> %xinclude;
-->

The cogsgml script uses a sed script (prex.sed) to add the following lines to the main.xml file.

<!DOCTYPE book SYSTEM "/usr/share/sgml/docbook/xml-dtd-4.2-1.0-17/docbookx.dtd" [
<!ENTITY % xinclude SYSTEM "../../config/xinclude.mod"> %xinclude;
]>

The osx and xsltproc processors don't include the document type (DOCTYPE) declaration in XML output, since it isn't necessary. This step puts it in so that XIncludes can be added to the document.

The cogsgml script then uses xsltproc with a special stylesheet (html-prex.xsl) to preprocess the file, replacing this code:

<imageobject>
  <imagedata format="linespecific" fileref="path/to/filename.ext">
</imageobject>

With this:

<xi:include href=[quot  ]path/to/filename.ext[quot  ] parse=[quot  ]text[quot  ]
xmlns:xi=[quot  ]http://www.w3.org/2001/XInclude[quot  ]/>

The cogsgml script then processes that output, which is still XML, into other formats, like HTML.


2.7. Images		2.9. Updating version and revision numbers