Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[John Ralls]

> On Aug 21, 2018, at 11:50 AM, Geert Janssens  
> wrote:
> 
> 
> I believe the gnome project is using Mallard (http://projectmallard.org/). 

That depends. The Gnome applications that have help at all use mallard (which 
is a Docbook dialect) on which they apply yelp-tools and itstool to create 
documentation. The libraries use gtk-doc to extract specially formatted 
comments and convert that to a form of Docbook to feed to yelp tools and 
itstool. In general those documents are published only on the web. The 
application docs are very simple, no more than a few pages.

> Aside from that they also expect there writers to work with git.

Version control is an obvious hard requirement. I don't know if it completely 
fulfills your "manageability" requirement, but it's crucial in a collaborative 
environment to be able to track who-did-what-when and to be able to restore an 
earlier version if something goes awry.

That said I'm perfectly happy to copy a rewritten section of a document into my 
working directory and create a commit out of it on behalf of a non-technical 
author who can't get their head around git.

Regards,
John Ralls

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

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[John Ralls]

Adrien,

If you mean https://help.gnome.org , those docs are 
built using Yelp tools, see 
https://gitlab.gnome.org/GNOME?utf8=%E2%9C%93=yelp 
. Most of that 
documentation seems pretty cursory, even for largish apps like Gnome Web (aka 
Epiphany).

Not all “Gnome” projects are included there. The GIMP and Inkscape (though I 
guess since Inkscape doesn’t keep their repo on gitlab.gnome.org 
 they’re no more a Gnome app than we are), for 
example, both maintain their own documentation (in DocBook) and doc build 
scripts.

Gimp’s docs are similar to ours if one doesn’t use viewdoc: They stand apart; 
there are links to the previous and next pages, there’s a “home” link back to 
the TOC, but nothing tying it to the main website.

Inkscape doesn’t really have a comprehensive manual. There’s a man page (not on 
their website) and 9 single-page tutorials (written in DocBook) that are 
displayed as regular website content pages with no extra links beyond the site 
menubar across the top.

No doubt that viewdoc.phtml could be improved. As Geert noted it’s pretty 
basic, just 144 lines of php. If someone fluent in modern php and css would 
like to overhaul and modernize the website we’d welcome it, but I think the 
core team’s time is better spent on GnuCash itself.

Regards,
John Ralls

> On Aug 21, 2018, at 8:49 AM, Adrien Monteleone 
>  wrote:
> 
> Thanks for the background info Geert,
> 
> I recall a discussion some time ago about the tools and methods used to 
> generate the documentation, and I think based on that thread and the info 
> you’ve just provided that the solution lies in a new method entirely. (frames 
> aren’t really the best option as you noted)
> 
> I’ll try to dig up that old thread, but is there a list of ’needs’ of the 
> developers to use when evaluating methods?
> 
> The only thing I can find recently is that the intended approach was to 
> create an “O’Reilly” style book, (just a goal or hard and fast requirement?) 
> and I recall there needed to be a means to generate PDF, .mobi, and .epub 
> versions.
> 
> As for the current method, I see docbook has something called docbook-xslt 
> which is a stylesheet approach to layout and other visuals. It seems geared 
> more toward print than web, but I supposed it could be used for such. This 
> strikes me though as trying to find a means to keep using the proverbial 
> hammer rather than a more appropriate tool. Though, I do see Gnome is still 
> using Docbook and their user help is well integrated into their website as 
> individual web pages, (breadcrumbs and all) and not anything resembling a 
> printed page.
> 
> Regards,
> Adrien
> 
>> On Aug 21, 2018, at 2:46 AM, Geert Janssens  
>> wrote:
>> 
>> Op dinsdag 21 augustus 2018 02:44:59 CEST schreef Adrien Monteleone:
>>> David C,
>>> 
>>> So for clarification this is the first link you posted about:
 https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#t
 xns-regstyle1
>>> Notice this is in the folder /docs/v3/C/gnucash-guide/
>>> 
>>> But the link on the Documentation page and the link you included (both in 
>> that first post and in the last one) that said how you got there was this:
 https://www.gnucash.org/viewdoc.phtml?rev=3=C=help
>>> 
>>> So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same
>>> link as above. (though it might be the exact same content, I didn’t check)
>>> 
>>> I can’t find any way, other than typing it in directly, to get to the
>>> /docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/
>>> folders and contents. All of the links on the documentation page seem to
>>> point instead to the /viewdoc.phtml which never changes the URL as you
>>> navigate the document. (my guess is the viewdoc.phtml template is serving
>>> the pages physically located in /docs/v3/C/, we just can’t see the real
>>> URL)
>> 
>> The viewdoc.phtml page is a first and imperfect attempt to integrate the 
>> documentation in the website.
>> 
>> It ensures that while presenting the documentation the main website's 
>> navigation menus and style are still visible. Before that page existed 
>> clicking on a documentation link would suddenly remove all website 
>> decorations 
>> and just show you the documentation on a plain white page with no option to 
>> navigate to other parts of the main website.
>> 
>> viewdoc.phtml is just a wrapper that opens the actual documentation in a 
>> separate frame. If you ask your browser to open that frame in its own window 
>> you'll see the direct links David posted here.
>> 
>> The use of a frame is old-fashioned and has indeed many limitations. It was 
>> the only option at the time that could be implemented with reasonable effort.
>> 
>> Of course it would be much nicer to have bread crumbs and clear links for 
>> each 
>> page. And a documentation navigation menu integrated in the 

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[John Ralls]

> On Aug 21, 2018, at 11:50 AM, Geert Janssens  
> wrote:
> - it should allow multiple output formats. A few the come to mind:
> html, pdf, epub, mobi, windows compressed help, xml for yelp,...

We don't need a single tool to do that; in fact we don't use a single tool now. 
We create Windows compressed html (.chm) with HTML Help Workshop from the 
xslt-created HTML and mobi with calibre from the xslt-created epub.

That aside, I think we should reconsider windows compressed help. Microsoft's 
own Windows 10 applications seem to open the browser to the relevant 
documentation page on www.microsoft.com and the help browser is still decorated 
with Windows 2000 frame and controls. It looks quite jarring. We could more 
easily just open the documents in a GtkWebkitWebView just like reports.

Regards,
John Ralls


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

Re: [GNC-dev] Bug 796778 Feature Request Multiple Selection in Import- matcher

[David Cousens]

Forgot Link to Bug report and patch file
https://bugs.gnucash.org/show_bug.cgi?id=796778

David



-
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

Re: [GNC-dev] Bug 796778 Feature Request Multiple Selection in Import- matcher

[David Cousens]

Hi,

I have attached a patch file with changes to
gnucash/import-export/import-main-matcher.c and 
gnucash/gtkbuilder/dialog-import.glade for adding multiple selection
capability to the import-matcher with the ability to assign a single
transfer
 account to the selected transactions. 

Transactions can be selected by any combination of Ctrl-click , Shift -click
and click and mouse drag. Using either a Right click on the importer or the
Shift-F10 GTK Popup menu shortcut will bring up a popupmenu with a single
entry "Assign a transfer account". Clicking on that initiates selecting a
transfer account and then assigning it to all transactions in the selection. 

Control is the returned to the import matcherwhere another group of
transactions can be selected and the process repaeted until all transactions
have a transfer account applied. Clicking OK will then import the
transactions as usual. 

The orignial double-click to input a transfer account for a single
transaction is unaffectedby the above changes.  I have tested the above
changes with "File->Import->Import OFX/QFX". and they work fine.  They
should also apply to any of the transaction import formats as they were
changes only to the import-main-matcher which seems to be common to the
other formats

I was looking for an appropriate point to modify the documentation, but I
could not find a section on the importing of transactions from files in
either the Tutorial and Concepts Guide or the Help Manual. Chapter 6 of the
Help Manual on Common Transaction operations would seem to me to be a
logical point to document importing transactions from OFX/QFX or CSV files,
for example either before or after 6.15 Online Actions. 
e.g. 
6.16 Importing Transactions from Files followed by 
6.17  General Journal.

Unless the documentation team has another suggestion or already has work in
progress on this, I am willing to have a go at producing some documentation
of the importing of transactions from files.

David Cousens



-
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