Opinions on look of documentation

[Rik]

12/11/15

All,

One of the changes for 4.2 will be to remove the "type" of function from
the documentation.  Currently the "type" might be something like "Function
File", "Mapping Function", "Command", "Loadable Function", etc.  The
current documentation displayed by 'help ls' is.

 -- Command:  ls
 -- Command:  ls FILENAMES
 -- Command:  ls OPTIONS
 -- Command:  ls OPTIONS FILENAMES
 -- Function File: LIST = ls (...)
     List directory contents.

     The `ls' command is implemented by calling the native operating
     system's directory listing command--available OPTIONS will vary
     from system to system.

The simplest change in the code is to blank out the type field.  After that
change, 'help ls' looks like

 -- :  ls
 -- :  ls FILENAMES
 -- :  ls OPTIONS
 -- :  ls OPTIONS FILENAMES
 -- : LIST = ls (...)
     List directory contents.

     The `ls' command is implemented by calling the native operating
     system's directory listing command--available OPTIONS will vary
     from system to system.

Is it too weird to have '-- :' as the leading characters?  This is only an
issue for the on-screen help.  The pdf looks fine in my opinion.  I've
attached ls.pdf as an example of what that looks like.  Alternatively, we
could fall back to using @deftypefun which would set the type field to
"Function".  This gives

 -- Function:  ls
 -- Function:  ls FILENAMES
 -- Function:  ls OPTIONS
 -- Function:  ls OPTIONS FILENAMES
 -- Function: LIST = ls (...)
     List directory contents.

     The `ls' command is implemented by calling the native operating
     system's directory listing command--available OPTIONS will vary
     from system to system.

Which one do people like better?

--Rik

ls.pdf
Description: Adobe PDF document