[RFC] Image filename conventions

[Tommy Reynolds]

Uttered James Laska <jlaska at redhat.com>, spake thus:

> What is the benefit of enforcing image filename conventions?  We label
> our images many times by where they exist in the document
> (figs/ch/section-name.<ext>).  I could even see a format such as
> "figs/<lang>/<some-dir-hierarchy>.<ext>".  Is the main goal to simplify
> the spec file %files?

AFAICT, there are two classes of figures: language-specific and
language-neutral.  All neutral files should always be copied into the
HTML chunk tree, or placed into the RPM.  Only the matching
language-specific files should be copied to the HTML chunk tree or to
the RPM, because image files can get disproportionately large.

When copying the "figs/" hierarchy, we need a batch method to
determine the appropriateness of each file.  My proposed grammar of:

<anthing_but_dashes>-<lang>.<ext> is considered language-specific

<anything_but_dashes>.<ext> is considered language-neutral

is unambiguous, so a batch method can easily select the proper files.
Selection is simple to understand.

I considered relaxing the <anything_but_dashes> part to be
<anything>, but that requires heuristics to guess about the content.
The "Makefile" knows the allowed set of ${LANGUAGES}, so the batch
copy process could compare the final after-the-dash component against
that list: language matches get copied, rejects don't.  What about
the file name "i-am-a-file.jpg"?  It doesn't match any known
language, so we could assume it is language-neutral and copy it, but
then we have to deal with a filename such as "eng-to-ru.png", where
no component has anything to do with the language context.

This gets very complicated really fast.  I hate complicated:

	Beauty is Elegance,
	Elegance is Simplicity,
	Simplicity is Not-Much-To-Remember,
	Not-Much-To-Remember is Perfection,
	Perfection is Beauty.

Sorry, I couldn't help it ;-)

Anyway, the suggested naming convention applies only to image files.

If the convention causes an unreasonable burden, you can use the
"Manifest-${LANG}" feature I just added.  Create the file
"figs/Manifest-${LANG}" whose content is the pathname, relative to
"figs/" of *every* file to be copied.  No filtering is done against
the names read from "figs/Manifest-${LANG}", although CVS files are
still ignored.

Create the "figs/Manifest-${LANG}" file like this:

	$ cd figs
	$ rm -f Manifest-${LANG}
	$ find * -print >/tmp/Manifest-${LANG}
	$ mv /tmp/Manifest-${LANG} Manifest-${LANG}

or any comparable way that puts relative pathnames into the file.
You want:

	foo.png

and not:

	figs/foo.png
	-or-
	/path/to/doc/figs/foo.png

Hope this helps.

Cheers
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20051212/085589e8/attachment.sig>