[GNC-dev] Documentation update problems

[David Cousens]

John, Geert, Adrien, David

Thanks for all the prespectives. I will attempt a restructure of the Building Gnucash page and its derivatives, trying
to push as much information back to the generic Linux level as I can from the BuildingUbuntu 16.04 pages. I have no
experience of building on Windows or MacOS X so I will definitely leave that to someone else. I'll start with Geert's
comments as an overall plan and try to address the rest of your comments. I can set VMs up for the other distros so I
can check them out a bit better

With the dependencies I compiled as complete a list as I was able to from my own experience and other users experiences
when a lot of people were building v3.0-3.2 as it wasn't available from the distros. . I had a clean Linux Mint install
at the time I did that so I captured a few that are usually already installed once you get a bit of other software on
board. Some distros do seem to use slightly different names for some libraries and headers so perhaps a warning to check
your own distros naming using the equivalent of apt-cache search. I'll do as much as I can from the online documentation
for the other distros. I  I'll have a closer look and if I can get away perhaps with a subsitute "dnf" and "yum"and
"apt" for apt-get as a note along the lines if compiling on xxx subsitute yyy for apt-get in the following.

I was reluctant originally to touch the Fedora and Gentoo sections as I hadn't had any experience of them. It would
appear the major difference is likely to be the name of the package manager on the various distros. I appreciate there
are sometimes also slight differences in the interpretation of the Linux File Heirarchy as well.

I'll come back when I've done a restructure and get everyone to check it out

David Cousens


On Wed, 2018-09-19 at 10:34 +0200, Geert Janssens wrote:
> Op dinsdag 18 september 2018 10:19:02 CEST schreef David Cousens:
> > John, David, Frank
> > 
> > I wonder at the value of the Build Tools page as a separate orphan entity
> > given the more detailed instructions given in the Building Gnucash page.
> > There is a fairly good example of dupllcation with it and the following for
> > the Gnucash progarm build.
> > 
> > https://wiki.gnucash.org/wiki/Building
> > 
> > and the breakout from it for recent Ubuntu versions
> > 
> > https://wiki.gnucash.org/wiki/BuildUbuntu16.04
> > 
> > The main building page is a massive tome. I did start breaking out some
> > parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
> > ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). The Build
> > Tools page may be a logical breakout from there with some of the detail in
> > the first page cut into it. There is also a short summary recipe for
> > building the Docs at the end of the BuildUbuntu16.04 page which lacks detail
> > but does work on Ubuntu and most linux distros. It has no details about the
> > dependencies in it though.
> > 
> > Would a page on building the docs be better as a breakout from the main
> > building Gnucash page perhaps with a shared section on the build tools
> > referenced from both. For build instructions I ususaly find the recipe the
> > most useful bit with explantions of the specific tools as breakouts. If you
> > need the information and background you can follow the links. If you only do
> > a build occasionally you follow the recipe.  I.e only read the manual when
> > you have to.
> > 
> 
> I wrote my previous mail before looking at the wiki pages you mentioned and I 
> agree the current structuring is not guiding the reader to a successful build 
> in the most efficient way.
> 
> The page could be restructured to be more recipe like with links to pages/
> sections with more details.
> 
> The general structure of the general instructions is good, but I would not 
> differentiate between general and distro specific variants. Building on 
> Windows and OS X do merit a separate mention as their build instructions are 
> very different. For linux distros as written before the only difference is how 
> to get the necessary dependencies set up. It would make sense to add a section 
> for this right before getting the gnucash sources.
> 
> And as I suggested, the info should be very short on the main building page, 
> with a link to a more detailed page specifically about setting up dependencies 
> per distro or distro group.
> 
> The configuring gnucash section could be reduced to indicating what to do for 
> gnucash 2.6.x and what to do for gnucash 3.x by default. More details on 
> configuration options could go to a more detailed page on configuring gnucash.
> 
> In my opinion the mention of the compiler is not relevant here. If it should 
> be mentioned it should be in the section or details on setting up 
> dependencies.
> 
> All the sections under OS/Distro specific information (other than the two 
> links to OS X and Windows should IMO be removed from this page. The details of 
> setting up dependencies can be grouped on the new page for this, the build 
> instructions themselves are identical for all distros. Oh and anything that's 
> valid only for obsolete distros should be removed completely. The oldest 
> supported Ubuntu distro is 14.04 LTS, for Fedora that's 27. I would not 
> mention distro releases unless it's necessary to differentiate. In that case I 
> would write the default instructions for the current distro (omitting distro 
> release info) and exceptional instructions for the older distro(s) (adding for 
> which distro this matters). That will make it easier to maintain the 
> documentation in the future:
> - if nothing changes when a new disto release comes out, documentation doesn't 
> need to be updated
> - if a distro becomes obsolete, it's easy to find and remove all info that's 
> no longer relevant.
> 
> Geert
> 
>