Re: [GNC-dev] Long Term Documentation Directions

[Adrien Monteleone]

David,

Count me in. (with a vote for Markdown)

Consider the idea of making the bulk of the current Help to be appendices of 
the new Manual. Many of those pages are simply reference lists of the menu 
entries.

Also, consider arranging the Manual by function rather than form. If GnuCash 
evolves to more closely follow the Gnome HIG, the UI is going to be very 
different in how it presents each function and where it appears. Arranging the 
manual this way will mesh nicely with that path and relieve the need to 
completely re-write it yet again.

Regards,
Adrien

> On Sep 8, 2018, at 10:48 AM, John Ralls  wrote:
> 
> 
> 
>> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel 
>>  wrote:
>> 
>> Hello,
>> 
>> As I have noted in another thread recently, I am finding the process of 
>> updating the various documentation pieces extremely challenging—due in large 
>> part to the fragmented nature of this documentation. Different contributors 
>> have placed information on similar topics in any of a number of official 
>> locations in the GnuCash documentation realm, making the update process a 
>> circular nightmare. 
>> 
>> This leads to variation in content, approach, and likelihood that a user is 
>> going to locate the full information on a given subject.
>> 
>> Rather than tackle each editorial task as if somehow this time it will be 
>> different, I would like to ask whether there would be support for a complete 
>> rewrite of the documentation. My idea would be to somehow merge all the 
>> content from the Guide and the Help into one huge file, and then establish a 
>> single Grand Unifying Manual that would provide users with a single source 
>> for help. Contextual help would be stripped back to only naming on screen 
>> functions, with references back to the GUM in all cases. The wiki would 
>> remain primarily for specific use cases and temporary issues. The FAQ would 
>> also point to the docs in most cases. Optionally, I would strip out the 
>> “Tutorial” aspect of the Tutorial and Concept Guide, as I think a solid 
>> Manual would obviate the need for this aspect (that, and the fact that most 
>> of the Tutorail sections are written in a “Hi, how are ya” folksie tone that 
>> I find inappropriate in formal documentation).
>> 
>> I do not make this suggestion lightly—I know the complexity and difficulty 
>> of such an endeavor. However, I increasingly find that the content of the 
>> Help and Guide are so inextricably enmeshed that any attempt to clean up one 
>> will have extreme impact on the other—and attempting to shepherd these 
>> changes through piecemeal is cumbersome at best. 
>> 
>> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 
>> 287. That’s over 500 pages of information—a good portion of which is 
>> duplicated across the docs. Any such rewrite would entail a HUGE effort, 
>> which is why I write this email: there is no way anyone would undertake this 
>> without knowing in advance whether the community would accept such a change 
>> at the outset.
> 
> I’ve no objection in principle.  Thorough preparation for such a rewrite 
> would also include a review of the mailing list archives and the wiki.
> 
> We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) 
> before beginning actual writing.
> 
> It’s a pretty massive project, I think you’ll need to recruit a team.
> 
> Regards,
> John Ralls
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

[GNC-dev] Import Documentation

[Frank H. Ellenberger]

Hi David Cousens,

Some update inline:

Am 08.09.2018 um 03:37 schrieb David Cousens:
> Thanks Frank,
>   
> It may be easier to start with what was there originally and rework it for 
> the recent changes with the CSV importer in
> particular.  I don't use QIF at all but the setup should not have changed 
> appreciably for that. OFX should not have
> changed appreciably. As far as I can see, the main matcher part is the same 
> no matter what the import format so I will
> structure it to reflect that.   
>   
> If its not in the current Doc format I can convert it over.   
>   
> David Cousens   
>   
> On Sat, 2018-09-08 at 02:06 +0200, Frank H. Ellenberger wrote:
>> Hi David C.
>>
>> There was a chapter. it was accidently removed instead of moved a few
>> years ago.
>>
>> I can try to get it back.

Until now I did not find it. It might be I messed it up with import-qif.

