Patch for guide file "ch_basics.xml"

[Geert Janssens]

On Tuesday 12 October 2010, Cristian Marchi wrote:
> I attach the diff for the "ch_basics.xml" guide file. I've reviewed the
> entire document and I've corrected some typo. The majority of works went
> in updating the "Preferences" chapter.
> I've also added, where applicable, the structure for menu, submenu and
> menuitem (e.g.
> <menuchoice><guimenu>File</guimenu><guisubmenu>Import...</guisubmenu><guime
> nuitem>Import QIF</guimenuitem></menuchoice>).
> 
> My English is not perfect so it's (very) possible that I made some mistake.
> 
> If I don't get any comments, in the week-end I'll commit the changes.
> 
> Thanks
> Cristian
> 
Good work Cristian!

Below you will find some corrections. Some are small mistakes due to your 
changes, other are proposals to improve the wording in some cases. I realize 
that many of the proposals are for texts that were there before, and not based 
on your changes. But since you are working on that chapter now, we might as 
well add additional improvements, I thought. And note that I'm not a native 
English speaker either, so I may make mistakes as well...

And perhaps the text improvements should be committed separately from your 
current reorganizing ?

@@ -680,10 +680,10 @@
       allows you to have as many account registers open as you wish.</para>
 
       <para>At the top of this window is the title bar, which displays the
-      file name (once you have saved the file.) Below that is the menu bar.
+      file name (once you have saved the file.) Below there is the menu bar.
       You can access the menu options by either clicking on these menu
-      headings or by using shortcuts and access key combinations, covered
-      later in this chapter. Next is the tool bar, which contains buttons
+      headings or by using shortcuts and access key (see <xref 
linkend="basics-shortcut2" />. 
+      Next is the tool bar, which contains buttons
       for the most common functions.</para>

I believe the first change is not correct. With my knowledge of English, it 
should remain "Below that is the menu bar."

In the second change I think "access key" should be "access keys".


@@ -737,11 +737,14 @@
       account register window,
       information appears about the current location of the cursor.</para>
       
-      <para>You can resize the various columns that 
<application>&app;</application> displays, but keep
-      in mind that the description column will automatically expand to fill 
all unused
+      <note>
+      <title></title>
+      <para>In the register windows, you can resize the various columns that 
+        <application>&app;</application> displays, but keep in mind that 
+        the description column will automatically expand to fill all unused
         space.  Therefore you should increase the size of all your other 
columns
-        first and then decrease the size of the description column.
-      </para>
+        first and then decrease the size of the description column.</para>
+      </note>
You have added an empty title tag in this note. You do the same later on in 
other notes. Just out of curiosity, is that required or your preference ?

@@ -827,17 +830,22 @@
This section talks about custom shortcuts. I am not 100% sure, but I don't 
think this is still possible with "recent" gnome versions. There exists still 
a control panel for Keyboard shortcuts [1], but it can't be used to change 
application shortcuts. I haven't found a gnome tool to do so easily. And even 
if such a tool still exists, I think it's outside the scope of a GnuCash 
manual to explain the exotic uses of the gnome desktop. So in my opinion this 
section is perhaps best removed altogether.

* the descriptions for the two summary bar options refer to a "report", but 
shouldn't they refer to the "summary bar" ?

* Start Date -> proposal: "This item sets the accounting period's start date. 
This date can subsequently be used by the GnuCash reports. You can choose 
between..."
Perhaps you can add a link to the concepts guide section on reports also.
The same suggestion goes for the End Date of course.

* Display "tip of the day" -> proposal "This option displays or hides the 
<interface>Tip of the Day</interface> screen when 
<application>&app;</application> is started."
I remember a bugreport created by Stormy in which she explains that the word 
"dialog" means nothing to an ordinary user. "Screen" was proposed as 
alternative word.

* Similar for "Show splash screen" -> "This option displays or hides the 
startup screen while <application>&app;</application> is starting up."

* Perform account list setup on new file -> proposal: "This option enables or 
disables the <interface>New Account Hierarchy Setup</interface> assistant when 
the entry <menuchoice><guimenu>File</guimenu><guimenuitem>New 
File</guimenuitem></menuchoice> is selected from the menu."

* Compress files: I would add here that the option is only relevant for files 
in xml format. (Remember that 2.4 will have support for xml, sqlite, mysql en 
postgresql).

* Print section. The sections in your text don't make it clear these settings 
are specific to check printing. They don't apply to for example report 
printing. Perhaps some text to clarify this should be added.

* Since Last Run Dialog - Run when data file is opened. I think the 
description for this item is incorrect. If checked, the Since Last Run Dialog 
is run when a file is opened. If unchecked, this dialog is only run when a 
user selects it from the Actions -> Scheduled Transactions -> Since Last 
Run... menu.

* Bring the most recent tab to the front: "showed" should be "shown"

* Width -> proposal: "The width of a tab expressed in characters." So I'd 
remove the "Insert in the field" part. This seems more consistent with other 
text entry fields and makes the text easier to read.

* Tab position -> proposal: "Position the tabs at the <guilabel>Top</guilabel> 
(default), <guilabel>Bottom</guilabel>, <guilabel>Left</guilabel> or 
<guilabel>Right</guilabel> of the <application>&app;</application> main 
window."

* Summary Bar position -> proposal: "Position the summary bar at the 
<guilabel>Top</guilabel> or <guilabel>Bottom</guilabel> (default) of the 
<application>&app;</application> main window."

* @@ -1681,20 +1907,29 @@
This is a section that says saving files regularly is important. Should this 
section be rewritten with the new backends in mind ? If any of the db backends 
is chosen, the save button is disabled, because changes are saved right away. 
If that is not well documented, I think we will see quite a lot of worried 
mails on the list or bug reports in bugzilla.

Similarly the auto save feature is only relevant for gnucash files in xml 
format.

* About file extensions: it is correct that new files get the file extension 
".gnucash". For already existing files, the extension will never be changed. 
So if the user opens a file named "Blurb", that name won't be changed if the 
file is saved. Perhaps it is useful to add a note in the guide that the 
.gnucash file extension is new since 2.4, that older gnucash versions didn't 
enforce a file extension (although .xac was considered the default) and that 
these files can still be opened with 2.4.

* Similarly, the guide talks about .xac files a bit further on under "File 
management". This refers to the backup files GnuCash creates. Prior to 2.3.x 
they all got extension .xac, but in 2.4 they will also have extension 
.gnucash. So if you upgrade from 2.2.x to 2.4, you may end up with both .xac 
and .gnucash backup files. (In fact, the extension itself is not what suggests 
a backup file, but rather the timestamp in the filename).
I think this section also could use a note to explain that 2.2.x did things 
slightly differently from 2.4.

* And the thing about backup and log files is only valid for xml based GnuCash 
files. It doesn't apply to any of the db based GnuCash "files".

That's it for me.

As far as I'm concerned, you can commit the patch (with the small errors I 
pointed out fixed). The text proposals can be added immediatly if you like 
them or we can discuss them further for another commit.

Geert

[1] http://library.gnome.org/users/user-guide/2.30/prefs-keyboard-
shortcuts.html.en