Version references in documentation
tbullock at nd.edu
Wed Aug 25 07:50:30 EDT 2010
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
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.
On 8/25/2010 1:59 AM, Yawar Amin wrote:
> 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?
More information about the gnucash-devel