>> Frank
>>
>> Am 08.09.2018 um 01:53 schrieb David Cousens:
>>> Hi
>>>
>>>  I recently made some changes to the import matcher to allow multiple
>>> selection of rows and assign a destination account to, all rows in the
>>> selection.
>>>
>>> I wanted to document this in the DOcs but could not find any documentation
>>> on the Importing of files at all, either in the Help Manual or the Turoial
>>> and Concepts guide.
>>>
>>> The Help manual selection on Transactions has a number of stubs for online
>>> importing. I would propose a similar section on  which addressed either
>>> before or after the stub on online importing:
>>> Importing from Files
>>>Importing from OFX/QFX
>>>Importing from QIF

Current location:
https://github.com/Gnucash/gnucash-docs/blob/maint/help/C/Help_ch_GettingStarted.xml:


This chapter should describe the druids/wizzards/assistents or however
they are called today. Version 1.6.4 had another structure where it was
part of "Importing Quicken ..."

>>>Importing from CSV
>>>
>>> Is anyone currently working on documentation of impoorting from files?  If
>>> so I am happy to contribute changes as above.

In the german part of the wiki, we have a page about
Data exchange
... by file import/export
... online by aqbanking
https://wiki.gnucash.org/wiki/De/Datenaustausch
Probably we should use a similar structure?

Because there is always the question in which part (Help or Guide)
informations belong, see also the related bugs:
https://bugs.gnucash.org/show_bug.cgi?id=571320 - Help me choose which
download format to use for my bank statements

https://bugs.gnucash.org/show_bug.cgi?id=687820 - Proposal to
restructure Tutorial and Concepts Guide
and it's dependency tree

>>> If not I would be willing to have a go at a first pass at producing some
>>> documentation.
>>>
>>> Is my choice of location sensible and consistent  with the overall
>>> documentation objectives?
>>>
>>> Davdi
>>>
>>>
>>>
>>> -
>>> David Cousens
>>> --
>>> Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
>>> ___
>>> gnucash-devel mailing list
>>> gnucash-devel@gnucash.org
>>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>>>
>>
>>



___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Docs under Linux; was: GNOME Template in Guide but not Help

[John Ralls]

> On Sep 8, 2018, at 8:52 AM, Frank H. Ellenberger 
>  wrote:
> 
> 
> 
> Am 08.09.2018 um 05:06 schrieb John Ralls:
>> 
>> 
>>> On Sep 7, 2018, at 4:54 PM, Frank H. Ellenberger 
>>>  wrote:
>>> 
>>> Hi David,
>>> 
>>> Am 07.09.2018 um 17:29 schrieb David T. via gnucash-devel:
 Hello,
 
 In digging around the documentation source XML files (gnucash-help.xml and 
 gnucash-guide.xml) I noticed that gnucash-guide.xml includes:
 
 
 
 I tried the link, but it is broken, moreover, gnucash-help.xml does not 
 include this information. Is this supposed to be here, and if so, why 
 isn’t it used in gnucash-help.xml?
