[RFC] Image filename conventions

[Tommy Reynolds]

Hello, ya'll!

Some folk have their document images in a "figs/" subdirectory tree
under the document directory.  Large documents may have additional
"figs/part1" style subdirectories, too.

The lack of a formal filenaming scheme makes selectively copying
files awkward.  Below is our current convention:

	<filename>-<locale>.<ext>

such as "watermark-ru.png".  Simple, eh?

The problem is that some filenames use the "-" minus sign to separate
words in the filename:

	this-is-my-picture.png

Is "picture" part of the filename or the language designation?  It is
difficult for a shell script to decode this just by looking at the
filename.

I propose a file naming scheme to simplify the selective copying of
files.  This will help reduce the complexity of the RPM packaging
tools.

Only three formal rules are needed:

1)  The minus sign "-" may not be used as part of the filename
    component.

1)  The minus sign only introduces the locale for the file.

1)  Filenames without a locale component are considered language
    neutral.

With these conventions in place:

	"foo.png" is a language-neutral graphic.

	"foo-it.png" is a graphic with Italian text.

	"foo-bar.png" is not permitted usage.

Comments? Alternatives? Bribes?

Cheers

[Karsten Wade]

On Fri, 2005-12-09 at 16:09 -0600, Tommy Reynolds wrote:

>  I propose a file naming scheme to simplify the selective copying of
>  files.  This will help reduce the complexity of the RPM packaging
>  tools.
>  
>  Only three formal rules are needed:
>  
>  1)  The minus sign "-" may not be used as part of the filename
>      component. 
We could use other separators, e.g. the fabulous_underbar_for_this-en ?

>  1)  The minus sign only introduces the locale for the file.
>  
>  1)  Filenames without a locale component are considered language
>      neutral.
>  
>  With these conventions in place:
>  
>  	"foo.png" is a language-neutral graphic.
>  
>  	"foo-it.png" is a graphic with Italian text.
>  
>  	"foo-bar.png" is not permitted usage.
>  
>  Comments? Alternatives? Bribes? 
Looks good to me.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
Content Services                          Fedora Documentation Project
http://www.redhat.com/docs   http://fedoraproject.org/wiki/DocsProject

[Tommy Reynolds]

Uttered Karsten Wade <kwade(a)redhat.com&gt;, spake thus:

>  > Only three formal rules are needed:
>  > 1)  The minus sign "-" may not be used as part of the filename
>  >     component.
>  We could use other separators, e.g. the fabulous_underbar_for_this-en ? 
Certainly.
 
>  > 1)  The minus sign only introduces the locale for the file.
>  > 1)  Filenames without a locale component are considered language 
Three rules numbered #1?  Proves I should not work when I should be
sleeping.

>  > Comments? Alternatives? Bribes?
>  Looks good to me. 
Good.  If no one objects in a day or two, I'll make the change.

Cheers

[James Laska]

Greetings,

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?

Thanks,
James Laska

On Fri, 2005-12-09 at 16:09 -0600, Tommy Reynolds wrote:
>  Hello, ya'll!
>  
>  Some folk have their document images in a "figs/" subdirectory tree
>  under the document directory.  Large documents may have additional
>  "figs/part1" style subdirectories, too.
>  
>  The lack of a formal filenaming scheme makes selectively copying
>  files awkward.  Below is our current convention:
>  
>  	<filename>-<locale>.<ext>
>  
>  such as "watermark-ru.png".  Simple, eh?
>  
>  The problem is that some filenames use the "-" minus sign to separate
>  words in the filename:
>  
>  	this-is-my-picture.png
>  
>  Is "picture" part of the filename or the language designation?  It is
>  difficult for a shell script to decode this just by looking at the
>  filename.
>  
>  I propose a file naming scheme to simplify the selective copying of
>  files.  This will help reduce the complexity of the RPM packaging
>  tools.
>  
>  Only three formal rules are needed:
>  
>  1)  The minus sign "-" may not be used as part of the filename
>      component.
>  
>  1)  The minus sign only introduces the locale for the file.
>  
>  1)  Filenames without a locale component are considered language
>      neutral.
>  
>  With these conventions in place:
>  
>  	"foo.png" is a language-neutral graphic.
>  
>  	"foo-it.png" is a graphic with Italian text.
>  
>  	"foo-bar.png" is not permitted usage.
>  
>  Comments? Alternatives? Bribes?
>  
>  Cheers
>  -- 
>  fedora-docs-list mailing list
>  fedora-docs-list(a)redhat.com
>  To unsubscribe: 
>  https://www.redhat.com/mailman/listinfo/fedora-docs-list

[Tommy Reynolds]

Uttered James Laska <jlaska(a)redhat.com&gt;, 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

[James Laska]

On Mon, 2005-12-12 at 10:40 -0600, Tommy Reynolds wrote:
>  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.  
Yeah I like this ... saves you from pulling in other lang specific
images.

>  This gets very complicated really fast.  I hate complicated: 
Couldn't agree more.  We'll need to have the images/figures section of
the documentation-guide (2.5. Diagrams and Image) updated to reflect
these rules.  

Are you already set on this format?  Something about leaving the image
filenames open to the authors appeals to me.  What are your thoughts on
a directory structure instead of filename rules?  Perhaps something
like:

  figs/$lang/
  figs/common/  or just figs/

If we force all images to be in the figs/ subdirectory, this will make
it difficult for large documents to remain sane.

Thoughts/concerns?

Thanks,
James Laska
-- 
==========================================
 James Laska         -- jlaska(a)redhat.com
 Quality Engineering -- Red Hat, Inc.
==========================================

[Tommy Reynolds]

Uttered James Laska <jlaska(a)redhat.com&gt;, spake thus:

