Re: What's down, doc? Standartize - standartize ...

[Shaun McCance <shaunm gnome org>]

On Tue, 2006-02-28 at 14:37 +0200, Alexander Shopov wrote:
> Hi guys,
> 
> This will certainly wait for the months after the March release and 
> subversion migration but I *do* think that we should all press to get 
> the structure for the documentation of packages heavily standardized.
> The maintenance of translation of documentation is several times more 
> time intensive for me to do than maintenance of interface translations.

Certainly.  I didn't expect that we'd have a perfect solution
right off the bat.  But we got infrastructure in place that we
can actually use.  Issues will crop up, and we'll address them.

So, now we have issues.  Danilo and I can soon get hacking for
2.16, wherein we'll have the desktop 100% documented and have
that documentation 100% translated. :)

> 1. We have po* subdirectories to hold the translations. We should expect 
> the help to always be in help*

I agree.  In fact, I generally push for a two-directory layout,
like so:

/sound-juicer/help/sound-juicer/C/sound-juicer.xml

Note the extra sound-juicer directory.  This allows you to add
new documents without having to move stuff around in your source
tree.  When we switch to subversion after 2.14, we'll be better
able to change directory names.

A longer-term goal is to get developer documentation also using
xml2po for translations.  Developer docs have traditionally been
put under the "doc" or "docs" subdirectory.  I think using help
for user help and docs for developer docs is perfectly fine.

Another related issue is what to do about ChangeLog files.  With
po files for interface translations, we have a single po directory,
and a ChangeLog for that directory.  Translators can just prepend
to po/ChangeLog, and maintainers can easily check this file when
compiling release notes.

With documentation, we have basically four choices:

1) /module/ChangeLog
2) /module/help/ChangeLog
3) /module/help/docname/ChangeLog
4) /module/help/docname/lang/ChangeLog

Choice (1) has all sorts of problems.  It means we all have to
do full checkouts for documentation and translations, and it
increases the chance of conflicts.

Choice (4) creates lots of ChangeLog files, making it hader for
maintainers to track changes when compiling release notes.  This
will inevitably lead to credits being omitted from release notes.

I consider (2) and (3) the only feasible options.  When a module
isn't following my recommended two-level layout, they degenerate
into exactly the same thing.  Translators would need to check out
one directory above their language, but they'll need to do that
anyway to merge new messages from the DocBook.  Both the writers
and the translators would put messages in the common ChangeLog
for the document, and we'd train maintainers to look at that for
release notes.

Anybody else have different thoughts on that?

> 2. The way a new language is included should be standard. I generally 
> could live with the configure.in/configure.ac dichotomy, but today I had 
> to include the translation of gcalctool - writing Makefiles.am is not 
> the translators task.

For the documentation translations, it's currently necessary to
modify the DOC_LINGUAS file in the Makefile.am of the document's
top directory.  I don't particularly see Makefile.am edits as any
harder than configure.in edits.  But then, we've already had at
least case of a translation not being included because of this.

One option is just to train translators on this.  They already
need to know how to work with xml2po instead of intltool for
documentation translation.  We really do try to make things as
easy as possible for translators, and to let them use a single
tool chain, but sometimes it's just necessary for them to learn
something new.

We could attempt to use the ALL_LINGUAS from configure.in, but
we'll have problems.  We might be able to solve those problems,
but they will arise.  Notably, what do you do if a language has
provided interface translations but not documentation translations?
Far from being uncommon, it's actually the norm right now.  So do
we just do the subset of ALL_LINGUAS for which there exists a po
file in the appropriate language directory?  That's possible, but
implicit rules tend to create problem.  We have at least two cases
where we have implicit rules in gnome-doc-utils.make (the .omf.in
and figures/*.png), and both have caused problems already.

I'm open to suggestions.

> 3. I do believe that the xml2po translation has begun, but we should 
> have it finished in all modules. Making xml2po is one thing, but then 
> re-merging the po to xml becomes tasking and error prone (at least for me).

Danilo and I have talked about ways of doing xml2po merges and
such without using make.  We understand that haveing to configure
a package just to do translations is a big hassle.  This will get
addressed for 2.16.

> 4. We have got to have a way easily to check the validity of 
> translation. msgfmt is fine for po-files, Emacs serves me fine there, 
> but getting things right for the documentation is more error prone. 
> Partial XMl conformance is difficult even for trivial cases of 
> "partial", especially if you do things in your head.

Sure.  Currently, running 'make check' will validate all the
translations (including the source) against the DTD.  This is
really really nice.  It means distcheck will fail if people
don't write correct DocBook.  I've even considered doing the
validation on just 'make all', but I'd want to do some sort
of timestamping hackery so it doesn't constantly happen.

But you want to validate the contents of your messages without
having to configure and make and all that crap.  And that makes
perfect sense, particularly given what I said to (3).  I'm not
sure how well we can manage validity checks, particularly given
stuff like <placeholder-$/> elements.  But well-formedness checks
are certainly doable.  Danilo?

--
Shaun