[GNC] File Format Documentation (Bug 777893)

Wed Aug 15 13:02:53 EDT 2018

But it’s not a ‘plain file’ as it is XML formatted. Someone expecting plain text and trying to view it is going to be met with tag soup they’ve never seen before and might very well not know how to read it.

It also carries an .xml extension. So specifying the format is very specific and informative, even for users who aren’t familiar with XML. They’ll see in their file manager the extension, and/or the OS’s interpretation of the file type itself. (in this case both XML)

Knowing this might very well help them find their file if they know the format they are looking for.

But I do agree, the documentation should cover where files are stored. Ideally, this should be made part of the Help or Guide in the Getting Started section. It is certainly a common enough issue on the list.

Regards,
Adrien

> On Aug 15, 2018, at 10:24 AM, Christoph R <subscriptions+listen at rohland.net> wrote:
> 
> Hi David,
> 
>> The default file storage format is XML
> 
> I would not call this “XML" but "plain file”. From a user perspective it is not important in which internal format it is stored. But it makes a big difference if it is a simple file created by Gnucash or if Gnucash needs to connect to a DBMS.
> 
> And one of the biggest confusion for users on the mailing list is the question: “Where is my data?”. Pointing out that all your accounts and transactions are in a simple file might reduce that problem.
> 
> Cheers,
> Christoph
> 
>> Am 15.08.2018 um 00:05 schrieb David T. via gnucash-user <gnucash-user at gnucash.org>:
>> 
>> Hello,
>> 
>> In response to Bug 777893 (https://bugs.gnucash.org/show_bug.cgi?id=777893 <https://bugs.gnucash.org/show_bug.cgi?id=777893>), I have written a more detailed description of the storage choices available to users for insertion into the Tutorial & Concepts Guide at section 2.5. Given the extent of the text, I am including it here so that the broader community can offer suggestions for improvement. Note that I will insert appropriate encoding once I finalize the content.
>> 
>> Thanks,
>> David T.
>> 
>> ————————————————————
>> Proposed text for Tutorial & Concepts Guide section 2.5
>> ————————————————————
>> 
>> 2.5 Storing your financial data
>> 2.5.1 Overview
>> GnuCash offers several formats for storing your financial data. The default file storage format is XML, while a number of flavors of SQL storage are available. Users can choose a file format from the File Save and File Save As dialogs.
>> The primary GnuCash storage format is an XML file. The file is by default compressed with gzip, which is a preference that is set at Edit→Preferences→General→Use file compression. 
>> GnuCash also supports SQL storage via the DBI back end. It supports PostgreSQL, MySQL and SQLite3 databases.
>> 
>> Storage Comparison
>> As noted, GnuCash allows storage in either XML or SQL formats. Each of these formats has benefits and shortcomings that the user should consider for their needs and abilities. 
>> The XML format is the most stable and established format, and for this reason, it is the recommended format for most users. SQL storage was added for the 2.4 release and has become an increasingly popular choice for users.
>> Use of SQL formats for storage implies to many that GnuCash is database management software (DBMS). While that is a long term goal of the development team, GnuCash as currently designed is not DBMS. It is a financial application that can store its data in SQL files.
>> Many features that users of DBMS expect from a DBMS are not implemented in GnuCash. The GnuCash data schema is not normalized. Significant elements of the data logic is implemented in code, rather than data structure.
>> Gnucash uses the SQL back end to load the entire data store into memory in the same manner as the XML back end. Consequently, use of the SQL back end does not enable simultaneous multi-user access to a GnuCash file, although that is one long term goal.
>> One benefit of the SQL back end is that it saves changes incrementally, and every change is committed to the back end as it happens. This is in contrast to the XML back end, which only writes to the data file when the user invokes the Save command. 
>> The SQL back end does allow users with SQL experience to write queries against the data to create custom reports without using Gnucash’s internal report system. It is important to note that modification of GnuCash data using external access modes is strongly discouraged by the development team, and damages to a GnuCash data file that result from such modifications are strictly the responsibility of the user.
>> 
>> Storage Comparison Table
>> 
>> XML     						SQL
>> Default						Optional
>> Requires no additional software	Requires additional software
>> Requires no additional expertise	Requires expertise with DBMS 
>> Compressed  					Uncompressed
>> Save on command				Save on commit
>> Uses log files					Does not use log files
>> Not multi-user					Not multi-user
>> Limited external processing		External processing through SQL queries
>> 
>> 
>> _______________________________________________
>> gnucash-user mailing list
>> gnucash-user at gnucash.org
>> To update your subscription preferences or to unsubscribe:
>> https://lists.gnucash.org/mailman/listinfo/gnucash-user
>> If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
>> -----
>> Please remember to CC this list on all your replies.
>> You can do this by using Reply-To-List or Reply-All.
> 
> _______________________________________________
> gnucash-user mailing list
> gnucash-user at gnucash.org
> To update your subscription preferences or to unsubscribe:
> https://lists.gnucash.org/mailman/listinfo/gnucash-user
> If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> -----
> Please remember to CC this list on all your replies.
> You can do this by using Reply-To-List or Reply-All.