Skip to content

Commit

Permalink
xmlformat all docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@fellen
fellen committed Apr 24, 2021
1 parent 2598119 commit 47e0514
Show file tree
Hide file tree
Showing 182 changed files with 200,069 additions and 118,407 deletions.
283 changes: 157 additions & 126 deletions guide/C/appendixa.xml
View file
@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix SYSTEM "gnc-docbookx.dtd">

<!--
(Do not remove this comment block.)
Version: 2.0.0
Expand All @@ -15,91 +14,104 @@
Translators:
(translators put your name and email here)
-->
<appendix id="appendixa">
<title>Migration Guide</title>
<para>
This appendix is to help current users of other financial software packages in their migration to &app;. We address the conceptual differences between the layout of &app; accounts versus other software packages.
</para>
<appendix id="appendixa">
<title>Migration Guide</title>

<sect1 id="appendixa_accts_vs_cats1">
<title>Using Accounts vs. Categories</title>
<para> If you are familiar with other personal finance programs, you are already accustomed to
tracking your income and expenses as categories. Since &app; is a double-entry system (see
<xref linkend="basics-accounting1" />),
income and expenses are tracked in accounts. The basic concept is the same, but the account
structure allows more consistency with accepted business practices. So, if you are a business user
as well as a home user, &app; makes it easy to keep track of your business as well as your
personal accounts.</para>
<para>
Income and expense accounts give you the same information you would get with categories, but they
also give you more flexibility in entering your transactions. In &app;, you have the option to
enter transactions directly into income and expense accounts through their account registers.
Other programs that use categories do not offer this option, because there is no
<quote>account register</quote> for a category.
</para>
<para>
You also have the option in &app; to treat income and expense accounts exactly as you would treat
categories, if you are more comfortable with that method. In
<trademark class="registered">Quicken</trademark>
and similar programs, transactions require an account and a category. Substitute an income or
expense account name in &app; where you would normally enter a category name in the other
programs, and the result should be the same. We will discuss transaction entry in
<xref linkend="basics-transactions2" /> in greater detail.
</para>
</sect1>

<sect1 id="appendixa_import">
<title>Importing Data</title>
<para>
If you want to import data from your previous application, you should distinguish between
financial data and other data. Probably the best way to import financial data is the
<quote>Quicken Interchange Format</quote> <acronym>QIF</acronym> .
It is a specific format for financial data, which most financial applications for the private
sector know and can use for export.</para>
<para>
For other data we suggest the use of the <quote>Comma Separated Value</quote>
<acronym>CSV</acronym> format.
<para>This appendix is to help current users of other financial software packages in their migration to
&app;. We address the conceptual differences between the layout of &app; accounts versus other
software packages.
</para>
<sect2 id="appendixa_qif1">
<title>Import of Financial Data by <acronym>QIF</acronym> Files</title>
<para>
See <ulink url="&url-wp-en;Quicken_Interchange_Format" /> for it's details.

<sect1 id="appendixa_accts_vs_cats1">
<title>Using Accounts vs. Categories</title>

<para>If you are familiar with other personal finance programs, you are already accustomed to tracking
your income and expenses as categories. Since &app; is a double-entry system (see
<xref linkend="basics-accounting1" />), income and expenses are tracked in accounts. The basic
concept is the same, but the account structure allows more consistency with accepted business
practices. So, if you are a business user as well as a home user, &app; makes it easy to keep
track of your business as well as your personal accounts.
</para>
<para>Some &app; users collected their knowledge about the best use in our
<ulink url="&url-wiki-qif;"></ulink>.

<para>Income and expense accounts give you the same information you would get with categories, but they
also give you more flexibility in entering your transactions. In &app;, you have the option to
enter transactions directly into income and expense accounts through their account registers.
Other programs that use categories do not offer this option, because there is no
<quote>account register</quote> for a category.
</para>
<para>For other formats and more details see <xref linkend="chapter_importing"/>.</para>
</sect2>
<sect2 id="appendixa_business">
<title>Import of Business Data by <acronym>CSV</acronym> Files</title>
<para>
If you want to import customers and vendors or bills and invoices see
<xref linkend="ch_import_bus_data" />.

<para>You also have the option in &app; to treat income and expense accounts exactly as you would treat
categories, if you are more comfortable with that method. In
<trademark class="registered">Quicken</trademark> and similar programs, transactions require
an account and a category. Substitute an income or expense account name in &app; where you
would normally enter a category name in the other programs, and the result should be the same.
We will discuss transaction entry in <xref linkend="basics-transactions2" /> in greater
detail.
</para>
</sect1>

<sect1 id="appendixa_import">
<title>Importing Data</title>

<para>If you want to import data from your previous application, you should distinguish between financial
data and other data. Probably the best way to import financial data is the <quote>Quicken
Interchange Format</quote> <acronym>QIF</acronym> . It is a specific format for financial
data, which most financial applications for the private sector know and can use for export.
</para>

<para>For other data we suggest the use of the <quote>Comma Separated Value</quote> <acronym>CSV</acronym>
format.
</para>
</sect2>
</sect1>

<sect1 id="appendixa_xmlconvert1">
<title>Converting <acronym>XML</acronym> &app; File</title>
<para>The &app; <acronym>XML</acronym> data file can be transformed to almost any other data
format (e.g., <acronym>QIF</acronym>, <acronym>CSV</acronym>...) quite easily if one is familiar
with the <quote>Extensible Stylesheet Language Transformations</quote> <ulink url="&url-wp-en;XSLT"><acronym>XSLT</acronym></ulink>.
The &app; data file is well-formed <acronym>XML</acronym>, and it can therefore be run
through an <acronym>XSLT</acronym> parser with an associated stylesheet. This allows one
to transform the file to just about any format that can be designed,
given a properly written stylesheet.</para>

<para>A few steps need to be followed. The writing of a stylesheet is a task
for a different time, but if you can get one written, here&rsquo;s what you
need to do:</para>
<orderedlist>
<listitem>
<para>Copy the &app; <acronym>XML</acronym> data file to a working file.</para>
<important>
<para>If the file was last modified by a version of &app; older than 2.0, then before you
continue to the next step you will need to modify the working file&rsquo;s &lt;gnc-v2&gt; tag
to read something like this:
<literallayout>

<sect2 id="appendixa_qif1">
<title>Import of Financial Data by <acronym>QIF</acronym> Files</title>

<para>See <ulink url="&url-wp-en;Quicken_Interchange_Format" /> for it's details.
</para>

<para>Some &app; users collected their knowledge about the best use in our
<ulink url="&url-wiki-qif;"></ulink>.
</para>

<para>For other formats and more details see <xref linkend="chapter_importing"/>.
</para>
</sect2>

<sect2 id="appendixa_business">
<title>Import of Business Data by <acronym>CSV</acronym> Files</title>

<para>If you want to import customers and vendors or bills and invoices see
<xref linkend="ch_import_bus_data" />.
</para>
</sect2>
</sect1>

<sect1 id="appendixa_xmlconvert1">
<title>Converting <acronym>XML</acronym> &app; File</title>

<para>The &app; <acronym>XML</acronym> data file can be transformed to almost any other data format (e.g.,
<acronym>QIF</acronym>, <acronym>CSV</acronym>...) quite easily if one is familiar with the
<quote>Extensible Stylesheet Language Transformations</quote>
<ulink url="&url-wp-en;XSLT"><acronym>XSLT</acronym></ulink>. The &app; data file is
well-formed <acronym>XML</acronym>, and it can therefore be run through an
<acronym>XSLT</acronym> parser with an associated stylesheet. This allows one to transform the
file to just about any format that can be designed, given a properly written stylesheet.
</para>

<para>A few steps need to be followed. The writing of a stylesheet is a task for a different time, but if
you can get one written, here&rsquo;s what you need to do:
</para>

<orderedlist>
<listitem>
<para>Copy the &app; <acronym>XML</acronym> data file to a working file.
</para>

