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 _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel