[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Texinfo and error messages
From: |
Colin Macdonald |
Subject: |
Re: Texinfo and error messages |
Date: |
Wed, 2 Oct 2019 18:18:43 -0700 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.1.0 |
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