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: DocumentationSeverity: 5 - Average
Status: NoneAssigned to: None
Open/Closed: OpenRelease: None
Effort: 0.00

Add a New Comment (Rich MarkupRich 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 File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

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

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

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    No Changes Have Been Made to This Item

    Back to the top


    Powered by Savane 3.1-cleanup