> -----Original Message----- > From: Geert Janssens [mailto:geert.gnuc...@kobaltwit.be] > Sent: Tuesday, 17 January 2017 10:14 PM > To: Chris Good <chris.g...@ozemail.com.au> > Cc: GnuCash Developers <gnucash-devel@gnucash.org> > Subject: Re: Document Update Instructions have been revised > > 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
Hi Geert, Thanks for reviewing my work and adding extra suggestions. I really enjoy learning more from your insights. I like to know, at least generally, 'why', as well as 'how'. I totally agree your suggestions would be helpful to new documenters. I'm a little concerned that the bulk of this page could be a little off-putting. However, I think it is better to have too much info than not enough. I would like to point out that your suggestions are mostly changes to things other people wrote. :-) Originally, I myself started to try to modify the documentation on Windows but soon thought it was not possible (or at least too difficult), and changed to Linux. People who are not familiar with Linux and virtual machines would probably like more guidance on this. I have since found that xmllint.exe & xsltproc.exe are in c:\strawberry\c\bin so that may help. Maybe an msys (or cygwin?) environment is not needed. I know practically nothing about msys or cygwin. If anyone else can add anything about updating the documentation on Windows or Mac, I'd like to hear it. Re the various translations: I only speak 1 language, English (Australian) fluently, and some will argue about that, so it has never really mattered to me, but... Is it true that the non-English versions of the documentation are translations of the English documentation? If so, is this 'policy' or just how it has worked out? I could imaging that different translations could have totally unique sections to cater for localisations. I agree it should be made clearer that it is only necessary to build and install a development version of GnuCash (programs) if one needs to test context help for features that are only in a more recent version than already installed. That section has always been confusing to me. 'Step 2 Git Clone' links to info about using pull requests instead of patches. I'll add similar references to the start of ' Step 15 Prepare your Patch'. Regards, Chris Good
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
