Special characters in doc strings of GDB commands

Special characters in doc strings of GDB commands

[Eli Zaretskii]

I see in cli-decode.c:print_doc_line that it displays the first line
only up to the first comma or period.  However, I don't see this
special treatment of these two characters documented anywhere, neither
in gdb.texinfo (where it matters for doc strings given to user-defined
commands), nor in gdbint.texinfo (where it is important for GDB
developers who add new commands).

Am I missing something?

Btw, should we have a mechanism to escape these special characters, at
least the comma?  Sometimes a sentence looks very awkward or even
unclear unless you use a comma.

Re: Special characters in doc strings of GDB commands

[Daniel Jacobowitz]

On Fri, Jan 19, 2007 at 01:36:56PM +0200, Eli Zaretskii wrote:
> I see in cli-decode.c:print_doc_line that it displays the first line
> only up to the first comma or period.  However, I don't see this
> special treatment of these two characters documented anywhere, neither
> in gdb.texinfo (where it matters for doc strings given to user-defined
> commands), nor in gdbint.texinfo (where it is important for GDB
> developers who add new commands).
> 
> Am I missing something?

Not as far as I know.

> Btw, should we have a mechanism to escape these special characters, at
> least the comma?  Sometimes a sentence looks very awkward or even
> unclear unless you use a comma.

Isn't this whole mechanism horribly i18n-unfriendly already?  Perhaps
we should just change it...

-- 
Daniel Jacobowitz
CodeSourcery

Re: Special characters in doc strings of GDB commands

[Eli Zaretskii]

> Date: Sat, 10 Feb 2007 15:47:29 -0500
> From: Daniel Jacobowitz <drow@false.org>
> Cc: gdb@sources.redhat.com
> 
> Isn't this whole mechanism horribly i18n-unfriendly already?  Perhaps
> we should just change it...

But how to change that?  Any ideas?

Re: Special characters in doc strings of GDB commands

[Daniel Jacobowitz]

On Sun, Feb 11, 2007 at 06:13:34AM +0200, Eli Zaretskii wrote:
> > Date: Sat, 10 Feb 2007 15:47:29 -0500
> > From: Daniel Jacobowitz <drow@false.org>
> > Cc: gdb@sources.redhat.com
> > 
> > Isn't this whole mechanism horribly i18n-unfriendly already?  Perhaps
> > we should just change it...
> 
> But how to change that?  Any ideas?

I haven't thought about it.  Probably we'd have to add an additional
argument to everywhere that registers a command, to provide the string
explicitly.  I'm not thrilled with the idea of duplicating that much
text though!

-- 
Daniel Jacobowitz
CodeSourcery

Re: Special characters in doc strings of GDB commands

[Daniel Jacobowitz]

On Sun, Feb 11, 2007 at 06:13:34AM +0200, Eli Zaretskii wrote:
> > Date: Sat, 10 Feb 2007 15:47:29 -0500
> > From: Daniel Jacobowitz <drow@false.org>
> > Cc: gdb@sources.redhat.com
> > 
> > Isn't this whole mechanism horribly i18n-unfriendly already?  Perhaps
> > we should just change it...
> 
> But how to change that?  Any ideas?

I haven't thought about it.  Probably we'd have to add an additional
argument to everywhere that registers a command, to provide the string
explicitly.  I'm not thrilled with the idea of duplicating that much
text though!

-- 
Daniel Jacobowitz
CodeSourcery

Re: Special characters in doc strings of GDB commands

[Eli Zaretskii]

> Date: Sun, 11 Feb 2007 13:08:55 -0500
> From: Daniel Jacobowitz <drow@false.org>
> 
> I haven't thought about it.  Probably we'd have to add an additional
> argument to everywhere that registers a command, to provide the string
> explicitly.  I'm not thrilled with the idea of duplicating that much
> text though!

Right.  Another possibility would be to enclose the short description
part in some control sequence, which will be stripped by the commands
that print the doc strings.  For example, like makeinfo uses ^[..^]
for similar purposes.

Re: Special characters in doc strings of GDB commands

[Eli Zaretskii]

> Date: Sun, 11 Feb 2007 13:08:55 -0500
> From: Daniel Jacobowitz <drow@false.org>
> 
> I haven't thought about it.  Probably we'd have to add an additional
> argument to everywhere that registers a command, to provide the string
> explicitly.  I'm not thrilled with the idea of duplicating that much
> text though!

Right.  Another possibility would be to enclose the short description
part in some control sequence, which will be stripped by the commands
that print the doc strings.  For example, like makeinfo uses ^[..^]
for similar purposes.

Re: Special characters in doc strings of GDB commands

[Daniel Jacobowitz]

On Sun, Feb 11, 2007 at 10:17:25PM +0200, Eli Zaretskii wrote:
> Right.  Another possibility would be to enclose the short description
> part in some control sequence, which will be stripped by the commands
> that print the doc strings.  For example, like makeinfo uses ^[..^]
> for similar purposes.

I guess that's better for translation purposes (tell translators to
leave those untranslated)?  It still seems problematic, e.g. if the
natural phrasing of the long descripton doesn't have the short
description as a substring.

-- 
Daniel Jacobowitz
CodeSourcery

Re: Special characters in doc strings of GDB commands

[Jim Blandy]

Daniel Jacobowitz <drow@false.org> writes:
> On Fri, Jan 19, 2007 at 01:36:56PM +0200, Eli Zaretskii wrote:
>> I see in cli-decode.c:print_doc_line that it displays the first line
>> only up to the first comma or period.  However, I don't see this
>> special treatment of these two characters documented anywhere, neither
>> in gdb.texinfo (where it matters for doc strings given to user-defined
>> commands), nor in gdbint.texinfo (where it is important for GDB
>> developers who add new commands).
>> 
>> Am I missing something?
>
> Not as far as I know.
>
>> Btw, should we have a mechanism to escape these special characters, at
>> least the comma?  Sometimes a sentence looks very awkward or even
>> unclear unless you use a comma.
>
> Isn't this whole mechanism horribly i18n-unfriendly already?  Perhaps
> we should just change it...

My understanding is that the first line should be a self-contained
summary.  If there is additional text on the first line, it should be
moved onto the second line.  Then, print_doc_line could stop at the
line break.