Document Update Instructions have been revised

[Geert Janssens]

Op dinsdag 17 januari 2017 11:16:39 CET schreef Chris Good:
> Hi,
> 
> 
> 
> I've finished updating the wiki Document Update Instructions [1] to include
> instructions for using 'make' rather than xmllint and xsltproc directly.
> 
> Thank you very much Geert for all the info.
> 
> 
> 
> [1] http://wiki.gnucash.org/wiki/Documentation_Update_Instructions
> 
> 
> 
> Regards, Chris Good

Chris,

Thanks for improving our documentation on improving our documentation ;)

Seriously, I appreciate the effort you're spending here.

I'm proof reading what you have written and below follow some remarks:

* You are referring to the required use of make, which I like obviously as I 
suggested that myself. What is not clear in your documentation however is how 
to obtain make and the related tools. On linux this is usually obtained via 
the package manager. There is usually some kind of package group related to 
development that installs all the required dependencies in one go. On OS X I 
don't know how to get it. That's John's expertise although David T may know 
this by now as well... And on Windows it's probably even more complicated. TBH 
I never tried manually building the gnucash documentation on that platform, so 
I can't give precise instructions. It will likely involve installing an msys 
environment.

* Step 5 confuses me:
"Experienced developers instruct that you should focus first on the modules in 
either of these two directories (found in the step 1 downloaded files): 
gnucash-docs/help/C or gnucash-docs/guide/C. "
What do you mean by this ? The "C" directories contain the documentation in 
English. All other directories contain translations of these in other 
languages. As I see it there is no need to present this as some kind of 
mythical knowledge only understood by "Experienced developers".

* The next paragraph confuses me as well. How would opening each file reveal 
errors ? This is not really clear to me.

* A bit further you suggest to add a pair of comments around your changes to 
help translators. I would propose not to do that as I believe this is 
redundant information. This is what a version management system is used for. 
One can use the git history to see what has changed since the last time one 
has worked on the translation. There are graphical tools like gitk or the 
github website that help you visualize these changes.

* "If you are adding or deleting an xml file, for example adding a new chapter 
or appendix, you also need to update files [guide|help]/[language]/gnucash-
{guide|help}.xml and [guide|help]/[language]/Makefile.am. There is no need to 
update Makefile.in as this is generated by running autogen.sh."
Perhaps here it's best to more explicitly state autogen.sh and ../configure.sh 
should be re-run.

* There is a section on testing the documentation locally on linux. I have 
slightly modified it, because parts of it were outdated. And I'm considering 
whether we shouldn't simplify it even more. For now I have stated you can run 
this test with any version of gnucash higher than 2.6.0, with the restriction 
that yelp is installed and working. The text is not too clear about that 
second part, but that is what the "linux" restriction is actually all about. 
This does reduce the cases where a full build of a development version of 
gnucash is necessary IMO. It believe this is only necessary when you want to 
test context help for features that are only in a more recent version than you 
currently have. But this begs the question whether we really need gnucash at 
all in the other cases. Only yelp suffices as explained at the end of step 
11.3. Perhaps we should make that the preferred testing method and only 
propose linux tests in case new context help should be tested. What do you 
think ?

* Lastly you describe how to format a patch. While this is certainly one of 
the accepted methods, it may be interesting to document how to make a pull 
request as well.

That's it. Again, thanks for all the effort you spent on this so far!

Regards,

Geert