From owner-freebsd-doc Thu Jul 2 01:51:54 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id BAA09430 for freebsd-doc-outgoing; Thu, 2 Jul 1998 01:51:54 -0700 (PDT) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from tyree.iii.co.uk (tyree.iii.co.uk [195.89.149.230]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id BAA09413 for ; Thu, 2 Jul 1998 01:51:45 -0700 (PDT) (envelope-from nik@iii.co.uk) From: nik@iii.co.uk Received: from carrig.strand.iii.co.uk (carrig.strand.iii.co.uk [192.168.7.25]) by tyree.iii.co.uk (8.8.8/8.8.8) with ESMTP id JAA20908; Thu, 2 Jul 1998 09:51:43 +0100 (BST) Received: (from nik@localhost) by carrig.strand.iii.co.uk (8.8.8/8.8.7) id JAA10395; Thu, 2 Jul 1998 09:51:36 +0100 (BST) Message-ID: <19980702095135.22477@iii.co.uk> Date: Thu, 2 Jul 1998 09:51:36 +0100 To: Chuck Robey Cc: doc@FreeBSD.ORG Subject: Using stylesheets with SGML (was Re: cvs commit: doc/sgml freebsd.dsl) References: <199806300852.BAA13364@freefall.freebsd.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.85e In-Reply-To: ; from Chuck Robey on Wed, Jul 01, 1998 at 06:03:53PM -0400 Organization: interactive investor Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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 This is the first paragraph. This is a para in a legal notice. 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 Paul Prescod's DSSSL tutorial James Clark's list of DSSSL related links Daniel Germa'n's introduction to DSSSL 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