Texinfo and error messages

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Texinfo and error messages

Mike Miller-4
Hi,

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.

Thoughts?

[1]: https://github.com/catch22/octave-doctest/issues/238
[2]: https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040error.html

--
mike

texinfo-error.patch (3K) Download Attachment
signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Texinfo and error messages

Colin Macdonald-2
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

Reply | Threaded
Open this post in threaded view
|

Re: Texinfo and error messages

Mike Miller-4
On Wed, Oct 02, 2019 at 18:18:43 -0700, Colin Macdonald wrote:
> I think *any* of those choices are better than using @result/nothing...

I agree.

> 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?)
Right, the typographic conventions are part of Texinfo itself, no
customization. I don't really like the "error→" rendering, it's
especially bad for multi-line errors as you've shown.

Using @print seems preferable for multi-line errors, even if we can't
have it in red. And if we prefer @print for multi-line errors, shouldn't
we also use it for one-line errors to be consistent?

--
mike

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Texinfo and error messages

Colin Macdonald-2
On 2019-10-03 9:35 a.m., Mike Miller wrote:
> Using @print seems preferable for multi-line errors, even if we can't
> have it in red. And if we prefer @print for multi-line errors, shouldn't
> we also use it for one-line errors to be consistent?

Unfortunately I agree with you ;-)

Colin