Date: Fri, 27 Feb 1998 12:30:36 +0000 From: nik@iii.co.uk To: Greg Lehey <grog@lemis.com> Subject: Re: Graphics in handbook? What do you think? Message-ID: <19980227123035.20115@iii.co.uk> In-Reply-To: <19980227114815.57531@freebie.lemis.com>; from Greg Lehey on Fri, Feb 27, 1998 at 11:48:15AM %2B1030 References: <19980227114815.57531@freebie.lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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: <screenshot> <screeninfo>A view of the directory listing for ftp.freebsd.org/pub/ </screeninfo> <graphic format="gif" fileref="screenshot.gif"></graphic> </screenshot> 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: <![ IGNORE [ This text will be ignored ]]> <![ INCLUDE [ But this text will be included ]]> 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: <screenshot> <screeninfo>A view of the directory listing for ftp.freebsd.org/pub/ </screeninfo> <![ %html; [ <graphic format="gif" fileref="screenshot.gif"></graphic> ]]> <![ %postscript; [ <graphic format="eps" fileref="screenshot.eps"></graphic> ]]> </screenshot> 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: <para>When you go the FreeBSD ftp site you will see a directory listing similar to this one.</para> <!-- If this the text only version then don't display any screen shots, instead, use the Screen element to show what they would see -> <![ %textonly; [ <screen> Nov 19 04:27 text/plain README 696 bytes Feb 17 05:33 text/plain UPLOADS.TXT 2Kb Feb 25 10:11 Directory archive-info Jan 14 07:17 Directory bin </screen> ]]> <!-- This is a version of the handbook with inline graphics, possibly HTML, possibly postscript. Show a screen shot, and select the format of the graphic to use as appropriate for the medium --> <![ %graphics; [ <screenshot> <screeninfo>A view of the directory listing for ftp.freebsd.org/pub/ </screeninfo> <![ %html; [ <graphic format="gif" fileref="screenshot.gif"></graphic> ]]> <![ %postscript; [ <graphic format="eps" fileref="screenshot.eps"></graphic> ]]> </screenshot> ]]> 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 <URL:http://home.sol.no/~aas/perl/guts/>; 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19980227123035.20115>