From owner-freebsd-doc Fri Feb 27 08:03:44 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id IAA09455 for freebsd-doc-outgoing; Fri, 27 Feb 1998 08:03:44 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from tyree.iii.co.uk ([195.89.149.230]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id IAA09449 for ; Fri, 27 Feb 1998 08:03:41 -0800 (PST) (envelope-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 PAA23731 for ; Fri, 27 Feb 1998 15:57:58 GMT Received: (from nik@localhost) by carrig.strand.iii.co.uk (8.8.7/8.8.7) id QAA03629 for doc@freebsd.org; Fri, 27 Feb 1998 16:03:17 GMT Message-ID: <19980227123035.20115@iii.co.uk> Date: Fri, 27 Feb 1998 12:30:36 +0000 From: nik@iii.co.uk To: Greg Lehey Subject: Re: Graphics in handbook? What do you think? References: <19980227114815.57531@freebie.lemis.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.85e In-Reply-To: <19980227114815.57531@freebie.lemis.com>; from Greg Lehey on Fri, Feb 27, 1998 at 11:48:15AM +1030 Organization: interactive investor Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Fri, Feb 27, 1998 at 11:48:15AM +1030, Greg Lehey wrote: > I've written a web page which is designed to be part of the online > handbook--thus my question about SGML a couple of days ago. It > contains some pretty extensive .gif screen shots, which is fine for a > web page, but may not be so easy to handle in a printed medium. > > Take a look at http://www.lemis.com/handbook/what-to-download.html and > tell me what you think of the idea. If there are technical problems > with putting the screen shots in the handbook, we should discuss them > too. Interesting question. What DTD is this marked up to? I've just had a look at the DocBook 3.0 DTD and the Screenshot element seems to be appropriate in this instance. It would be used like this: A view of the directory listing for ftp.freebsd.org/pub/ As you say, this may not be too handy when producing multiple output format versions of the handbook. The trick is to use "marked sections" to delimit data, and turn on or off the processing of a particular marked section depending on the desired output format. For example, two marked sections look like this: As you can see, the text will be included or ignored. This isn't that useful, because you need to be able to selectively turn on or off the processing of particular sections, so. . . . . . define a couple of 'entities', call them 'html' and 'postscript' for example. The value of these entities will be set by the processing application to either "INCLUDE" or "IGNORE". You can then write marked sections like this: A view of the directory listing for ftp.freebsd.org/pub/ ]]> ]]> When this section is processed for HTML output, set the 'html' entity to 'INCLUDE' and the 'postscript' entity to 'IGNORE', and the first 'graphic' element will be included. Reverse those two when you're producing the postscript version and the EPS file will be used instead of the GIF file. As a minimum, we probably need four such entities, organised into two pairs. % html - HTML % postscript - Postscript output % textonly - Don't include inline graphics % graphics - Include inline graphics When one of a pair is set to INCLUDE, the other is set to IGNORE. The entire section above could then be rewritten as: When you go the FreeBSD ftp site you will see a directory listing similar to this one. A view of the directory listing for ftp.freebsd.org/pub/ ]]> ]]> ]]> As you can see, marked sections provide an "IF...THEN" ability, not an "IF...THEN...ELSE" ability. OK, so that explains (possibly in more detail than you need) the technical issues involved. As to your question of whether or not we should. . . IMHO, there are times when a picture is worth a thousand words (or more). Look at which is Gisle Aas' illustrated guide to Perl internals for an example. So I don't have a problem with including images in the handbook (and FAQ come to that) as long as text only equivalents are provided in some form. Of course, John Fieber and Peter da Silva have the final say. 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