Version references in documentation

[Tom Bullock]

  Hi Yawar,

Thank you for your reply and not-too-late offer of help.  Your idea 
sounds good to me and if the developers have no objection, I encourage 
you to begin implementing your suggestion.  As far as I know, I am the 
only one that is discussing working on the GC documentation (at least, 
other than an isolated patch).  The developers have more experience than 
I, including the documentation process.  So if Geert Janssens, John 
Ralls, or Derek give you the green light, do proceed.

For my part, the only documentation segment I am working on at the 
moment is the Guide Chapter 3.  Since I have to rebuild my patch and 
currently am away on vacation, if you were to start with Guide, Chapter 
3, when I return my rebuild of my patch would pickup your entity 
references and there should be little risk that my patch would cancel 
your work.

Since I am on vacation, I will be able to check email and lists only 
occasionally.  Please be guided by what the developers suggest, post 
your action here, and I can catch up as I can login online.

Thanks for your bringing a good idea (seems to me) to the documentation.

Tom

On 8/25/2010 1:59 AM, 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
>