[PATCH 1/2] Bug #632244: Guide

[Yawar Amin]

Hi Cristian,

First off, that was a huge effort on your part. I’m in awe :-)

Second, sorry about taking so long with this. What happened was I couldn’t find a good way to review the patch in BugZilla as there are specific lines I want to comment on. I thought about putting it up on my GitHub clone and using the really cool line-by-line commenting tool there, but that would be introducing yet another complexity into the patch review process. So I finally decided to post it here as the best way to keep everything in the GnuCash archives. I know my mail client doesn’t wrap lines, so it shouldn’t be too horrible :-)

Review below, followed by second email with second patch.

Regards,

Yawar

diff --git a/guide/C/ch_basics.xml b/guide/C/ch_basics.xml
index 20a1426..0d7825f 100644
--- a/guide/C/ch_basics.xml
+++ b/guide/C/ch_basics.xml
[…]
@@ -2077,8 +961,9 @@
     <note>
         <para>As it is very important to save your data frequently to avoid loosing them for whatever reason,
         <application>&app;</application> is able to automatically save the opened file every a certain amount of time.
-        This interval can be set in the <link linkend="basics-general2">General</link> tab under 
-        <interface>Preferences</interface>. Keep in mind that this option is relevant only if you are saving in xml format.
+        This interval can be set in the <guilabel>General</guilabel> tab under 
+        <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>. 
+        Keep in mind that this option is relevant only if you are saving in xml format.

I recommend we use <acronym>XML</acronym> here and with other acronyms we have throughout the docs. We may not have much styling on them now but in future we may be able to style them with e.g. small caps. I’m not saying we should go out and change everything right now, but we can use them every time we add some text and make more changes later.

         If you are working with a database the <guibutton>Save</guibutton> button and the <guimenuitem>Save</guimenuitem>
         menu entry will be grayed out because changes are stored right away.</para>
     </note>
@@ -2086,21 +971,14 @@
     <para>To open an existing file, select <menuchoice><guimenu>File</guimenu>
     <guimenuitem>Open</guimenuitem></menuchoice> from the menu and choose your file from the list.</para>
 
-    <sect2 id="basics-file-ext2">
-      <title>The <filename>.gnucash</filename> Extension</title>
-
-      <para><application>&app;</application> stores its data with the
-      extension <filename>.gnucash</filename>.</para>
-
-      <para>The <filename>.gnucash</filename> extension was chosen as the
-      default during development of the 2.3 unstable series of
-      <application>&app;</application>. For already existing files, the
-      extension will never be changed. So if you open an existing file
-      named <filename>Myoldfile</filename>, that name won't be changed if
-      the file is saved. You might use the <guimenuitem>Save
-      As...</guimenuitem> command and give the file a new name in order to
-      have it saved with the extension
-      <filename>.gnucash</filename>.</para>
+    <para><application>&app;</application> is storing its data with the extension <filename>.gnucash</filename>.</para>

Um, sorry to be a grammar stickler, but I really want to use the infinitive (‘stores’) instead of present (‘is storing’) tense here. The latter is the more general form.

+      <note>
+        <para>The <filename>.gnucash</filename> extension was introduced with version 2.4 of <application>&app;</application>.

This isn’t totally accurate, but I guess the question is, will most readers care? Some might. How about we say ‘… introduced in the 2.3 series …’?

+        For already existing files, the extension will never be changed. So if you open an existing file named 
+        <filename>Myoldfile</filename>, that name won't be changed if the file is saved. You might use the 
+        <guimenuitem>Save As...</guimenuitem> command and give the file a new name in order to have it saved with the 
+        extension <filename>.gnucash</filename>.</para>
+      </note>
     
     <para>If you name your <application>&app;</application> file to <filename>MyBudget</filename>, the actual file name
     will be <filename>MyBudget.gnucash</filename></para>
[…]
@@ -2275,12 +1152,10 @@
       name.</para>
       
       <note>
-        <para>Remember from <xref linkend="basics-file-ext2"/> that the
-        default <application>&app;</application> file extension is
-        <filename>.gnucash</filename>. So if you upgrade from the 2.2
-        series to the 2.4 series, you may end up with both
-        <filename>.xac</filename> and <filename>.gnucash</filename> backup
-        files in your directory.</para>
+        <para>Starting from version 2.4 <application>&app;</application> does not create anymore
+        backup files with the extension <filename>.xac</filename> but with the extension 
+        <filename>.gnucash</filename>. So if you upgrade from <application>&app;</application> version 
+        2.2.x to 2.4 you may end up with both xac and gnucash backup files in your directory.</para>

Same as before about the 2.4 version file name. Also want to rearrange the sentence structure a bit. I recommend we say:

<para><application>&app;</application> 2.4 onwards creates backup files with the extension <filename>.gnucash</filename> instead of the old extension <filename>.xac</filename>. So if you upgrade from the 2.2 series to the 2.4 series, you may end up with both <filename>.xac</filename> and <filename>.gnucash</filename> backup files in your directory.</para>

       </note>
     </sect2>
 
[…]
diff --git a/guide/C/ch_currency.xml b/guide/C/ch_currency.xml
index 966a537..3e773a0 100644
--- a/guide/C/ch_currency.xml
+++ b/guide/C/ch_currency.xml
@@ -130,25 +130,24 @@ Note: the currency of each account is shown in parenthesis.
 
     <itemizedlist>
       <listitem>
-        <para>Default currency you want the newly created registers to
-        have</para>
+        <para><guilabel>Default Currency</guilabel> for accounts in the <guilabel>Accounts</guilabel> tab 
+        under <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice></para>
       </listitem>
 
       <listitem>
-        <para>Default currency for the reports</para>
+        <para><guilabel>Default Report Currency</guilabel> in the <guilabel>Reports</guilabel> tab 
+        under <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice></para>
       </listitem>
 
       <listitem>
-        <para>Date and Time formats</para>
+        <para><guilabel>Time Format</guilabel> and <guilabel>Date Format</guilabel> in the <guilabel>Date/Time</guilabel> tab 
+        under <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice></para>
       </listitem>
 
-      <listitem>
-        <para>Euro support</para>
-      </listitem>
     </itemizedlist>
 
-    <para>For a full explanation of the International Preferences available,
-    see <xref linkend="basics-prefs1" /></para>
+    <para>For a full explanation of the International preferences available,
+    see the <application>&app;</application> manual</para>

Let’s make this: see the <application>&app;</application> Help Manual.</para>
   </sect1>
 
   <sect1 id="currency_howto1">
-- 
1.7.0.2

-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 194 bytes
Desc: This is a digitally signed message part
URL: <http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20101031/d53d4af3/attachment.bin>