[Top][All Lists]

[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→   syntax 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?)


reply via email to

[Prev in Thread] Current Thread [Next in Thread]