DocBook and Jade for Literate Programming


Date:      Thu,  5 Nov 1998 07:50:01 -0500
From:      Norman Walsh <ndw@nwalsh.com>
To:        dssslist@mulberrytech.com
Subject:   DocBook and Jade for Literate Programming

This thread finally made me implement something I've been thinking about for months: a DocBook-derived DTD with the DSSSL architecture. Now I can write my DocBook stylesheets in the "obvious" literate way ;-)

(I'm thinking I might convert entirely to this scheme in some future DocBook DSSSL Stylesheet release.)

Here's the DTD I'm using this morning:


<!-- ================================================================= -->
<!-- A DTD for Literate DSSSL Programming with DocBook.  

     Copyright (C) 1998 Norman Walsh
     This DTD may be distributed under the same terms as the
     Modular DocBook Stylesheets (http://nwalsh.com/docbook/dsssl/)

     This DTD is an extension to DocBook that conforms to the DSSSL
     architecture.  This means that instances of this DTD can be
     legal DSSSL stylesheets and (almost) legal DocBook documents
     simultaneously.

     This DTD as DSSSL:

     Instances of this DTD conform to the DSSSL architecture if and
     only if they contain a BOOK and that BOOK contains one or more
     PROGRAMLISTINGS.  An EXTERNAL-SPECIFICATION, if required, must
     be provided in the SETINFO element.

     This DTD as DocBook:

     Instances of this DTD are extensions of DocBook in the following
     small ways:
 
     - SETs may consist of only a single BOOK.
     - SETINFO may include EXTERNAL-SPECIFICATION.
     - EXTERNAL-SPECIFICATION is new.
     - BOOK has two additional attributes, DSSSL (#FIXED) and USE to
       point to EXTERNAL-SPECIFICATIONs.
     - PROGRAMLISTING has an additional attribute, DSSSL (#FIXED).

     A typical invocation:
     <!DOCTYPE book PUBLIC 
       "-//Norman Walsh//DTD Literate DSSSL Programming with DocBook V1.0//EN">
-->
<!-- ================================================================= -->

<!-- =================== Declare the DSSSL Architecture ============== -->

<?IS10744 ArcBase DSSSL>
<!NOTATION DSSSL   PUBLIC "ISO/IEC 10179:1996//NOTATION
                   DSSSL Architecture Definition Document//EN"
                -- A document architecture conforming to the
                   Architectural Form Definition Requirements of
                   ISO/IEC 10744.     --
>

<!ATTLIST #NOTATION DSSSL
                            -- Support attributes for all architectures --
  ArcQuant CDATA #FIXED "NAMELEN 64"
  ArcDTD CDATA #FIXED "%DSSSLDTD"
  ArcDocF NAME #FIXED dsssl-specification
  ArcDataF NAME #FIXED dsssl-specification
>

<!ENTITY % DSSSLDTD PUBLIC
 "ISO/IEC 10179:1996//DTD DSSSL Architecture//EN"
>

<!-- ============================ Load DocBook ======================= -->

<!ENTITY % set.module "IGNORE">
<!ENTITY % setinfo.module "IGNORE">
<!ENTITY % book.module "IGNORE">
<!ENTITY % programlisting.module "IGNORE">

<!ENTITY % docbook PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
%docbook;
                  
<!-- ============ Adjust DocBook to fit the DSSSL Architecture ======== -->

<!ENTITY % local.set.attrib "">
<!ENTITY % set.role.attrib "%role.attrib;">
<!ELEMENT Set - O ((%div.title.content;)?, SetInfo?, ToC?,
		(%book.class;)+, SetIndex?)
		+(%ubiq.mix;)>
<!ATTLIST Set
		--
		FPI: SGML formal public identifier
		--
		FPI		CDATA		#IMPLIED
		%status.attrib;
		%common.attrib;
		%set.role.attrib;
		%local.set.attrib;
>

<!ENTITY % local.setinfo.attrib "">
<!ENTITY % setinfo.role.attrib "%role.attrib;">
<!ELEMENT SetInfo - - ((Graphic | LegalNotice | ModeSpec | SubjectSet 
	| KeywordSet | ITermSet | %bibliocomponent.mix; 
	| external-specification)+)
	-(BeginPage)>
<!ATTLIST SetInfo
		--
		Contents: IDs of the ToC, Books, and SetIndex that comprise 
		the set, in the order of their appearance
		--
		Contents	IDREFS		#IMPLIED
		%common.attrib;
		%setinfo.role.attrib;
		%local.setinfo.attrib;
>

<!ENTITY % local.book.attrib "">
<!ENTITY % book.role.attrib "%role.attrib;">
<!ELEMENT Book - O ((%div.title.content;)?, BookInfo?, Dedication?, ToC?, LoT*, 
		(Glossary|Bibliography|Preface)*,
		(((%chapter.class;)+, Reference*) | Part+ 
		| Reference+ | (%article.class;)+), 
		(%appendix.class;)*, (Glossary|Bibliography)*, 
		(%index.class;)*, LoT*, ToC?)
		+(%ubiq.mix;)>
<!ATTLIST Book	
		--
		FPI: SGML formal public identifier
		--
		FPI		CDATA		#IMPLIED
		%label.attrib;
		%status.attrib;
		%common.attrib;
		%book.role.attrib;
		%local.book.attrib;
                DSSSL NAME #FIXED style-specification
		USE IDREFS #IMPLIED
>

<!ENTITY % local.programlisting.attrib "">
<!ENTITY % programlisting.role.attrib "%role.attrib;">
<!ELEMENT ProgramListing - - ((%programlisting.content;)+)>
<!ATTLIST ProgramListing
		%width.attrib;
		%linespecific.attrib;
		%common.attrib;
		%programlisting.role.attrib;
		%local.programlisting.attrib;
		DSSSL NAME #FIXED style-specification-body
>

<!ELEMENT external-specification - o empty>
<!ATTLIST external-specification
		ID		ID	#REQUIRED
		Document 	ENTITY	#REQUIRED
		SpecId 		NAME 	#IMPLIED
>

<!-- ================================================================= -->

And an example: (I hacked this a little in the email message, so maybe it won't parse, but it should ;-)


<!DOCTYPE set SYSTEM "dsssldb.dtd" [
<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
]>
<set>
<setinfo>
<title>A Plain Driver</title>
<external-specification id="docbook" document="docbook.dsl">
</setinfo>
<book use=docbook><title>SSB</title>
<chapter><title>Titlepages</title>
<para>some info</para>
<programlisting>
(define %generate-set-titlepage% #f)
(define %generate-book-titlepage% #f<co id=foo>)
(define %generate-part-titlepage% #f)
(define %generate-reference-titlepage% #f)
(define %generate-article-titlepage% #f)
</programlisting>
<para>some info</para>
</chapter>
<chapter><title>TOCs</title>
<para>some info</para>
<programlisting>
(define %generate-set-toc% #f)
(define %generate-book-toc% #f)
(define %generate-part-toc% #f)
(define %generate-reference-toc% #f)
(define %generate-article-toc% #f)

(define %generate-book-lot-list% '())
</programlisting>
</chapter>
</book>
</set>

Basically, the DSSSL code is the concatenation of PROGRAMLISTINGs.

Too Cool!


                                        Cheers,
                                          norm

Norman Walsh <ndw@nwalsh.com>      | There's 2 possible outcomes: If
http://nwalsh.com/                 | the result confirms the
                                   | hypothesis, then you've made a
                                   | measurement. If the result is
                                   | contrary to the hypothesis, then
                                   | you've made a discovery.--Enrico
                                   | Fermi

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