Re: Texinfo and error messages

[Colin Macdonald]

On 2019-10-02 4:36 p.m., Mike Miller wrote:
> The topic of how to format error messages in Texinfo example blocks came
> up in a separate discussion [1]. I looked into it, and found that
> Texinfo has a @error macro for this purpose [2]. But I also found that
> Octave doesn't use it, and instead uses @print, @result, or sometimes
> nothing, in @example blocks in function docstrings and the user manual.
>
> Should we use the @error macro? Or should we standardize on another
> convention? Here are a few possible choices, in no particular order.
>
>    @print{} error: sqrt: argument must be numeric
>
>    @error{} error: sqrt: argument must be numeric
>
>    @error{} sqrt: argument must be numeric
>
> Attached is a patch that applies the second choice above in a few
> places. I actually prefer the third option, since the rendered output
> "error→ error: ..." seems redundant. But maybe the first option is even
> better for our purposes.

I think *any* of those choices are better than using @result/nothing...

For short one-line errors, I like the third option too, with option two 
used in specific cases (when the error message does not begin with the 
word "error").  E.g.,
```
>> 1 + (1 + 1))
error→ parse error:
```

Counterpoint: suppose we wanted to show *all* of the syntax error 
message in some docs; it would look like:
```
error→ parse error:
error→
error→   syntax error
error→
error→ >>> 1 + (1 + 1))
error→                ^
```
That's quite a wall!  If I can have a pony, I'd ask for @error to make 
output like @print, but with the "⊣" symbol rendered in red:

```
⊣ parse error:
⊣
⊣   syntax error
⊣
⊣ >>> 1 + (1 + 1))
⊣                ^
```
But I don't think we get that level of control (right?)

best,
Colin