[Ltrace-devel] Addition to the manpage

[Dima Kogan]

Petr Machata <pmachata at redhat.com> writes:

> Dima Kogan <lists at dima.secretsauce.net> writes:
>
>> Hi. I added a section to the manpage giving an example of the effects of
>> -l, -x and -e. It's here:
>>
>>  https://github.com/dkogan/ltrace/tree/manpage
>
> This looks good.  I wonder about the effect of grep in there--that only
> filters the exit messages, doesn't it?  I think it would be better to
> have them included and not have the grep there, so that it doesn't look
> as if it's hiding something important.

The grep is just there to highlight what is being described. Without it
it looks like this:

=== without -Bsymbolic ===
$ ltrace -x 'func*' -L ./tst
func_f_main()                             = <void>
func_f_lib at tstlib.so( <unfinished ...>
func_g_lib at tstlib.so()                    = <void>
<... func_f_lib resumed> )                = <void>
+++ exited (status 163) +++

$ ltrace -e 'func*' ./tst
tst->func_f_lib( <unfinished ...>
tstlib.so->func_g_lib()                   = <void>
<... func_f_lib resumed> )                = <void>
+++ exited (status 163) +++

$ ltrace -l tstlib.so ./tst
tst->func_f_lib( <unfinished ...>
tstlib.so->func_g_lib()                   = <void>
<... func_f_lib resumed> )                = <void>
+++ exited (status 163) +++


=== with -Bsymbolic ===
$ ltrace -x 'func*' -L ./tst
func_f_main() = <void>
func_f_lib at tstlib.so( <unfinished ...>
func_g_lib at tstlib.so()                    = <void>
<... func_f_lib resumed> )                = <void>
+++ exited (status 163) +++

$ ltrace -e 'func*' ./tst
tst->func_f_lib()                         = <void>
+++ exited (status 163) +++

$ ltrace -l tstlib.so ./tst
tst->func_f_lib()                         = <void>
+++ exited (status 163) +++


Do you think this is better? I can go either way.



> I would also put the whole example in a section of its own, presumably
> named "EXAMPLE", or maybe "SYMBOL FILTERING EXAMPLE".  That should only
> come after the "FILTERING EXPRESSIONS", as conceptually it builds on
> what's written there.  It would however be good to refer to this new
> section from -e, -x and -l.

Sure? I think the way it is now is better. Both putting the examples
first (all perl docs do that, and they tend to be very good) and putting
them into the same section (but different subsections). If you don't
have strong feelings here, I'd rather leave it.

dima