bugPSPP - Bugs: bug #36747, The command synopsis notation is...

 
 

bug #36747: The command synopsis notation is confusing for users.

Submitter:  John Darrington <jmd>
Submitted:  Fri 29 Jun 2012 08:48:09 AM UTC
   
 
Category:  Documentation Severity:  5 - Average
Status:  None Assigned to:  None
Open/Closed:  Open Release:  None
Effort:  0.00
* Mandatory Fields

Add a New Comment Rich Markup
   

Fri 29 Jun 2012 08:48:09 AM UTC, original submission:  

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.


John Darrington <jmd>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by jmd (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    No changes have been made to this item

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code