Re: [bug-recutils] Work needed in the user manuals

[John Darrington]

I've raed through the manual and have the following comments:

1. It would not hurt to run it through a spell checker.  There are a
    number of typos.

2. I couldn't find the word "escalar" in any English dictionary.  Should
   this read "scalar" or is it some specialist terminology which is supposed
   to be familiar to the readership?

3. The word "sensible" is used several times inapproriately.  "Sensible" is 
   NOT the same as the German "sensibel"!!  I think you mean "sensitive".

4. I recommend that all the chapters whose names begin with %  be retitled, 
   to something more descriptive.

5. Like you say, the chapters descibing the tools are very terse and read like 
a 
   reference rather than a tutorial.   I recommend that these chapters be 
   made into an appendix, and in their place three or four new tutorial type 
   chapters:

   "Retrieving your data" - covering the use of recinf, recsel and recfmt
   "Entering data" -- covering recins
   "Editing entries" -- covering recset and recdel (maybe recfix too)
   "Importing and Exporting" -- all the rec2* utilities.

6. There is no index.  The manual is big enough that it could use one.

On Tue, Jul 24, 2012 at 01:10:12PM +0200, Jose E. Marchesi wrote:
     
     Hi John.
     
     The GNU Recutils user manual lives in the file doc/recutils.texi.  The
     problems we currently have with this manual are mainly two:
     
     - The manual is incomplete and does not currently cover some of the new
       facilities that will go in 1.6.  The list of not covered functionality
       is:
     
       + Grouping (option -G|--group-by to recsel).  There is a section
       called "recsel Grouping" which I started, but it is not finished.
     
       + The aggregated functions.  This would ideally go in a dedicated
       section after the section on grouping.
     
       + Joins.  We would need a section "recsel Joins" or something.
     
     - Some people complained about the manual not being tutorial-like
       enough, meaning that it is difficult to get started in using the
       tools.  It would be probably good to re-structure it.
     
     Additionally, the Emacs mode rec-mode.el is now getting stable and
     better.  I started a skeleton of a manual for the mode at
     doc/rec-mode.texi, but we need to write it down.
     
     -- 
     Jose E. Marchesi         http://www.jemarch.net
     GNU Project              http://www.gnu.org

-- 
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://keys.gnupg.net or any PGP keyserver for public key.

signature.asc
Description: Digital signature