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