Version references in documentation

[Derek Atkins]

Geert Janssens <janssens-geert at telenet.be> writes:

[snip]
> Hmm, in my opinion this would not be as useful as using parameter entities to 
> define current-stable, next-stable and so on.

Seconded.

I think it's useful to parameterize the version numbers.
I do NOT think it's useful to parameterize sections of the DOCS.  The
docs should be for a single version, and the docs will get
tagged/branched to support history (i.e. previous versions),
as Geert says:

> 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

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available