From owner-freebsd-doc  Tue Jul  4 11:51:41 2000
Delivered-To: freebsd-doc@freebsd.org
Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66])
	by hub.freebsd.org (Postfix) with ESMTP id B9B7A37B810
	for <doc@freebsd.org>; Tue,  4 Jul 2000 11:51:34 -0700 (PDT)
	(envelope-from nik@nothing-going-on.demon.co.uk)
Received: from kilt.nothing-going-on.org (kilt.nothing-going-on.org [192.168.1.18])
	by nothing-going-on.demon.co.uk (8.9.3/8.9.3) with ESMTP id TAA23343;
	Tue, 4 Jul 2000 19:30:13 +0100 (BST)
	(envelope-from nik@catkin.nothing-going-on.org)
Received: (from nik@localhost)
	by kilt.nothing-going-on.org (8.9.3/8.9.3) id SAA00705;
	Tue, 4 Jul 2000 18:13:22 GMT
	(envelope-from nik@catkin.nothing-going-on.org)
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>
References: <200007021750.KAA04760@h4.private>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.2i
In-Reply-To: <200007021750.KAA04760@h4.private>; from papowell@astart.com on Sun, Jul 02, 2000 at 10:50:04AM -0700
Organization: FreeBSD Project <URL:http://www.freebsd.org/>
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

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