Date: Wed, 24 May 2000 01:24:04 +0100 From: Nik Clayton <nik@freebsd.org> To: papowell@astart.com Cc: doc@freebsd.org Subject: Re: Help? With DocBook + LPRng documentation Message-ID: <20000524012403.G42626@catkin.nothing-going-on.org> In-Reply-To: <200005232152.OAA18784@h4.private>; from papowell@astart.com on Tue, May 23, 2000 at 02:52:40PM -0700 References: <200005232152.OAA18784@h4.private>
next in thread | previous in thread | raw e-mail | index | archive | help
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
<mediaobject>
<imageobject>
<imagedata fileref="image.png" format="png">
</imageobject>
<imageobject>
<imagedata fileref="image.eps" format="eps">
</imageobject>
</mediaobject>
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000524012403.G42626>