Version references in documentation

[Yawar Amin]

Hi,

On 2010-07-20, at 04:31, Geert Janssens wrote:

> [...]
> I think the idea was to have a set of documentation per release, but this 
> didn't work out for 2.2.
> 
> I'm not sure what the best way to deal with this is.

GnuCash version-dependent documentation changes could be handled with XML parameter entities. So if we maintain certain differences between 2.2.9 and 2.4.0 docs, we can encapsulate those changes in parameter entities that act kind of like #ifdef macros in C/C++. For example, let's say we have the following version-specific wording:

GC 2.2.9: In GnuCash 2.2.9, we do not have an easy way to delete saved custom reports from the reports menu.

GC 2.4.0: In GnuCash 2.4.0, we have an easy way to delete saved custom reports from reports menu, using the reports management dialog box.

We could manage it in the DocBook sources like so:

<!ENTITY % v229 "INCLUDE">
<!ENTITY % v240 "IGNORE">

...

In GnuCash
<![%v229;[2.2.9, we do not]]>
<![%v240;[2.4.0, we]]>
have an easy way to delete saved custom reports from the reports menu
<![%v240;[, using the reports management dialog box]]>.

And then to compile v2.4 docs instead of v2.2.9, we flip the INCLUDE and IGNORE directives in the entity definitions. It looks pretty ugly, but it can be made pretty darn automatic. I'll keep this in my work queue as well.

In the meantime, what's the best way to look for version-specific differences in the docs? Do a diff in the sources between revisions tagged 2.2 and 2.4, or something like that?

Regards,

Yawar

-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 194 bytes
Desc: This is a digitally signed message part
URL: <http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20100825/0df82f2a/attachment.bin>