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

 
 

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

Submitted by:  John Darrington <jmd>
Submitted on:  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

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

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>
Project 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)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    No changes have been made to this item

    Back to the top


    Powered by Savane 3.5