Date: Tue, 4 Jul 2000 18:13:22 +0000 From: Nik Clayton <nik@freebsd.org> To: papowell@astart.com, doc@freebsd.org Subject: Re: Images in the documentation Message-ID: <20000704181322.A380@kilt.nothing-going-on.org> In-Reply-To: <200007021750.KAA04760@h4.private>; from papowell@astart.com on Sun, Jul 02, 2000 at 10:50:04AM -0700 References: <200007021750.KAA04760@h4.private>
next in thread | previous in thread | raw e-mail | index | archive | help
Patrick, I've put doc@freebsd.org back on the to: line, so this goes in to the archives. On Sun, Jul 02, 2000 at 10:50:04AM -0700, papowell@astart.com wrote: > > I had thought that we were pretty much in agreement that SVG was the way to > > go. Then I talked to Patrick at Usenix, who was vociferously in favour of > > EPS. > > > > Patrick, this is your cue to talk about why EPS would be a better format to > > use than SVG. From my point of view SVG is a better bet because it's > > XML based. This makes it easy to write an application to manipulate the > > data using any of the XML libraries out there -- in particular, Perl and > > (I believe) Python have good XML support. Here's a very small fragment of > > SVG: > > <aside> > I just dug some numbers up for a documentation project > I did a couple of months ago: > > Tools used: Tex, PSFig, Perl, Corel Draw, PaintShop Pro, > + a bunch of snazzy tools for editting scripts. We'll have some of the same. The difference is that we're not mandating particular tools, just particular output formats. On the SVG front, if people want to use commercial software then I know that Corel Draw and Adobe Illustrator both have SVG import/export filters. . . > Time taken to set up all of the tools: > 4 (four) working days. Right. And remember- these were > 'expert' level people + 2 'newbies' who had to do a lot of > RTFM. That'll probably be about the same amount of effort that I'll be putting in to do it. Keep in mind that the ports collection automates a lot of the setup for people. > Time taken to produce the first 'template document' that had > a single example of all the text and figures we were going > to use: 6 (six) working days. (Did I mention the Prozac > for the newbies?) Ours probably won't need to be that complex. > Major problems: file conversions, I think a combination of sketch for the svg2ps code, and the NetPBM utilities for everything else. I believe the NetPBM stuff *doesn't* need Ghostscript installed, which is a big win compared to ImageMagick. > setting up automatic conversion scripts, make(1). > and figuring out ways to update illustrations > which used screen dumps. How do you mean? > Discovered that there were no way to automate the screen dumps > easily, hired a trained monkey to document how to update the > illustrations and then had them do the illustrations (remember to > put Prozac in trained monkey's Orange Juice BEFORE you tell him that you > changed the title on the screen for all 30 of the screen dumps you > use). Screen dumps aren't going to be that much hassle for us, I suspect. Partly because we're not going to use a great deal of them (certainly not in the early days anyway), and partly because they're so easy to generate on FreeBSD. As for standards, that just requires a chapter in the Primer, which I, or someone else, will have to write. We'll need a common look for X screenshots (same window manager, colour scheme, that sort of thing) and maximum image widths that we want, but that's about it. Certainly for a volunteer project anyway. > I hate the idea of Yet Another Graphics Descrition Language and Tool. New output format does not imply new tools. As I say, the commercial packages are gaining support for it, and Sketch can import EPS and write SVG, so people can go on using the same EPS generating tools they always have been. The eps-converted-to-svg probably won't be as easy to manipulate programmatically as something that was generated in an SVG aware tool, which is unfortunate, but there's no much we can do about that. > The only way that I see that this would be better is if there was a way to > leverage this: > > a) Make it easier to automate the process of getting illustrations. > (Screen Dumps! Hatums Screen Dumps! Bad! Evil! Cause you cannot > modify text easily. For text mode screen dumps you can -- they'll be a 4000 byte dump of the screen memory, where each pair of a bytes is the ASCII code and the colour code respectively. Editing these after they've been produced is relatively simple. For those wondering why we'd do screendumps in text mode -- I want to preseve the colours and general look and feel. A non-graphic version of the text can still be included (and will be, and probably be automatically generated), but the colour version gives a bit more impact, looks more professional, and probably communicates more to the reader as well. For graphics dumps (shots of X windows, that sort of thing) this will be a problem. Fortunately, we won't have many of these to contend with, I think. > b) Make it easier to automate the process of generating documents from > templates!!! > > Currently, for b) I do the following: > > 1. Generate the document using Corel or PSFig, and then produce > EPS. > > 2. Edit the PostScript, and replace fixed text strings with > macros (actually, I sometimes do this first) of the form: > @@name@@ (this probably came from some TeX stuff) > > 3. Have a 'name file' and Perl Script that expands the macros > in the file, replacing them with the real text. Can you give me a simple example of a document that you do this with. Or do you mean "screenshot" when you say "documents"? SVG should make this a doddle, as the format as easily parseable. N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery 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?20000704181322.A380>