>  Are you already set on this format?  Something about leaving the
> image
>  filenames open to the authors appeals to me.  What are your thoughts on
>  a directory structure instead of filename rules?  Perhaps something
>  like:
>    figs/$lang/
>    figs/common/  or just figs/
>  If we force all images to be in the figs/ subdirectory, this will make
>  it difficult for large documents to remain sane.
>  Thoughts/concerns? 
Yeah, I'm going to be pretty stubborn on the filename convention.
This format mimics the decision we have for the various document
translations themselves.  We have a base filename ${DOCBASE}, a
${LANG} specifier, and an .xml extention.  However, with the images
we also allow generic images to omit the ${LANG} component.

I don't really care how the "figs/" files are organized.  Make a flat
directory, make tons of subdirs, it all works for me.  The
"docs-common/bin/copy-figs" script traverses the "figs/" tree,
copying individual files into corresponding subdirs in the
destination.

I have added the "figs/Manifest-${LANG}" file, mentioned in my
previous email, so you can name your files using whatever convention
you choose; the cost is having to explicity identify the files.

Sound OK, now?

[James Laska]

On Mon, 2005-12-12 at 17:41 -0600, Tommy Reynolds wrote:
>  I have added the "figs/Manifest-${LANG}" file, mentioned in
> my
>  previous email, so you can name your files using whatever convention
>  you choose; the cost is having to explicity identify the files.
>  
>  Sound OK, now?  
It should also be noted in the documentation-guide (or where ever these
rules land), that you need to include the directories in the Manifest as
well.  My apologies if that was stated already.

Additionally, should the Manifest-${LANG} should reference images
relative to the figs/ directory?  For example

$ cat figs/Manifest-en
ch-intro/one.png
ch-asdf/foo/bar.png
ch-qwerty/one.png

If that is the case then ../docs-common/bin/copy-figs is able to find
them, however for htmlchunked output it places those files in ...

${DOCBASE}-${LANG}/ch-intro/one.png
${DOCBASE}-${LANG}/ch-asdf/foo/bar.png
${DOCBASE}-${LANG}/ch-qwerty/one.png

Which now differs from how html-nochunks refers to these images:

figs/ch-intro/one.png
figs/ch-asdf/foo/bar.png
figs/ch-qwerty/one.png

For consistency, and working figures, I would suggest that copy-figs put
all figures under a figs/ directory within ${DOCBASE}-${LANG} (like
${DOCBASE}-${LANG}/figs)?  Am I using the Manifest-${LANG} incorrectly?

Thanks,
James

-- 
==========================================
 James Laska         -- jlaska(a)redhat.com
 Quality Engineering -- Red Hat, Inc.
==========================================

[Tommy Reynolds]

Uttered James Laska <jlaska(a)redhat.com&gt;, spake thus:

>  > Sound OK, now? 
>  It should also be noted in the documentation-guide (or where ever these
>  rules land), that you need to include the directories in the Manifest as
>  well.  My apologies if that was stated already. 
Good idea.  That was not explicitly stated.  I've just checked in a
new version of "copy-figs" that will create path components
automatically if the Manifest-${LANG} omits the directories.
 
>  Additionally, should the Manifest-${LANG} should reference images
>  relative to the figs/ directory?  For example 
Ah, caught another one!

I've fixed the copy-figs script to work correctly now.  A
Manifest-${LANG} file should look like this:

	$ find figs -print >/tmp/foo && mv /tmp/foo figs/Manifest-${LANG}
	$ cat figs/Manifest-${LANG}
	figs/a/b/c/d/e/foo.png
	figs/Fedora_Desktop.eps
	figs/Fedora_Desktop.png

It's OK, but no longer necessary, if directories are listed in the 
Manifest-${LANG} file.  Also "*/CVS/*" and "*/.svn/*" entries
continue to be ignored.

Cheers!

[James Laska]

Greetings,

Now that's response time ;)  Works great on my end, thanks very much for
your help!

Thanks,
James


On Tue, 2005-12-13 at 10:52 -0600, Tommy Reynolds wrote:
>  Uttered James Laska <jlaska(a)redhat.com&gt;, spake thus:
>  
>  > > Sound OK, now? 
>  > It should also be noted in the documentation-guide (or where ever these
>  > rules land), that you need to include the directories in the Manifest as
>  > well.  My apologies if that was stated already.
>  
>  Good idea.  That was not explicitly stated.  I've just checked in a
>  new version of "copy-figs" that will create path components
>  automatically if the Manifest-${LANG} omits the directories.
>   
>  > Additionally, should the Manifest-${LANG} should reference images
>  > relative to the figs/ directory?  For example
>  
>  Ah, caught another one!
>  
>  I've fixed the copy-figs script to work correctly now.  A
>  Manifest-${LANG} file should look like this:
>  
>  	$ find figs -print >/tmp/foo && mv /tmp/foo figs/Manifest-${LANG}
>  	$ cat figs/Manifest-${LANG}
>  	figs/a/b/c/d/e/foo.png
>  	figs/Fedora_Desktop.eps
>  	figs/Fedora_Desktop.png
>  
>  It's OK, but no longer necessary, if directories are listed in the 
>  Manifest-${LANG} file.  Also "*/CVS/*" and "*/.svn/*" entries
>  continue to be ignored.
>  
>  Cheers!
>  -- 
>  fedora-docs-list mailing list
>  fedora-docs-list(a)redhat.com
>  To unsubscribe: 
>  https://www.redhat.com/mailman/listinfo/fedora-docs-list 
-- 
==========================================
 James Laska         -- jlaska(a)redhat.com
 Quality Engineering -- Red Hat, Inc.
==========================================