<important>
<para>If the file was last modified by a version of &app; older than 2.0, then before you continue to the
next step you will need to modify the working file&rsquo;s &lt;gnc-v2&gt; tag to read
something like this:
<literallayout>
&lt;gnc-v2 xmlns:cd="http://www.gnucash.org/XML/cd"
xmlns:book="http://www.gnucash.org/XML/book"
xmlns:gnc="http://www.gnucash.org/XML/gnc"
Expand All @@ -122,48 +134,67 @@ need to do:</para>
xmlns:fs="http://www.gnucash.org/XML/fs"
xmlns:addr="http://www.gnucash.org/XML/custaddr"&gt;
</literallayout>
</para>
</important>
<note><para>You can put pretty much anything you want behind the equal signs, but a unique
<acronym>URL</acronym> is what is typically used.</para>
</note>
</listitem>
<listitem>
<para>Create an <acronym>XSLT</acronym> stylesheet containing the transformation your desire,
or obtain one that&rsquo;s already written.</para>
<itemizedlist><title>User Contributed XSLT Stylesheets</title>
<listitem><para>in our repository: <ulink url="&url-src-maint;contrib/xslt"></ulink></para></listitem>
<listitem><para>in our wiki: <ulink url="&url-wiki-xslt;"></ulink></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Install an <acronym>XSLT</acronym> processor such as Saxon
(<ulink url="&url-wp-en;Saxon_XSLT" />) or Xalan (<ulink url="&url-wp-en;Apache_Xalan" />).
Any <ulink url="&url-wp-en;Category:XSLT_processors">conforming processor</ulink> will do, really...</para>
</listitem>
<listitem>
<para>Run the work file and the stylesheet through the processor according
to the processor&rsquo;s instructions.</para>
</listitem>
<listitem>
<para>You will now have a file in the desired output format. An
enterprising individual could go so far as to write a stylesheet to
transform the &app; data file to an OpenOffice spreadsheet (or
vice-versa, for that matter). Such things as <acronym>QIF</acronym> ought to be a little
less work.</para>
</listitem>
</orderedlist>

<para>Benefits are that you don&rsquo;t need to write a Scheme module or a new C
routine to do this transformation. Anyone who knows or can learn <acronym>XML</acronym>
and <acronym>XSLT</acronym> can perform this task. Not much harder, really, than writing a
Web page....</para>

<para>Anyhow, I just wanted this tidbit to be captured somewhere permanently.
The process works on &vers-stable; datafiles, and ought to
work on earlier versions, too.</para>

</sect1>

</appendix>
</para>
</important>

<note>
<para>You can put pretty much anything you want behind the equal signs, but a unique
<acronym>URL</acronym> is what is typically used.
</para>
</note>
</listitem>

<listitem>
<para>Create an <acronym>XSLT</acronym> stylesheet containing the transformation your desire, or obtain
one that&rsquo;s already written.
</para>

<itemizedlist>
<title>User Contributed XSLT Stylesheets</title>

<listitem>
<para>in our repository: <ulink url="&url-src-maint;contrib/xslt"></ulink>
</para>
</listitem>

<listitem>
<para>in our wiki: <ulink url="&url-wiki-xslt;"></ulink>
</para>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para>Install an <acronym>XSLT</acronym> processor such as Saxon (<ulink url="&url-wp-en;Saxon_XSLT" />)
or Xalan (<ulink url="&url-wp-en;Apache_Xalan" />). Any
<ulink url="&url-wp-en;Category:XSLT_processors">conforming processor</ulink> will do,
really...
</para>
</listitem>

<listitem>
<para>Run the work file and the stylesheet through the processor according to the processor&rsquo;s
instructions.
</para>
</listitem>

<listitem>
<para>You will now have a file in the desired output format. An enterprising individual could go so far as
to write a stylesheet to transform the &app; data file to an OpenOffice spreadsheet (or
vice-versa, for that matter). Such things as <acronym>QIF</acronym> ought to be a little
less work.
</para>
</listitem>
</orderedlist>

<para>Benefits are that you don&rsquo;t need to write a Scheme module or a new C routine to do this
transformation. Anyone who knows or can learn <acronym>XML</acronym> and
<acronym>XSLT</acronym> can perform this task. Not much harder, really, than writing a Web
page....
</para>

<para>Anyhow, I just wanted this tidbit to be captured somewhere permanently. The process works on
&vers-stable; datafiles, and ought to work on earlier versions, too.
</para>
</sect1>
</appendix>

0 comments on commit 47e0514

Please sign in to comment.