From owner-freebsd-doc Mon Jun 26 2:13:57 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 AC18F37BCE1; Mon, 26 Jun 2000 02:13:43 -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 IAA88197; Mon, 26 Jun 2000 08:25:29 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id TAA00508; Sun, 25 Jun 2000 19:50:51 GMT (envelope-from nik) Date: Sun, 25 Jun 2000 19:50:51 +0000 From: Nik Clayton 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> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2i Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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: Path for incoming e-mail (POP3) 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