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

[Stefan Mueller]

thanks for the information. I might find the time to adapt the removed page
as it was very helpful to me and should return to the documentation, but
updated to new interface.

2018-04-11 19:06 GMT+02:00 Geert Janssens <geert.gnucash at kobaltwit.be>:

> 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
>
>
>