Re: [python] [patch] set/show extended-prompt

[Phil Muldoon <pmuldoon at redhat dot com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Phil Muldoon <pmuldoon@redhat.com>
>> Date: Thu, 11 Aug 2011 16:06:45 +0100
>> 
>> 
>> This patch adds extended-prompt capabilities to GDB.  In addition it
>> adds a prompt substitution library.  I made the extended-prompt lazily
>> control the prompt_hook on setting, over controlling it unconditionally.  The
>> rest of the function remains the same other than in-Python documentation
>> as was found in Archer.
>
> Thanks, I have a few comments about the documentation part:
>
>> +@xref{gdb.prompt} for a list of the flags that can be used for
                     ^
> If you run "make info", it will complain here, because you need to add
> a comma after the right brace.

I normally run 'make info', but my preferred method of proof-reading is
to generate a PDF with 'make pdf'.  This time it looks like I forgot to
sanity check with 'make info', apologies for that.  BTW, it does not
error with 'make pdf', but good point, will adjust.


>> +               The prompt is updated with the value of the
>> +flags each time it is displayed.
>
> Is "flags" a good term?  I think "escape sequence" is better, e.g.:
>
>   Any escape sequences specified as part of the prompt string are
>   replaced with the corresponding strings each time the prompt is
>   displayed.

One of the flags is a specific escape (/e), so I worried about collision
with that term.  That is why ended up using flags.  I'm have no strong
opinions on terminology here, so I will go with what your suggest.

>> +@smallexample
>> +substitute_prompt (``frame: \f, print arguments: \p@{print frame-arguments@}'')
>> +@end smallexample
>
> The line inside @example should be broken into two, as it is too long.

I'm never sure how to break up function examples like these for the
documentation (other than making a smaller example).  Any suggestions on
where to include the break?

>> +@smallexample
>> +``frame: main, print arguments: scalars''
>> +@end smallexample
>
> Aren't these ``..'' quotes left verbatim in the printed version of the
> manual?  I think you need literal ".." quotes here, since they are not
> converted inside @smallexample.

Yes, you are right.  I relied on the emacs Texinfo major mode to do the
right thing here, but I guess it does not in the context of
@smallexample.  When you mean literal quotes, do you mean just pasting
in '"'?

Cheers,

Phil