[GNC-dev] Long Term Documentation Directions

David Cousens davidcousens at bigpond.com
Tue Sep 11 03:15:43 EDT 2018


Just some comments on a couple of other points: 

Embedding even the context help in the program code is not a really good
idea. It means that text cannot be edited /altered easily separately from
the program and without rebuilding the program.  My understanding is that it
can be done from a docbook that just has the links to a section which is
displayed in response to a help button being pressed or  something like a
Shift-F1 key combination while the focus is on the button/checkbox/etc that
you want help on. It could be a separate window from the main help system
which just pops up displays the information and closes when you finish (i.e
no navigation - want help on something else-click on something else and hit
shift F10 -  but pulls its text from a HTML file created from a 
docbook/asciidoc or similar source help file. It would not necessarily have
to have such a file broken up into subfiles.

The same would also be true of the Concepts guide. It could be modules
within a single file or a collection of files which can either be displayed
independently or linked together to form a full document. The existing Help
manual are organised a bit like that but the separate files for the chapters 
do not have document headers so they can't be displayed independently . What
I mean by that is you can point a browser at the derived HTML file for a
chapter and have it display just that chapter without having to load the
whole Help manual and navigate to the bit you want. In any case breaking it
into separate source files is not a high priority but it may make some sense
to have related content in its own module futher down the track. It can also
be done progressively once the content  has been rearranged.

Walk throughs on the other hand require a considerable code effort and have
to be embedded in the code completely. They need an engine which can drive
the interfaceand either feed data in or better still request the user to
enter the data.  The one I am most familiar with is in the Flight Gear
flight simulator on Linux. It is just like a flying instructor taking you
through the check list before takeoff. While it would be nice I doubt if it
would really be feasible.

David Cousens

David Cousens
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html

More information about the gnucash-devel mailing list