DSSSL Documentation Project
DSSSL Handbook Outline
This is the outline for a proposed DSSSL handbook. The only portions being worked on at present are the Flow Object Class Reference and, intermittently, the Glossary.
Offers to oversee the project, contributions of sections or subsections (marked up to DocBook 3.0), offers to contribute, or suggestions for improvement are actively solicited. Please send any contributions or suggestions for improvement to firstname.lastname@example.org.
Purpose of this book
To cover aspects of DSSSL well enough that people can do useful work. The book starts with introductions to DSSSL, has a reference section to help you out when you need to know something about the formalities, and has a “Real World DSSSL” section covering how to approach using DSSSL, how to organise your stylesheet, and how to achieve the output you want.
Who it is written for
This is primarily a book for newcomers to DSSSL, but it should be generally useful.
|0.3||The DSSSL Documentation Project|
Where to find other DSSSL resources
James Clark’s DSSSL page contains pointers to resources
Where to find introductions to SGML
Gary Simon’s discussion of SGML in “Using Text Encoding to Represent Linguistic Data” for pointers to online stuff; your local bookstore
PART 1 - INTRODUCING DSSSL
Beginners start here. This is the introduction to DSSSL, DSSSL concepts, and the mechanics of doing something with DSSSL.
|1.||INTRODUCTION - WHAT DSSSL IS ABOUT|
Possible future directions
Extensions for xml-style
REALLY SIMPLE EXAMPLE
Starting at the level of “hello, world”. Starting with “hello, world” is either de rigeur or it’s objectionable because it perpetuates the most overused example in the history of computing, or maybe it’s a bit of both.
|3.||OVERVIEW OF DSSSL|
|3.3.3||Flow Object trees|
|4.||A CRASH-COURSE IN SCHEME|
|5.||SIMPLE STYLESHEET EXAMPLES|
|6.||MORE COMPLEX STYLESHEET EXAMPLES|
PART 2 - REFERENCE SECTION
This is where you go to look something up to help you out of a bind with the nitty-gritty of using DSSSL. The next part, Real World DSSSL, is where you go for help in getting results using DSSSL.
HOW TO READ AND USE THE DSSSL STANDARD DOCUMENT
|8.||DSSSL SYNTAX SUMMARY|
|9.||STYLE SHEET SYNTAX|
|10.||EXPRESSION LANGUAGE REFERENCE|
|11.||TRANSFORMATION LANGUAGE REFERENCE|
|12.||STANDARD DOCUMENT QUERY LANGUAGE REFERENCE|
|13.||STYLE SPECIFICATION MODEL|
This should include a table showing what flow object classes or procedures depend upon each feature.
External procedures and declared characteristics
What this means, how to specify an external procedure or declare a characteristic, and how to reference them in a stylesheet
The character model in all its glory
|14.||STYLE LANGUAGE REFERENCE|
|15.||FLOW OBJECT CLASS REFERENCE|
|16.||SPECIFIC TOOL (JADE) EXTENSIONS|
Summary of the purpose and status of XSL, where to get up to date information
PART 3 - REAL WORLD DSSSL
Not the world’s best title, but this part provides help in getting results using DSSSL.
Analyzing the DTD
|19.3||Transformation in the style language|
DSSSL FOR VISUAL APPEARANCE
Another catchy title that needs changing. This chapter covers how to achieve using DSSSL the objects you’re used to seeing on a page or screen.
Pages, Headers and Footers
How to define a page, how to create a header or footer using simple-page-sequence, (theoretical) discussion of page-sequence and column-set-sequence, how (using Jade) to reset page numbers, etc.
How to create numbered, alphabetic, and bulleted lists, how to creat definition lists
Grateful reference to Anders Berglund’s CALS table module, how to turn non-table markup into tables using the table-related flow object classes
|20.4||Figures and Graphics|
|20.6||Contents and Indexing|
|20.7||Anchors and Links|
|20.10||Stuff in the margin|
|20.11||Characters, fonts, and character effects|
|21.||USING JADE’S SGML BACKEND|
EXAMPLE STYLE SHEETS
One or more complete stylesheets, presumably for a publicly available DTD (probably the DTD used for the Handbook). This would be most useful if it or they can be used as running examples throughout the book and it is possible to reference into these stylesheets.
|B||COMPARISON OF DSSSL AND OTHER MECHANISMS|
"Man"-style instructions for how to run the available DSSSL tools
Sending Glossary Requests
- Send glossary requests to email@example.com.
- Use the subject line “Glossary request”, and in the body of the message list just the requests, one per line, as in the following example:
To: firstname.lastname@example.org Subject: Glossary request kendot spread sosofo R4RS
Sending Glossary Entries
- Send glossary entries to email@example.com.
- Use the subject line “Glossary entry”. In the body of the message include the SGML for one or more entries marked up using DocBook 3.0 as shown in the following example:
<!DOCTYPE glossary PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> <glossary> <glossentry id="gloss-kendot"> <glossterm>kendot <revhistory> <revision> <revnumber>1.0</revnumber> <date>19970620</date> <authorinitials>Tony Graham firstname.lastname@example.org</authorinitials> </revision> </revhistory> </glossterm> <glossdef> <para>Emphasizing mark used in Japanese typography</para> <glossseealso otherterm="gloss-emphasizing-mark"> </glossdef> </glossentry> <glossentry> <glossterm>kendot scoring</glossterm> <glosssee otherterm="gloss-kendot"> </glossentry> </glossary>
- Include your name and email address in the <authorinitials> element
- Glossary entries should have an ID that is “gloss-” prefixed to the term, with any spaces in the term replaced by hyphens, e.g. “gloss-kendot”
- You can include more than one glossary entry in a single mail message
- Use the “OtherTerm” attribute in <GlossSee> and <GlossSeeAlso> for other terms you want to reference, even if you don’t know if there is an entry for that term. If there are any broken links when I put together the SGML, I’ll just create an empty entry and add the term to the request list.
- Graphics should be in TIFF or EPS formats only. Text in graphics should be 10pt Arial wherever possible.