> 
> Most of our makefiles are copied from scollkeeper-example2 with a
> similar timestamp. Should we remove them too? ;-)
> There is still a manual online:
> http://scrollkeeper.sourceforge.net/documentation/scrollkeeper_example2_manual/index.html
> 
>>> As you can see from the date in the template and John mentioned before
>>> in another thread, almost our whole docs build system was unmaintained
>>> for over a decade.
>>> 
>>> In Gnome 2 this templates were replaced by the GNOME Documentation Build
>>> Utilities (GDU). See my "research" in
>>> https://wiki.gnucash.org/wiki/Gnome_Doc_Utils
>>> 
>>> ISTM that I opened a bug report too, but can not find it now.
>>> 
>>> For some unknown reason, help has the template in each chapter. Probably
>>> the maintainer at that time was testing the right way and got disrupted.
>>> I /believe/, having one template per book, not per chapter is the right way.
>>> 
>>> The purpose is to collect the infos required to generate the OMF, the
>>> digital equivalent of the index cards in the library.
>>> 
>>> The question, when I got distracted, was:
>>> should we make GDU a build dependency or must we adapt the useful parts?
>>> 
>>> Or in other words: can we keep our translations as they are or requires
>>> GDU to convert them to gettext-po files. The downside of po files can be
>>> seen in out frozen italian translation.
>> 
>> 
>> Gnome Doc Utils last release was in 2012. It *did* get migrated to an active 
>> gitlab project,  https://gitlab.gnome.org/GNOME/gnome-doc-utils 
>> , but the Gnome docs use 
>> https://gitlab.gnome.org/GNOME/yelp-tools/ 
>>  now. A rather cursory 
>> web-search suggests that Yelp doesn’t use OMF anymore, and it’s not really 
>> clear to me that our users really benefit much from our using Yelp anyway, 
>> any more than they do from our using the Windows Help Browser. I propose in 
>> the near term that we just open the docs in the default browser (we already 
>> do that for Mac and have since 2.4.0) and try for 4.0 to open them in a 
>> GtkWebkitWebView like we do reports.
> 
> The whole help under Linux has become a mess:
> OMFs are an XDG standard and used by rarian, the tool which creates
> yelps index, but KHelpcenter uses .desktop files instead. By this .omf
> or .desktop metafiles the docs appear in the index of the respective
> help viewer and can be read there without starting the program or
> searching the files on the disk.
> 
> Gnome3 yelp-tools support only mallard, which seems to be a mixture of
> Docbook and DITA. Because GDP suggests also a licence change, they seem
> not to offer conversion tools.
> 
> One benefit of both help viewers: they can also display man and info
> pages. So with the respective 'Xhelp:', 'man:' or 'info:' URL one could
> link also such elements.
> 
> The KHelpcenter works on html files. From my observations html files are
> some 25% larger than xml files and need some time to generate. So
> proofreading is much faster done with yelp on the docbook main file.
> 
>> 
>> I think that means we shouldn’t make GDU a doc-system dependency
> 
> I believe, if you work on the italian translation it is already there.
> 
> and that there may be fewer “useful parts” than you expect.

Heh, I expect no useful parts at all because I don’t think many users even 
approach Help by starting with Yelp or KDEHelp and going through the index. I 
think most everyone nowadays starts at some web search engine and nearly all 
the rest start at the help menu in-app.

The Italian translation is the only one using po files, but its processing is 
frozen because when you reprocess it most of the msgids turn fuzzy and it 
becomes English with scattered Italian. We may as well remove the 
infrastructure and leave just the last gnucash-guide.xml and gnucash-help.xml.

At some point we’re going to have to drop both Italian and Japanese 
documentation for being obsolete.

As for Scrollkeeper, it’s embalmed body is still on Sourceforge because that’s 
what Sourceforge does with dead projects. The last release was in 2002 and the 
repository is read-only (and not online) because it’s CVS and SourceForge has 
removed everything except the checkout infrastructure for CVS. Debian maintains 
a Scrollkeeper 

[GNC-dev] Docs under Linux; was: GNOME Template in Guide but not Help

[Frank H. Ellenberger]

Am 08.09.2018 um 05:06 schrieb John Ralls:
> 
> 
>> On Sep 7, 2018, at 4:54 PM, Frank H. Ellenberger 
>>  wrote:
>>
>> Hi David,
>>
>> Am 07.09.2018 um 17:29 schrieb David T. via gnucash-devel:
>>> Hello,
>>>
>>> In digging around the documentation source XML files (gnucash-help.xml and 
>>> gnucash-guide.xml) I noticed that gnucash-guide.xml includes:
>>>
>>> 
>>>
>>> I tried the link, but it is broken, moreover, gnucash-help.xml does not 
>>> include this information. Is this supposed to be here, and if so, why isn’t 
>>> it used in gnucash-help.xml?

