[GNC] Documentation changes needed

[Frank H. Ellenberger]

Hi Phil,

before I start: it seems the mail server rejected your mail because of
the for it unknown attachment. Perhaps Derek will comment on that later.

Thunderbird did not display your attachment. I had to trick it to
display it in LibreOffice.

David is right, just register your wiki account and start improving the
page. In case of doubt we can revert it. ;-)

As a "technician" I usually do not touch the user written sections 1-4
of the page.

Perhaps we should for now add a link to
https://github.com/Gnucash/gnucash-docs/blob/maint/README
at the beginning. Some points may still be better explained there.

More inline …

Am 11.05.22 um 17:30 schrieb Phillip Duff:
> HI,
> 
> Looks like I might need some help here as well as offering a rewrite for the ‘How to change documentation in GNUCash, which I find difficult, confusing and overly technical when the audience is documenters who may well not be developers.
> 
> It has taken me a whole afternoon to unravel what to do and I have rewritten much of it to completely simplify it and convert it into ’These are the steps you need to take;, type documentation. It is attached. If someone can look at it (it isn’t complete, because as below, I am stuck) and advise me if this is what they consider to be an improvement (note I have deliberately left out some stuff to keep it simple and instructive rather than explanatory).
> 
> Some examples + where I am currently stuck.
> 
> OK, Install Git, no problem.  
> 
> (Needs to have added here for Mac users that if you install XTools, you already have both Git and make (which ic buried further down, too late). We should simply recommend that Xtools is installed, whether it is 4Gb is irrelevant in today’s world generally, and we should move away from command line wherever possible for documenters.
> 
> Clone it, no problem.  (Can be easily done using Tools, so I have added it).
> Create the directory structures, no problem (This is then repeated on the ‘Initialising build environment page, so eliminate the repeat).
> 
> Now it gets interesting and very confusing. The page on make is pretty confusing.

We should reorder it from bottom-up to top-down.

> You need CMake to create the directory structures inside build, but there is no mention of that this needs to be downloaded.

Right, should be mentioned before.

> After this we are now positioned to change the documentation , as far as I can see, so I would continue with the documenting of this with a clear set of the instructions needed as documenters only want to know what in Git they need without wading through the Git pages to work it out.

The wiki page Git is terrible. Better link "An Introduction to Git",
which did not exist, when this page was created.

> For the Mac at least, CMake has a user interface, but for some reason the author wants to bring everything back to command line level, so the Make interface should be referenced. Not sure about Linux, so we can leave the command line in for that.

But to reduce redundancy I would suggest to create a separate page for
XCode specifics. As I am no Mac user, I don't know its content. Perhaps
there are already a few similar pages in
https://wiki.gnucash.org/wiki/Category:IDE.

Later Mac users can link it from other occurrences
https://wiki.gnucash.org/wiki/index.php?search=XCode&title=Special%3ASearch&go=Seite


Linux distributions also often have a meta package "[C/C++] Developement
Tools" which should today include Git, Cmake, …

It is often faster to copy the command frome the wiki onto your command
line than describing In IDE x click here and there, but in y use foo and
bar instead. And not everybody knows every environment.

> Except that when I run Cmake pointing to the src and build directories and enabling Mobi, I get errors.
> 
> Can’t find fop, you will be unable to generate pdf files.

Right, they use the same fo interim format like pdf.

> CMake Error in guide/C/CMakeLists.txt:
> The custom command generating
> 
> /Users/philduff/Documents/gnucash-build/share/gnome/help/gnucash-guide/C/fdl-appendix.xml
> 
> is attached to multiple targets:
> 
> C-gnucash-guide-check
> C-gnucash-guide-ghelp
> C-gnucash-guide-html
> C-gnucash-guide-epub
> 
> but none of these is a common dependency of the other(s). This is not
> allowed by the Xcode "new build system”.
> 
> Note that I set the environment to Xtools since it is installed and this seemed like a reasonable assumption.
> Any help ??

AFAIK nobody has tested the Xcode "new build system”. Perhaps John
knows, if it is easily adapted.

> Cheers Phil

Ceers
Frank