[docs] xmldocs - docelic modified 2 files

[Davor Ocelic]

> > It is now possible to output docs for up to a specified version.
> > That is, you can generate docs for 5.0.0 release, for 5.2.0 release, or
> >   for development branch.
> > 
> > To do this, run: TARGET_RELEASE="--last 5.2.0" make refxmls
> 
> That's very nice, Davor. So we can keep adding new docs for development,
> but still release docs for a release version, all without having to create 
> CVS branches of the docs, right?

Uhm, Yes and No... 

a) Yes:
What this makes is it stops processing cache files (generated by
bin/stattree) when the target release is processed.

This has the effect of producing all autogenerated output exactly
for the version targetted, and not for later versions. Typically
you'd use this to stop at last release and avoid cvs-head.
Then all source contexts and other autogenerated data should exactly
match one's installation of a specific release.

b) No:
However, this only works for autogenerated parts of XML - 
the descriptions and parameter lists that you write manually are
unfortunately not release-specific and will always reflect
cvs-head (if we keep up with documenting).

The "No" part can be solved in 2 ways:
I) I can add version specifier to format of files, roughly like:

__DESCRIPTION__5.2.0
Normal description
__END__

__DESCRIPTION__5.3.0
To-be stuff.
__END__

This could work but has very unfortunate side effect of 
breaking the section text into "a bunch of small unconnected
bits" because you can only append to existing text this way,
and not modify the shape of an existing sentence or paragraph
(and it would add additional requirements on the order of
sections in the file).

II) Possible good solution is:
Since we have support for XML profiling ("conditional text") that
we already use for distribution-specific (red hat, debian, ...)
documentation and inclusion of online examples, we can use this
existing feature of XML, roughly like:

<para>
	Tag xyz does this, this and that.
	<phrase revision='5.3.0'>If ImageMagick is installed,
	the tag can also do _something else_.</phrase>
</para>

<para>
	<arg choice='plain'>makesize</arg> option accepts format
	<phrase revision='!5.3.0'>
		AxB
	</phrase>
	<phrase revision='5.3.0'>
		[Ax[B]|xB][!@$%><], which covers all possible
		specifications supported by the Mogrify command
		itself.
	</phrase>.
</para>

(The "!<release>" syntax is not directly accessible in DocBook XML
but I think it's easy to add).