Docbook-based Literate Programming

DocBook-Based Literate Programming 1.4 Mark Wroth April 12, 2001 This document, and the literate programming system described herein, is c 2001 by Mark Wroth. Permission is granted for the reproduction, copyright use, and modification of this system provided that • No charge is made for the use of this system. A nominal charge for reproduction of the media on which the system is provided may be levied, however. • The complete literate programming source of the system is made available to the user. • Modifications of this system are clearly identified as derivative works. Provision must be made to identify the author of the changes, and to provide error reports to the modifier rather than the original author. Works created using this system (as opposed to modifications of this system itself) are subject to whatever copyright or use provisions may be imposed by the authors of those works; the use of this system shall not be the basis for any change or modification of the rights of such authors. The author of this system, in permitting its general use, makes no warranty of its suitability for any purpose nor any guarantee of its correctness. In other words, you are welcome to use this system, but you do so at your own risk. 1 Contents 1 Functional Description 1.1 Purpose of the Functional Description . . . . . . . . . . . . . . . 1.2 Project References . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4 5 2 System Summary 2.1 Background . . . . . . . . . . . . . . . 2.1.1 Literate Programming . . . . . 2.1.2 SGML and XML . . . . . . . . 2.1.3 DocBook . . . . . . . . . . . . 2.2 Objectives . . . . . . . . . . . . . . . . 2.3 Existing Methods and Procedures . . . 2.4 Proposed Methods and Procedures . . 2.4.1 Summary of Improvements . . 2.4.2 Summary of Impacts . . . . . . 2.4.3 Assumptions and Constraints . 2.5 Detailed Characteristics . . . . . . . . 2.6 Design Considerations . . . . . . . . . 2.6.1 System Description . . . . . . . 2.6.2 System Functions . . . . . . . . 2.6.3 Flexibility . . . . . . . . . . . . 2.7 Environment . . . . . . . . . . . . . . 2.7.1 Equipment Environment . . . . 2.7.2 Support Software Environment 2.8 System Development Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6 6 7 8 8 8 9 9 10 10 10 10 10 10 11 11 11 11 12 3 DTD Implementation 3.1 Purpose . . . . . . . . . . . . . . . 3.2 Top Level Organization . . . . . . 3.3 The programlisting Customization 3.3.1 The ‘literalchar’ element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 13 13 13 14 . . . . . . . . 4 SGML Tangle 16 4.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.2 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2 4.3 Implementation Notes . . . . . . . . . . . . . . . . . . . . . . . . 5 SGML Weave 5.1 Purpose . . . . . . . . . . . . . . . . . . . 5.2 Minimum DocBook Customization Layer 5.3 The l