PSPP-BUG: [bug #36747] The command synopsis notation is confusing for users.

[John Darrington]

URL:
  <http://savannah.gnu.org/bugs/?36747>

                 Summary: The command synopsis notation is confusing for
users.
                 Project: PSPP
            Submitted by: jmd
            Submitted on: Fri 29 Jun 2012 10:48:09 CEST
                Category: Documentation
                Severity: 5 - Average
                  Status: None
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
                 Release: None
                  Effort: 0.00

    _______________________________________________________

Details:

Many users appear to be confused by the notation used in the user manual to
describe the syntax of procedures.  Eg:

  ADD FILES

     Per input file:
             /FILE={*,'FILE_NAME'}
             [/RENAME=(SRC_NAMES=TARGET_NAMES)...]
             [/IN=VAR_NAME]
             [/SORT]

     Once per command:
             [/BY VAR_LIST[({D|A})] [VAR_LIST[({D|A})]...]]
             [/DROP=VAR_LIST]
             [/KEEP=VAR_LIST]
             [/FIRST=VAR_NAME]
             [/LAST=VAR_NAME]
             [/MAP]

It is not obvious, to a non-computer scientist, what is to be interpreted
literally, and what should not be.
Although there is a Section in Chapter 6 entitled "Backus-Naur Form" this does
not explain, for example, that [...] indicates optional construction.  And
anyway, most readers do not notice this section in the manual.






    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?36747>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/