[GNC-dev] Autogenerated GUI description? was: Long Term Documentation Directions

John Ralls jralls at ceridwen.us
Mon Sep 10 22:52:36 EDT 2018



> On Sep 10, 2018, at 2:41 PM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> wrote:
> 
> 
> 
> Am 10.09.2018 um 13:46 schrieb Geert Janssens:
>> Op zondag 9 september 2018 12:21:08 CEST schreef Frank H. Ellenberger:
> :
>>> ?: Usability: Will F1 or pressing the Help button still deliver the
>>> right content? I know it is aslo now not always th case.
>>> 
>> If I read David's proposal carefully there remains some kind of interface 
>> index document (listing all ui buttons, menu items,...). But instead of having 
>> full documentation they would point to relevant sections in the manual. 
>> Assuming we can make cross-linking work, this should be covered.
>> 
>> On the other hand if we think of our documentation more as a clever 
>> composition of documentation snippets, we could also opt to compose help 
>> information from the same snippets that are used to compose the full manual. 
>> That's theory of course. I don't know if this would be possible in practice.
> 
> Let me concentrate here on the reference part - whereever it might
> appear later:
> Woking on https://bugs.gnucash.org/show_bug.cgi?id=782423 I got the
> following basic idea:
> Scan the .glade files for Label, corresponding tooltip_text and value
> lists to generate the menu and dialog descriptions (curently4. GnuCash
> Windows & Menus Options Overview). We want additional the help context
> id and eventally a Purpose field for each dialog (i.e. by doxygen?).
> 
> The tables in Help Appendix A are a edited compilation of several
> sources (gnc & FQ code, a website, a email).
> 
> I am not sure, if it would help editors and/or users to reenable a cross
> reference again, but each good markup language should be able to produce
> one.

So riffing on the glade idea we could set up Doxygen markup, maybe with some special keywords, in the GUI source code that expands on tooltips or fills in for them in places where they’re not appropriate. I don’t know off hand if GtkBuilder is tolerant of elements or attributes it doesn’t know about, but if it is we could add documentation that way to builder (aka glade) files as well.

I like the idea of getting the help documentation into the source code. 

Regards,
John Ralls


More information about the gnucash-devel mailing list