[GNC-dev] GnuCash - documentation display disfunctional and sources

[Geert Janssens]

Op woensdag 11 april 2018 16:09:57 CEST schreef Stefan Mueller:
> Hallo,
> I the course of my researches in regard to *Import Map Editor* I've noticed
> that there are two branches of documentation, *stable
> <https://www.gnucash.org/docs/v3/>* and *git <https://cvs.gnucash.org/docs>*
> and that there are some lonely help docs. on *git*: 2.7. Daten importieren
> <https://cvs.gnucash.org/docs/de/gnucash-guide/basics-import1.html> what
> shall go into the official documentation.

What you are looking at are the html translation of our documentation. It's 
not the version managed documentation source though.

That is written in docbook format and stored here:
https://github.com/Gnucash/gnucash-docs/

The specific page is a relic of documentation that got removed from the 
documentation sources in 2015 by Mechtilde in this commit:
https://github.com/Gnucash/gnucash-docs/commit/31d724b34ceaa98d7aa29

The html page should not have been there anymore and is a heads up we should 
update our nightly documentation build to clean out obsolete files.

However in this case it's nice you found it and it triggers you to re-enable 
it.
> 
> In order to do so I would have to clone the documentation repository and
> reorder the html files and reset the links and commit it.

Not exactly. You'd have to translate the html pages back into docbook format 
and update them to reflect current stable. The importer (particularly the csv 
one) has changed since that documentation was written.

It's probably easier though to search for the original docbook source in git 
history and start from there.

I have quickly searched the current documentation sources and it appears there 
is no information on importing either in the English documentation. That's 
likely why it got removed from DE at some point as the English version is 
considered the primary documentation and the other languages are 'only' 
translations. (Though that may not necessarily be the right approach)

> Once I have finalized all that, I will notify the developer team of your
> changes, either by creating a pull request
> <https://wiki.gnucash.org/wiki/Git#Pull_Requests> (pulls my clone into
> master), or by creating and uploading a patch
> <https://wiki.gnucash.org/wiki/Preparing_A_Documentation_Patch>.

Indeed.

> That's it isn't it?
> One step is still unclear, how or by whom are the files moved from *git*
> <https://cvs.gnucash.org/docs> to *stable*
> <https://www.gnucash.org/docs/v3/>.
> 
Never. Both urls you specify are html renderings of the documentation sources, 
though they render different branches. These renderings are automatically 
generated from the true git sources (see link above).

The source git repo has two relevant branches: maint and master.
Whatever is committed to maint will appear in the rendering at https://
www.gnucash.org/docs/v3/ at the first new release after it got committed.
Whatever is committed to master will appear in the rendering at https://
cvs.gnucash.org/docs (though we normally use it's other alias https://
code.gnucash.org/docs)

In addition *all* commits that go into the maint branch will at some point get 
merged into master, and will hence appear in the rendering of that branch as 
well. We don't merge the other way around so master can contain documentation 
for features that are not yet in a stable gnucash release (though currently 
that's uncommon).

> In addition, I've noticed that the translated help is not pulled up when
> changing the language on gnucash.org
> <https://www.gnucash.org/viewdoc.phtml?doc=help>, although it is available:
> 
> GnuCash Documentation EN
> <https://www.gnucash.org/viewdoc.phtml?doc=help&lang=de_DE> àgnucash help EN
> <https://www.gnucash.org/docs/v3/C/gnucash-help/>
> GnuCash Documentation DE
> <https://www.gnucash.org/viewdoc.phtml?doc=help&lang=de_DE> àgnucash help EN
> <https://www.gnucash.org/docs/v3/C/gnucash-help/> although there is gnucash
> help DE <https://www.gnucash.org/docs/v3/de/gnucash-help/>
> GnuCash Documentation IT
> <https://www.gnucash.org/viewdoc.phtml?doc=help&lang=it_IT> àgnucash help EN
> <https://www.gnucash.org/docs/v3/C/gnucash-help/> although there is gnucash
> help IT <https://www.gnucash.org/docs/v3/it/gnucash-help/>
> 
> That is properly due to that the folder in .../docs
> <https://www.gnucash.org/docs> are not named according the format of Locale
> <https://en.wikipedia.org/wiki/Locale_(computer_software)>.
> 

Right. That should be aligned. I seem to remember we chose to remove the 
region code from the documentation directories at some point. We probably 
should do the same for the website's html, or alternatively make the 
documentation selection in viewdoc.phtml more intelligent and try with and 
without region code if there is one in the chosen language.

Regards,

Geert