Version references in documentation

[Geert Janssens]

On Wednesday 25 August 2010, Yawar Amin wrote:
> 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
> 
Hmm, in my opinion this would not be as useful as using parameter entities to 
define current-stable, next-stable and so on.

gnucash-docs' trunk is not meant to apply to all versions of GnuCash. It 
should only apply to the trunk version of GnuCash. Documentation releases are 
targeted at a specific GnuCash release. Each of these documentation releases 
will get its own tagged revision. So there's not really a need for 
conditionals based on the GnuCash release.

If documentation updates are offered specific to a tagged documentation 
release, that don't apply to the trunk version of the documentation, a 
documentation branch can be created holding these specific documentation 
updates. This branch can also be the basis for new documentation releases.

Perhaps an example will clear this up:
gnucash-docs trunk is currently targetted at gnucash (the code) trunk.
The documentation that goes with GnuCash 2.2.9 is tagged 2.2.
Suppose someone posts a change to the documentation, but this new 
documentation is only valid for GnuCash 2.2.9, and doesn't apply to the 
current development series. Then a branch should be made in svn for the 2.2 
documentation and the changes will be applied there. At some point, this 
branch will then be released (tagged) as version 2.2.1 for gnucash-docs.
Suppose then someone adds documentation that is relevant for both 2.2.9 and 
2.3.x/2.4. This should be added to trunk and from there on merged into the 2.2 
branch as well. This would lead to two separate documentation releases, 2.2.2 
(for the 2.2.x series) and 2.4.x when GnuCash 2.4 is eventually released.

So again, I'm not in favor of using parameter entity based conditionals in the 
documentation source. Svn itself will allow proper separation of 2.2.x and 
2.4.x documentation sources.

Geert