From owner-freebsd-doc Tue May 23 17:53:31 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 411DE37B855 for ; Tue, 23 May 2000 17:53:15 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id BAA52322; Wed, 24 May 2000 01:24:04 +0100 (BST) (envelope-from nik) Date: Wed, 24 May 2000 01:24:04 +0100 From: Nik Clayton To: papowell@astart.com Cc: doc@freebsd.org Subject: Re: Help? With DocBook + LPRng documentation Message-ID: <20000524012403.G42626@catkin.nothing-going-on.org> References: <200005232152.OAA18784@h4.private> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0.1i In-Reply-To: <200005232152.OAA18784@h4.private>; from papowell@astart.com on Tue, May 23, 2000 at 02:52:40PM -0700 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Patrick, [ I've cc'd this to -doc mailing list -- there's some stuff in the latter half of this message that I haven't really talked about on that list yet, and I'd like to get some feedback on it from others as well ]. Sorry for sounding slightly distant in my last e-mail. I've just remembered that we met at least years FreeBSDCon. I'm glad to see that something came of our conversation :-) On Tue, May 23, 2000 at 02:52:40PM -0700, papowell@astart.com wrote: > Thanks. I just read the stuff about illustrations and it > confirms my worst thoughts on this. > > You seem to have come to the same conclusion that I have: > each output format has a 'compatible' or 'desirable' input > format for illustrations and heaven help you if you want to > convert from one to the other. Yes and no. Actually converting from one image format to another is not too difficult. If you install the grapics/ImageMagick port, it includes a program called "convert". You can quite literally do convert _source_ _target_ to have it convert between several tens of different graphic formats. May main concern with mandating ImageMagick for the Documentation Project is that it's big. Something like the NetPBM utilities are smaller, but require a little more effort to string together. Instead of writing convert image.jpeg image.gif in your Makefiles (or shell scripts) you have to write something like djpeg image.jpeg | ppmquant -fs 256 | ppmtogif > image.gif Eminently feasible, it's just a trade off between ease of use vs. size. The only other problem is that producing PS and PDF output from the same source requires a small SGML hack, until the stylesheets we use get a little smarter. The other issue is "What should be the native format for vector graphics?". I first suggested EPS, several other people suggesting SVG from the W3C, which looks promising. The only stumbling block at the moment is the lack of a small utility that can convert SVG files to EPS (we already have a large program that can do that, called Sketch, but again, I don't want to add another big program to the set required to build the documentation if I can at all avoid it). > In addition, I note carefully that you also took at tiny > peek at 'language dependencies' in illustrations. > > Here is what I have done in the past for this stuff. > > I had a 'illustrations' directory that had all of the illustrations > in files with various suffixes. Note that the names of the illustrations > were NOT according to their position, but according to what I wanted. Not so good from our point of view -- people are going to be downloading this from all over the 'net. I'd like to make sure they have a way of easily saying "don't send me the Japanese images" (for example), to keep the amount of data transferred down. With the tools we're using at the moment (primarily CVSup) that means that organising things into different directories, rather than one big images directory, is probably better. > Now, you may wonder why I had a preprocessor. The answer is > AUTOMATIC CONVERSION. I had a set of EPS stuff -> .gif and a set > of .gif -> eps. Also, I had the convention that I would name > the language dependent ones 'illustration.fr.xx' so I could get the > right stuff. OK. This is (I think) really solving two problems. The first problem is, how do you use the right format image for the right output format. The second is how do you share images between languages. DocBook already lets us solve the first. You can write in your document, and the stylesheets are supposed to do the right thing, depending on what output format you're using. The example above will use the PNG file when generating HTML, and the EPS file when generating Postscript. As I say, it's a bug in the stylesheets that this doesn't work properly with PDF as well, requiring a kludge to work around -- it's not an inherent limitation in DocBook. I think we can solve the second problem (that of sharing images) by designating one language (probably English) as containing the master images. Consider a hypothetical article called "foo" in the English tree. This article uses three images. Two of these are not language specific (they contain no text), called generic-1.png and generic-2.png. The other one does contain English text, called specific.png. The Makefile for this document might look something like this: [...] IMAGES= generic-1.png IMAGES+= generic-2.png IMAGES+= specific.png [...] Then, some hypothetical Makefile magic in (the as yet unwritten) doc.images.mk is used to convert these images to the required formats, depending on the FORMATS variable. The logic is something like: If ${FORMATS} is anything except 'ps' or 'rtf' then do nothing special. If ${FORMATS} is 'ps' then convert them to EPS, if ${FORMATS} is 'rtf' then convert them to BMP. Now, suppose that the Japanese team have translated this article, but they have not yet created a translated version of specific.png. The Makefile for the Japanese document would contain the same three IMAGES lines. However, we need some additional glue that checks to see whether or not the image exists in the current directory. If it doesn't exist then it checks to see if the image exists in the parallel English directory. If it does then the Makefile can create a symlink to it, if it doesn't then an error can be flagged. This means that initially, the Japanese document will build with an English illustration. However, IMHO, a Japanese document with an English illustration is better than no Japanese document at all. Later, when the translation teams have created a translated version of the image then can commit their own version of "specific.png", at which point the Makefiles will realise it exists, and use it in preference to the English version. None of the code to do this exists yet -- it's not rocket science, I'm just somewhat busy on other stuff. If anyone wants to pick up an editor and start coding, please do so. To forestall a possible suggestion of "Why not create a generic/ directory, at the same level as the en*/, ja*/, and other directories, and put the language neutral images in there?" I think that this would inevitably lead to a profusion of repository copies, either as images are first committed to a language specific directory, before needing to be moved to the generic directory, or vice-versa. I realise that the approach I've outlined above would also make the English language directories in the repository become a pre-requisite for building the other translations, and that this is a burden for the translation teams. I hope that the use of technologies such as CVSup's "refuse" files, which would allow the translation teams to only need to download a copy of the English images (without needing the associated SGML files, or other infrastructure) will be sufficient to mitigate this problem. Of course, suggestions for alternative methods are always welcome. 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