Re: Opinions on look of documentation

[Nicholas Jankowski]

On Fri, Dec 11, 2015 at 1:57 PM, Rik <address@hidden> wrote:

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

Assuming the in-program documentation will look like the help output, I do like the -- as it makes it easier for the eye to catch separation between functions/commands. The : is a little odd there, but not so much that it's a problem. I was actually wondering if there was a way to add a more noticeable separation between functions in the PDF...