From owner-freebsd-doc Thu Jul 2 18:43:46 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id SAA15655 for freebsd-doc-outgoing; Thu, 2 Jul 1998 18:43:46 -0700 (PDT) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from picnic.mat.net (picnic.mat.net [206.246.122.117]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id SAA15635 for ; Thu, 2 Jul 1998 18:43:37 -0700 (PDT) (envelope-from chuckr@glue.umd.edu) Received: from localhost (chuckr@localhost) by picnic.mat.net (8.8.8/8.8.5) with SMTP id UAA15096; Thu, 2 Jul 1998 20:41:25 -0400 (EDT) Date: Thu, 2 Jul 1998 20:41:25 -0400 (EDT) From: Chuck Robey X-Sender: chuckr@localhost To: nik@iii.co.uk cc: doc@FreeBSD.ORG Subject: Re: Using stylesheets with SGML (was Re: cvs commit: doc/sgml freebsd.dsl) In-Reply-To: <19980702095135.22477@iii.co.uk> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Thu, 2 Jul 1998 nik@iii.co.uk wrote: > 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. I realize that I could change the stylesheet, but the goal was to be able to do it from the single document source sgml file, and not to have to include a modified stylesheet each time (so that it is like my present groff documents). I wanted to be able to include some kind of sgml markup in the base doc, that would send a parameter to the stylesheet. I'm not sure it's possible to go in that direction with the information, but it would make things extremely more workable. This would be something I would want to change on a doc by doc basis, and not just being able to have one personally-modified local stylesheet. I'm trying to get the functionality I presently have in groff (or that you get via LaTeX). > > 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? > > ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@glue.umd.edu | communications topic, C programming, and Unix. 213 Lakeside Drive Apt T-1 | Greenbelt, MD 20770 | I run Journey2 and picnic (FreeBSD-current) (301) 220-2114 | and jaunt (NetBSD). ----------------------------+----------------------------------------------- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message