Separate directories for each Language for Release notes (and other docs)

[Tommy Reynolds]

Uttered "Paul W. Frields" <stickster at gmail.com>, spake thus:

> As long as there's a way to share common files like figures under a
> common/ subdirectory we should be OK.  I'm sure Tommy will think about
> this and propose something logical.

Oh, foolish mortal!  I did think of this (check the archives), back
when we first started added the i18n build support.  The consensus at
the time was to have flat directories.  And so we do.

However, I never liked the idea.  I suppose having foo-en.xml and
foo-cz.xml in the same directory was appealing to visually compare
translations side-by-side, but it was not clear to me why this was
needed.  Must a translator slavishly make a foo-topicA-de.xml file
just because the original author made a foo-topicA-ru.xml file?
Anyway, I digress.

How about something like this, which is what I use for my own projects:

fedora-docs/
+-- docs-common/
|   +-- Makefile
|   +-- Makefile.common
|   +-- README
|   +-- bin/
|   |   +-- db2rpm-info*
|   |   +-- tidy-bowl*
|   |   +-- <snip>
|   |   +-- xmldiff*
|   |   +-- xmldiff.pl
|   |   +-- xmlformat*
|   |   \-- xmlformat-fdp.conf
|   +-- common/
|   |   +-- README
|   |   +-- <snip>
|   |   \-- opl.xml
|   +-- css/
|   |   +-- fedora-draft.css
|   |   \-- fedora-plain.css
|   +-- fedora-doc-common-0.1-cvs20051230.noarch.rpm
|   +-- images/
|   |   +-- Makefile
|   |   +-- <snip>
|   |   +-- watermark-en.png
|   |   \-- watermark-en.svg
|   +-- man/
|   |   \-- man1/
|   |       \-- tidy-bowl.1
|   +-- packaging/
|   |   +-- <snip>
|   |   \-- titlegrab.py*
|   +-- stylesheet-images/
|   |   +-- 1.eps
|   |   +-- <snip>
|   |   \-- warning.png
|   \-- xsl/
|       +-- html-common-relnotes.xsl
|       +-- <snip>
|       \-- redhat.xsl
\-- example-tutorial/
    +-- Makefile
    +-- common/
    |   +-- Makefile
    |   +-- bin/
    |   +-- figs/
    |   +-- src/
    |   \-- xml/
    \-- en/
        +-- Makefile
        +-- bin/
        +-- figs/
        +-- src/
        \-- xml/

Where:
	bin/	holds whatever scripts and such that need be run to
		generate dynamic content.
	figs/	holds language-specific diagrams and whatnot, such
		as SVG files converted to PNG by a bin/ script.
	src/	holds any raw code or snippets needed for the
		figures or examples.  I use this to make sure any 
		code-based screenshots actually work.
	xml/	Holds the XML files for the document.  Does not
		usually have subdirs, but they are not prohibited.

A set of recursive Makefile's tie all this together, so I can drive
everything from the top-level Makefile.

Now, most of this is overkill for FDP, but I believe the structure is
comprehensible, scalable, and most of all "sound".  Any subdir not
needed can simply be omitted.  More could be added.

Want to know how many documents have Hungarian translations?

	
	$ echo fedora-docs/*/hr | xargs -n1 | wc -l

Seriously, this would simplify the individual Makefile's even more than
what we currently have, because we could avoid all those silly Makefile
TEMPLATE constructs: they're elegant but not really readable.

I propose deferring this reorganization until we get the RPM
packaging stuff nailed down.  Then we can just change the paths
around a bit ;-)

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/20060107/9b6b3ef9/attachment.sig>