Date: Sun, 25 Jun 2000 19:50:51 +0000 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Cc: dgl@bsdi.com, jim@cdrom.com, papowell@astart.com, wpaul@freebsd.org, ceren@magnesium.net, ryan@ryan.net, murray@bsdi.com Subject: Images in the documentation Message-ID: <20000625195051.B470@kilt.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
This is one of our top priority issues to resolve. There's a lot of
existing documentation that we could bring in to the tree if we have support
for images.
[ Because someone *always* complains when this is bought up -- NO, I am not
suggesting we remove existing text, or the ASCII art images when the
documentation is converted to a text-only medium. Images will be an
addition to the current documentation, not a replacement for some of it. ]
For example, Matt Dillon's VM article in DaemonNews a while back, or Archie
Cobb's discussion of Netgraph. Both of these are good examples of well
written, useful, technical articles, which we currently lack. They also
both rely on images to make it easier to put across certain concepts.
There is also a wealth of documentation written by others about FreeBSD on
other websites around the world. I'd like to bring these in to the tree
wherever possible as well -- if this means bringing on board the original
authors as committers (restricted to their own directory under -doc if
necessary) then I don't have a problem with that.
Currently, our lack of image support is a bottleneck preventing this, and I
want it removed ASAP.
We hashed out most of the issues in a thread on -doc started by me with
the subject "Including images in the documentation".
Most of the actual infrastructure concerns were resolved in that thread.
What wasn't resolved was the master format we would use for images in
the repository.
We had settled on PNG for bitmap images. As far as I'm aware, everybody
thinks that's a good choice.
We haven't settled on a vector format.
The two contenders seems to be EPS and SVG. EPS is more widely deployed,
and has more tools that can create it. SVG is on the W3C standards track,
is XML based, and probably makes it easier to translate text in images. We
also have command line tools (even if they do add a 6MB dependency to the
docproj tool chain) to convert SVG to EPS (I'm talking about
ports/graphics/sketch).
[ Newsflash: I've been reading the proceedings of the Freenix track at
Usenix, where a discussion of the GNOME Canvas model was presented. Turns
out the GNOME guys have another application that reads and writes SVG --
not that I'm suggesting we add GNOME as a dependency in docproj, but there
is now more than one free application out there supporting it.
Given the GNOME canvas technical model I also think it would be relatively
easy for someone to extend to add SVG as a native export format for it,
effectively allowing all GNOME applications that use the Canvas to
support SVG. ]
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:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG December 1999//EN"
"http://www.w3.org/Graphics/SVG/svg-19991203.dtd">;
<svg width="16cm" height="10cm" viewBox="1 2 17 12">
<rect style="fill: #ffffff" x="4" y="5.75" width="2.5" height="1"/>
<rect style="stroke-width: 0.001; stroke: #000000" x="4" y="5.75"
width="2.5" height="1"/>
<text style="fill: #000000; text-align: left; font-size: 0.3" x="7.5"
y="11.5">Path for incoming e-mail (POP3)</text>
</svg>
Whichever way you look at it, that's got to be easier to parse than EPS.
One way or another, I'd like this wrapped up within a fortnight or so. We
still have a few other related issues to discuss, like standards for image
sizes, fonts (and font sizes) to use in images, and so on, but these should
be fairly easy to do in parallel -- to kick things off, vector images should
assume a page width of US Letter or A4 (whichever is thinner), bitmap images
should, wherever possible, be no wider than 640 pixels.
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?20000625195051.B470>