Most of our makefiles are copied from scollkeeper-example2 with a
similar timestamp. Should we remove them too? ;-)
There is still a manual online:
http://scrollkeeper.sourceforge.net/documentation/scrollkeeper_example2_manual/index.html

>> As you can see from the date in the template and John mentioned before
>> in another thread, almost our whole docs build system was unmaintained
>> for over a decade.
>>
>> In Gnome 2 this templates were replaced by the GNOME Documentation Build
>> Utilities (GDU). See my "research" in
>> https://wiki.gnucash.org/wiki/Gnome_Doc_Utils
>>
>> ISTM that I opened a bug report too, but can not find it now.
>>
>> For some unknown reason, help has the template in each chapter. Probably
>> the maintainer at that time was testing the right way and got disrupted.
>> I /believe/, having one template per book, not per chapter is the right way.
>>
>> The purpose is to collect the infos required to generate the OMF, the
>> digital equivalent of the index cards in the library.
>>
>> The question, when I got distracted, was:
>> should we make GDU a build dependency or must we adapt the useful parts?
>>
>> Or in other words: can we keep our translations as they are or requires
>> GDU to convert them to gettext-po files. The downside of po files can be
>> seen in out frozen italian translation.
> 
> 
> Gnome Doc Utils last release was in 2012. It *did* get migrated to an active 
> gitlab project,  https://gitlab.gnome.org/GNOME/gnome-doc-utils 
> , but the Gnome docs use 
> https://gitlab.gnome.org/GNOME/yelp-tools/ 
>  now. A rather cursory web-search 
> suggests that Yelp doesn’t use OMF anymore, and it’s not really clear to me 
> that our users really benefit much from our using Yelp anyway, any more than 
> they do from our using the Windows Help Browser. I propose in the near term 
> that we just open the docs in the default browser (we already do that for Mac 
> and have since 2.4.0) and try for 4.0 to open them in a GtkWebkitWebView like 
> we do reports.

The whole help under Linux has become a mess:
OMFs are an XDG standard and used by rarian, the tool which creates
yelps index, but KHelpcenter uses .desktop files instead. By this .omf
or .desktop metafiles the docs appear in the index of the respective
help viewer and can be read there without starting the program or
searching the files on the disk.

Gnome3 yelp-tools support only mallard, which seems to be a mixture of
Docbook and DITA. Because GDP suggests also a licence change, they seem
not to offer conversion tools.

One benefit of both help viewers: they can also display man and info
pages. So with the respective 'Xhelp:', 'man:' or 'info:' URL one could
link also such elements.

The KHelpcenter works on html files. From my observations html files are
some 25% larger than xml files and need some time to generate. So
proofreading is much faster done with yelp on the docbook main file.

> 
> I think that means we shouldn’t make GDU a doc-system dependency

I believe, if you work on the italian translation it is already there.

 and that there may be fewer “useful parts” than you expect.
> 
> Regards,
> John Ralls

Regards
Frank

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[John Ralls]

> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel 
>  wrote:
> 
> Hello,
> 
> As I have noted in another thread recently, I am finding the process of 
> updating the various documentation pieces extremely challenging—due in large 
> part to the fragmented nature of this documentation. Different contributors 
> have placed information on similar topics in any of a number of official 
> locations in the GnuCash documentation realm, making the update process a 
> circular nightmare. 
> 
> This leads to variation in content, approach, and likelihood that a user is 
> going to locate the full information on a given subject.
> 
> Rather than tackle each editorial task as if somehow this time it will be 
> different, I would like to ask whether there would be support for a complete 
> rewrite of the documentation. My idea would be to somehow merge all the 
> content from the Guide and the Help into one huge file, and then establish a 
> single Grand Unifying Manual that would provide users with a single source 
> for help. Contextual help would be stripped back to only naming on screen 
> functions, with references back to the GUM in all cases. The wiki would 
> remain primarily for specific use cases and temporary issues. The FAQ would 
> also point to the docs in most cases. Optionally, I would strip out the 
> “Tutorial” aspect of the Tutorial and Concept Guide, as I think a solid 
> Manual would obviate the need for this aspect (that, and the fact that most 
> of the Tutorail sections are written in a “Hi, how are ya” folksie tone that 
> I find inappropriate in formal documentation).
> 
> I do not make this suggestion lightly—I know the complexity and difficulty of 
> such an endeavor. However, I increasingly find that the content of the Help 
> and Guide are so inextricably enmeshed that any attempt to clean up one will 
> have extreme impact on the other—and attempting to shepherd these changes 
> through piecemeal is cumbersome at best. 
> 
> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. 
> That’s over 500 pages of information—a good portion of which is duplicated 
> across the docs. Any such rewrite would entail a HUGE effort, which is why I 
> write this email: there is no way anyone would undertake this without knowing 
> in advance whether the community would accept such a change at the outset.

I’ve no objection in principle.  Thorough preparation for such a rewrite would 
also include a review of the mailing list archives and the wiki.

We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) 
before beginning actual writing.

It’s a pretty massive project, I think you’ll need to recruit a team.

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

[GNC-dev] Long Term Documentation Directions

[David T. via gnucash-devel]

Hello,

As I have noted in another thread recently, I am finding the process of 
updating the various documentation pieces extremely challenging—due in large 
part to the fragmented nature of this documentation. Different contributors 
have placed information on similar topics in any of a number of official 
locations in the GnuCash documentation realm, making the update process a 
circular nightmare. 

This leads to variation in content, approach, and likelihood that a user is 
going to locate the full information on a given subject.

Rather than tackle each editorial task as if somehow this time it will be 
different, I would like to ask whether there would be support for a complete 
rewrite of the documentation. My idea would be to somehow merge all the content 
from the Guide and the Help into one huge file, and then establish a single 
Grand Unifying Manual that would provide users with a single source for help. 
Contextual help would be stripped back to only naming on screen functions, with 
references back to the GUM in all cases. The wiki would remain primarily for 
specific use cases and temporary issues. The FAQ would also point to the docs 
in most cases. Optionally, I would strip out the “Tutorial” aspect of the 
Tutorial and Concept Guide, as I think a solid Manual would obviate the need 
for this aspect (that, and the fact that most of the Tutorail sections are 
written in a “Hi, how are ya” folksie tone that I find inappropriate in formal 
documentation).

I do not make this suggestion lightly—I know the complexity and difficulty of 
such an endeavor. However, I increasingly find that the content of the Help and 
Guide are so inextricably enmeshed that any attempt to clean up one will have 
extreme impact on the other—and attempting to shepherd these changes through 
piecemeal is cumbersome at best. 

Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. 
That’s over 500 pages of information—a good portion of which is duplicated 
across the docs. Any such rewrite would entail a HUGE effort, which is why I 
write this email: there is no way anyone would undertake this without knowing 
in advance whether the community would accept such a change at the outset.

Comments are welcome.

David
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation--What else?

[David T. via gnucash-devel]

Thanks John for the confirmation on my efforts to realign my repo.

David

