Re: Calling all documentation writers

[Brent Smith <gnome nextreality net>]

Danilo Šegan wrote:
> Hi Brent,
>
> Yesterday at 21:11, Brent Smith wrote:
>
>
> > I can do this.  I've actually been meaning to for awhile, but
> > I wasn't sure how this affected translations since I wasn't sure
> > if we could port the existing ones over or not.
>
>
> Great, you are welcome to do it as well ;)
>
> As for translations, porting is a bit more complicated, and since
> we've not been shipping them anyway (check that Makefile.am has only
> SUBDIRS = C), there are no regressions. 
>
> Of course, since translations are Sun work, they probably are based on
> a single revision of original, and it should be easier to find which
> one is it (instead of looking for different originals for each
> translation).  Basic description on migrating them is on 
>
>   http://live.gnome.org/GnomeDocUtilsTranslationMigration

Ok.  A large portion of the content is already translated, so I think
it would be good to port over what we can.  That being said, it
seems like it might be more trouble than it's worth.

> > I would also like to consolidate the licenses from gnome-desktop,
>
>
> The only problem I see with this is if user guide is not installed,
> and other applications license texts (gnome-desktop also contains
> libdesktop for reading .desktop files, I think, so it's always
> installed).

Good point.  But does anyone install gnome-desktop and not
gnome-user-docs?

> > any updates you make shouldn't affect the port to gnome-doc-utils
> > (unless you are touching Makefiles, etc..), so don't worry about it
> > :-)
>
>
> If we keep the current layout of user-guide.xml (i.e. including using
> <!ENTITY SYSTEM ...>), xml2po is going to produce single big XML file
> for translations instead.
>
> The solution is to switch to xinclude, and put all additional files to
> DOC_INCLUDES.  So, this would mean changing all the &gos... references
> to <include...>s, but it seems it's all in user-guide.xml.
>
> Example of how this looks is in gnome-doc-utils/doc/gnome-doc-make/ :

Familiar with that document, I just ported the instructions on the wiki
to it ;-)

Ok, I will try to move things over to xinclude.  The only problem that
this creates is an extra step for validation since you have to  process
the guide with xmllint --xinclude before performing the validation step.

for example, validation for each case:

with xinclude:
xmllint --xinclude gnome-doc-make.xml | xmllint --noout --valid -

with system entities:
xmllint --noout --valid gnome-doc-make.xml


--
Brent Smith <gnome nextreality net>
IRC: smitten