Re: Opinions on look of documentation

[Rik]

On 12/11/2015 01:12 PM, John W. Eaton wrote:
> On 12/11/2015 01:57 PM, Rik wrote:
>
>> 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.
>
> I think the ":" looks a little funny there.  I would like it better if if
> it only displayed the leading "--", like this:
>
>   -- ls
>   -- ls FILENAMES
>   ...
>
> though even that might be confusing to some people.  I don't konw.

It is Texinfo that is placing the ':' in the output.  To code this properly
would require creating our own @defXXX command in texinfo.tex which would
probably require us to ship that file with the distribution.  We used to do
that up until version 4.0.

>
> If it is not possible to configure makeinfo to display this way, I guess
> we could fix that with a sed filter.

We could hack it externally in sed, or with regexprep in Octave which might
be more portable.  The command help is used interactively so I don't think
performance is an issue (it operates on a slow human time scale).

>
> Also, why the extra space before "ls..." vs. "LIST..."?  Where is that
> coming from?

Also Texinfo.  This might be fixable if we manipulate the texinfo.tex file.
 
>
>> Alternatively, we
>> could fall back to using @deftypefun which would set the type field to
>> "Function".
>
> Doesn't that also put the "[Function]" tag in the PDF file?
>
Yes it would.

--Rik