Re: DSSSL Documentation Project?

Subject: Re: DSSSL Documentation Project?
From: Tony Graham <tgraham@xxxxxxxxxxxxxxxx>
Date: Mon, 16 Jun 1997 21:08:54 -0400 (EDT)
At 13 Jun 1997 17:53 +0100, Sebastian Rahtz wrote:
 > i dont use DocBook, so i dont know how it deals with examples. so far
 > as I can see, the ordinary structure (paras, lists, trivial tables,
 > headings) might as well be HTML as anything, and the meta stuff is
 > easy to do with ad hoc tags. but i am more concerned about 
 > consistent tagging of 
 > 
 >  - SGML examples
 >  - DSSSL specification examples
 >  - DTD examples
 >  - index terms
 >  - URLs
 > 
 > if DocBook has an obvious way of tagging each of the above, then could
 > someone familiar with it provide a 20 line example/template for a FAQ
 > entry? 

I'm not nearly as familiar with DocBook as I used to be, but the
remainder of this message is a first attempt at an example entry.

Regards,


Tony Graham
=======================================================================
Tony Graham, Consultant
Mulberry Technologies, Inc.                         Phone: 301-231-6931
6010 Executive Blvd., Suite 608                     Fax:   301-231-6935
Rockville, MD USA 20852                 email: tgraham@xxxxxxxxxxxxxxxx
=======================================================================

<!DOCTYPE sect1 PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<!-- $Id: faqsample.sgm,v 1.1 1997/06/16 21:01:10 tkg Exp $ -->
<sect1>
<title>Major level of FAQ</title>
<sect2>
<sect2info>
<!-- Is is possible to record the author or authors -->
<author>
<firstname>Tony</firstname><surname>Graham</surname>
</author>
<!-- And it is also possible to capture the revision history -->
<revhistory>
<revision>
<revnumber>0.1</revnumber>
<date>19970614</date>
<authorinitials>Tony Graham tgraham@xxxxxxxxxxxxxxxx</authorinitials>
<revremark>Initial attempt at FAQ example/template</revremark>
</revision>
</revhistory>
</sect2info>
<title>What is an example FAQ item?</title>
<para>A contrived collection of tags interspersed with a seemingly random
text, it is meant to illustrate the use of tags, and the text is, well, an
afterthought.</para>
<sect3>
<title>Why put a Sect3 in a FAQ item?</title>
<para>Maybe what you have to say is best broken up into smaller sections, or maybe it's as disjointed as this example and there's no point pretending it's a coherent whole.</para>
</sect3>
<sect3>
<title>SGML Example</title>
<para>SGML can be inline such as this <sgmltag class="starttag">sgmltag class="starttag"</sgmltag> or blocks of SGML may be included in a <sgmltag>programlisting</sgmltag>:
<programlisting>&lt;doc>
&lt;para>hello, world&lt;/para>
&lt;/doc></programlisting></para>
</sect3>
<sect3>
<title>DSSSL Specification Example</title>
<para>This shows a simple but effective stylesheet for use if you like <emphasis>everything</emphasis> in 10pt Times Roman (or &ldquo;iso-serif&rdquo; where available)</para>
<programlisting>&lt;!doctype style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN">
;; $Id: faqsample.sgm,v 1.1 1997/06/16 21:01:10 tkg Exp $</programlisting>
</sect3>
<sect3>
<title>DTD Example</title>
<para>DTD examples are probably just another <sgmltag>programlisting</sgmltag>:
<programlisting>&lt;!DOCTYPE doc [
&lt;!--                    DOCUMENT                                   -->
&lt;!ELEMENT  doc          - - (para+)                                  >


&lt;!--                    PARAGRAPH                                  -->
&lt;!ELEMENT  para         - - (#PCDATA)                                >
]></programlisting></para>
</sect3>
<sect3>
<title>Index Terms</title>
<para>DocBook does include <indexterm><primary>Primary index term</primary>
<secondary>Secondary index term</secondary>
<tertiary>Tertiary index term</tertiary></indexterm>index term elements,
although they are an inclusion at <sgmltag class="starttag">sect1</sgmltag>
and above so the index term wouldn't parse if the document started at
<sgmltag class="starttag">sect2</sgmltag> or below.</para>
</sect3>
<sect3>
<title>URLs</title>
<para>Use <sgmltag class="starttag">ULink</sgmltag> for URLs such as
<ulink url="http://www.mulberrytech.com/dsssl/dssslist";>DSSSList</ulink>
</para>
</sect3>
</sect2>
</sect1>


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist


Current Thread