> On Sep 7, 2018, at 7:55 PM, John Ralls  wrote:
> 
> David,
> 
> I checked your Github repository and it looks good.
> 
> I agree with Geert, your plan for Online Quotes seems sound.
> 
> I haven’t reviewed the wiki Online Quotes page; if there’s material there 
> about the F::Q API, you may safely remove it because that’s duplicated in the 
> F::Q documentation. Any other technical information should stay or at least 
> be carefully reviewed before removal. 
> 
> Regards,
> John Ralls
> 
>> On Sep 7, 2018, at 1:24 PM, David T. via gnucash-devel 
>>  wrote:
>> 
>> Ha. That means I have to figure out how to get my local repository working 
>> again….
>> 
>> [some time later]
>> 
>> OK, so I googled “force upstream into fork” and found some resources that 
>> seem to have fixed things for me. The commands I issued were:
>> 
>> DHT-Retina:gnucash-docs david$ git fetch upstream
>> DHT-Retina:gnucash-docs david$ git reset --hard upstream/maint
>> HEAD is now at ecd868b Fix xmllint error
>> DHT-Retina:gnucash-docs david$ git push origin maint --force
>> Counting objects: 99, done.
>> Delta compression using up to 8 threads.
>> Compressing objects: 100% (99/99), done.
>> Writing objects: 100% (99/99), 95.66 KiB | 0 bytes/s, done.
>> Total 99 (delta 69), reused 0 (delta 0)
>> remote: Resolving deltas: 100% (69/69), completed with 15 local objects.
>> To https://github.com/sunfish62/gnucash-docs
>> + 4de1289...ecd868b maint -> maint (forced update)
>> 
>> If I understand it correctly, the first command brings in upstream 
>> (github.com/gnucash/gnucash-docs ), 
>> the second force-resets my local (computer) repo to match upstream/maint, 
>> and the last pushes my (now-updated) local repo to my github fork. Do I have 
>> this right?
>> 
>> This appears to have done the trick; I see Geert’s final xmllint changes to 
>> ch_basics.xml on my local system, and github says that my fork is even with 
>> Gnucash-docs.
>> 
>> Is there another way that I can verify this? After all, I have remarkably 
>> bad luck when it comes to git…
>> 
>> David
>> 
>> 
>>> On Sep 7, 2018, at 12:54 PM, Geert Janssens  
>>> wrote:
>>> 
>>> That reads like a good plan.
>>> 
>>> I'm all for deduplication. I agree with your assessment of what help and 
>>> guide 
>>> should be. And that the guide should be the general documentation with 
>>> troubleshooting explained in the wiki. Troubleshooting tends to change more 
>>> quickly than base documentation.
>>> 
>>> I also think it's a good idea to keep an entry point on Online Quotes on 
>>> the 
>>> FAQ.
>>> 
>>> So a +1 on all accounts.
>>> 
>>> Geert
>>> 
>>> Op vrijdag 7 september 2018 17:47:55 CEST schreef David T. via 
>>> gnucash-devel:
 Hello,
 
 I am going to raise—once again—the spectre of the conflicting and
 duplicative information in the various documentation packages in relation
 to online quote retrieval.
 
 As one of the documentarians in the broader community, I episodically
 attempt to make sense of, clean up, and (hopefully) improve the various
 sets of documentation. Currently, I am poking primarily at the wiki, and I
 find myself in a long series of circular tangles of information that render
 a solution daunting (to say the least).
 
 There are two entries on Online Quotes in the FAQ; these refer to each 
 other
 and to a separate page on the wiki. The separate wiki page is a mess of
 highly technical information that has nothing to do with the FAQ questions,
 and offers no help in that regard (making the references from the FAQ less
 than helpful). Furthermore, both the Guide and the Help have separate,
 essentially complete descriptions of setting up online quotes.
 
 Any rightful attempt at ensuring that online quoting is properly and
 carefully documented requires that *every* one of these sources be updated
 and coordinated with the others. This turns out to be exceedingly
 challenging, especially given that it’s not entirely clear which source
 should contain which data. To me (admittedly a “Concepts” kind of guy), the
 fullest description of setup and management should go into the Guide at
 section 9.6. However, the Help at section 5.4.1.1 includes another
 essentially full description of setup and management; presumably this entry
 should focus on the “This button does This action” kind of information
 (since that is what I understand is supposed to be the primary purpose of
 the Help). And where, in all this, do the different pieces on the wiki fit
 in?
 
 Attempting to shepherd any rationalization of these resources through the
 process is painful and time-consuming.
 
 I will note that the challenge described here repeats itself time and time
 again, in all manner of subject areas in the documentation,