Patch for guide file "ch_basics.xml"

Cristian Marchi cri79 at libero.it
Wed Oct 13 14:57:48 EDT 2010


Thanks Geert for taking the time to review my changes.

Il 13/10/2010 17:56, Geert Janssens ha scritto:
> 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".
>
>    
Ok!

> @@ -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 ?
>
>    
These are leftovers. I've added them while writing in the case I wanted 
to add later a title but forgot them.


@@ -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.
>    
I agree with the fact that this section superflous. Moreover if it 
doesn't work anymore.

> * the descriptions for the two summary bar options refer to a "report", but
> shouldn't they refer to the "summary bar" ?
>    
You are right. I will check what the tooltips says!

> * 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.
>    
Ok!

> * 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."
>    
Ok! I will check throught the xml file for the word "dialog" and I will 
substitute it.
> * 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."
>    
Ok
> * 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).
>    
Ok! It was in my intentions to write something about the new file 
formats but I don't know enough about them.
For now I will only specify in the text that this option works only when 
saving in xml format.

> * 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.
>    
Ok, I will add a little introduction to this section

> * 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.
>
>    
Yes, your description is better.


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

> * 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."
>    
ok!

> * @@ -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.
>    
So, a section explaining a little about file format is essential!

> * 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.
>    
Ok! I've noticed this behavoir on my GnuCash files.

> * 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.
>    
In the next days I will commit the file with the smaller changes. Then I 
will add the bigger ones and I will send back the diff for review.

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


More information about the gnucash-devel mailing list