Date: Thu, 2 Jul 1998 09:51:36 +0100 From: nik@iii.co.uk To: Chuck Robey <chuckr@glue.umd.edu> Cc: doc@FreeBSD.ORG Subject: Using stylesheets with SGML (was Re: cvs commit: doc/sgml freebsd.dsl) Message-ID: <19980702095135.22477@iii.co.uk> In-Reply-To: <Pine.BSF.3.96.980701175749.303J-100000@localhost>; from Chuck Robey on Wed, Jul 01, 1998 at 06:03:53PM -0400 References: <199806300852.BAA13364@freefall.freebsd.org> <Pine.BSF.3.96.980701175749.303J-100000@localhost>
next in thread | previous in thread | raw e-mail | index | archive | help
Chuck,
I'm cc'ing this to -doc, mostly because I want to make sure that discussions
like this get archived. There are also bits and pieces I'm not 100% sure
about, and a wider audience for review can't hurt.
On Wed, Jul 01, 1998 at 06:03:53PM -0400, Chuck Robey wrote:
> Nik, can I ask you a question about this? I'm a longtime user of groff,
> along with the mm macros and tbl (and very occaisonally some of the
> other tools) but I've put off switching to anything sgml based for one
> simple reason: lack of control over precise font point size and font
> name. Everything else my heart desires is already available, but then I
> have to follow someone else's choices on font characteristics, and with
> my professors often _requiring_ certain fonts and sizes, this eliminates
> snything sgml based from working for me.
There's nothing stopping you. The SGML approach is (generally) to markup
for content, and put all the logic for converting that content to another
format (RTF, HTML, whatever) in to a stylesheets.
Stylesheets are written in DSSSL (Document Style Semantics and
Specification Language) a very Lisp-ish sort of language.
Suppose you want things marked up as paragraphs (with the 'para' element)
to be rendered in a 12 point font. However, paragraphs inside a legalnotice
should be marked up in 8 point text.
In your SGML document you might write something like
<para>This is the first paragraph.</para>
<legalnotice>
<para>This is a para in a legal notice.</para>
</legalnotice>
Note that there's no specification of fonts, sizes, weights, justification
(quadding) or anything else.
Then, in your DSSSL stylesheet you would include the following fragment,
; By default, paragraphs should be in 12 point type
(element para (make-paragraph font-size: 12pt))
; However, paragraphs that are immediately inside a legalnotice
; should be rendered in 8 point type
(element legalnotice para (make-paragraph font-size: 8pt))
This is sufficient to specify that paragraphs should then be rendered
in a 12 point font by the 'backend converter', unless they're inside
'legalnotice', in which case 8 point should be used. One of the backend
converters used by the Doc. Project is Jade, which can read SGML source,
a DSSSL stylesheet, and then produce RTF format text (it can also do
Word .doc format and DTD to DTD transformations, which is how we convert
text written in the DocBook DTD to the HTML DTD).
If you have two different stylesheets for the same DTD then you can use
them to produce two different looking copies of the same text.
We're fortunate that Norm Walsh's Modular DocBook stylesheets are
relatively easy to customise. If they weren't, I (or someone else) would
probably be writing a FreeBSD DocBook stylesheet. As it is we can use the
published 'knobs' plus a few hacks (I hope) to get what we need. The
alternative would be to write our own DSSSL stylesheet, something that I'm
not yet capable of doing.
You say "professors" earlier on, so I assume this is for research work
of some kind.
You may not find the DocBook DTD to be too useful, as it's heavily
orientated towards producing technical manuals. I imagine (but can't
confirm) that DTDs exist for theses and other acadamic documents. After
finding an appropriate DTD you would then need to find (or write) a
DSSSL stylesheet for that DTD, so that something like Jade can then
convert it into formatted text.
> Is there any likelihood that such options could ever be put into the
> FreeBSD stylesheet, even as an addendum (that could be specifically
> eliminated from anything put into FreeBSD documentation)?
It's a possiblity. I need to explore Norm Walsh's stylesheet some more,
and work out what can and can't be done easily. I don't know how simple
it is (for example) to tweak the formatting settings for one element
without affecting any others). I expect to be able to get back to Norm
with a wishlist sometime in the next few weeks.
> I don't want to force you guys to have to put up with idiots submitting
> docs in 5 point fonts,
That won't happen. DocBook doesn't include any mechanism to force a
particular font size (or colour, or weight, or font name. . .) that's all
handled by the stylesheet.
In fact, I intend to experiment (a little later down the line) with
several different stylesheets for the HTML output, producing HTML targetted
at different browsers. One stylesheet might markup filenames in a monospace
font, another one might mark them up in the regular font but in purple
(I use that just as an example).
Some handy references for SGML and DSSSL are
<URL:http://itrc.uwaterloo.ca/~papresco/dsssl/tutorial.html>;
Paul Prescod's DSSSL tutorial
<URL:http://www.jclark.com/dsssl/>;
James Clark's list of DSSSL related links
<URL:http://csg.uwaterloo.ca/~dmg/dsssl/tutorial/tutorial.html>;
Daniel Germa'n's introduction to DSSSL
<URL:http://www.sil.org/sgml/sgml.html>;
SGML / XML home page, a comprehensive listing of related resources
N
--
Work: nik@iii.co.uk | FreeBSD + Perl + Apache
Rest: nik@nothing-going-on.demon.co.uk | Remind me again why we need
Play: nik@freebsd.org | Microsoft?
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19980702095135.22477>