On Fri, Nov 01, 2024 at 10:38:17AM +0100, R. Diez wrote:
> There are also other Overfull warnings like this:
>
> Overfull \hbox (20.85455pt too wide) in paragraph at lines 2141--2141
> []@texttt lappend post_init_commands {echo "OpenOCD successfully
> initialized."
> }[] |
>
> Just search for "OpenOCD successfully initialized" in the example PDF linked
> near the top of this e-mail to see the effect.
>
> These are the related .texi lines:
>
> @example
> lappend post_init_commands @{echo "OpenOCD successfully initialized."@}
> lappend post_init_commands @{echo "Have fun with OpenOCD !"@}
> @end example
>
> This is a different issue. The OpenOCD manual wants to give examples of
> commands or console outputs with long text lines which will often not fit on
> a printed page. Such commands should not be broken up like normal text,
> because the reader must have a sense of what words belong to a single command
> line or console output line. What is the best strategy to display such long
> commands in a Texinfo user manual?
>
I see in the document the @example is nested inside the definition of
"init" (a "Config Command"). This leads to more indentation of the
environment. Consider reorganizing this part of the manual
to put the @example outside of the definition.
You could give more space using
@exampleindent 0
before the @example environment.
One way is to use @smallexample instead of @example which would use a
smaller font and allow more characters on a line.
You could also look for ways to break the line. I don't know the
syntax of the language in question. Would something like the following
be appropriate?
@example
lappend post_init_commands @{
echo "OpenOCD successfully initialized."
@}
lappend post_init_commands @{
echo "Have fun with OpenOCD !"
@}
@end example
Are there line continuation characters, like \ in bash, that could be
used? Like this:
@example
lappend post_init_commands @{ \
echo "OpenOCD successfully initialized." @}
lappend post_init_commands @{ \
echo "Have fun with OpenOCD !" @}
@end example
Another idea is to use a prompt character at the beginning of input
so that a line missing this prompt character is likely to be a
continuation of the previous line:
@example
> lappend post_init_commands @{ \
echo "OpenOCD successfully initialized." @}
> lappend post_init_commands @{ \
echo "Have fun with OpenOCD !" @}
@end example
There might also be a continuation prompt:
@example
> lappend post_init_commands @{ \
+ echo "OpenOCD successfully initialized." @}
> lappend post_init_commands @{ \
+ echo "Have fun with OpenOCD !" @}
@end example
It appears that the manual uses @smallbook size which means lines have
to be shorter.
