From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 21930 invoked by alias); 11 Aug 2012 17:36:56 -0000 Received: (qmail 21922 invoked by uid 22791); 11 Aug 2012 17:36:55 -0000 X-SWARE-Spam-Status: No, hits=-8.6 required=5.0 tests=AWL,BAYES_00,KHOP_PGP_SIGNED,KHOP_RCVD_UNTRUST,KHOP_THREADED,RCVD_IN_DNSWL_HI,RCVD_IN_HOSTKARMA_W,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from smtp.gentoo.org (HELO smtp.gentoo.org) (140.211.166.183) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sat, 11 Aug 2012 17:36:42 +0000 Received: from vapier.localnet (localhost [127.0.0.1]) by smtp.gentoo.org (Postfix) with ESMTP id 1487F1B400A; Sat, 11 Aug 2012 17:36:41 +0000 (UTC) From: Mike Frysinger To: Eli Zaretskii Subject: Re: [PATCH] gdb: improve usage strings Date: Sat, 11 Aug 2012 17:36:00 -0000 User-Agent: KMail/1.13.7 (Linux/3.5.0; KDE/4.6.5; x86_64; ; ) Cc: gdb-patches@sourceware.org References: <1344704080-24677-1-git-send-email-vapier@gentoo.org> <83fw7tcpst.fsf@gnu.org> In-Reply-To: <83fw7tcpst.fsf@gnu.org> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="nextPart6163593.UTF79VTbtY"; protocol="application/pgp-signature"; micalg=pgp-sha1 Content-Transfer-Encoding: 7bit Message-Id: <201208111336.41052.vapier@gentoo.org> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2012-08/txt/msg00341.txt.bz2 --nextPart6163593.UTF79VTbtY Content-Type: Text/Plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Content-length: 3758 On Saturday 11 August 2012 13:16:18 Eli Zaretskii wrote: > > From: Mike Frysinger > > Date: Sat, 11 Aug 2012 12:54:40 -0400 > > c =3D add_com ("signal", class_run, signal_command, _("\ > >=20 > > -Continue program giving it signal specified by the argument.\n\ > > -An argument of \"0\" means continue program without giving it a > > signal.")); > > +Continue program by sending it the specified signal.\n\ >=20 > This "by sending it" is AFAIU inaccurate: we don't continue program > _by_ sending it the signal, we continue the program _and_ send it the > signal. I actually don't see anything wrong with the original > wording. ok, but your response shows what i was trying to fix: - adding "the" before "program" - changing "giving" to "sending" the "by" change was incidental so i'll change it to: Continue program and send it the specified signal. > > add_com ("finish", class_run, finish_command, _("\ > > Execute until selected stack frame returns.\n\ > > +Usage: finish\n\ > > Upon return, the value returned is printed and put in the value > > history.")); >=20 > Does this "usage" really add any information? not really, but i added it for two reasons: - consistency: the current *lack* of help text consistency is extremely=20 confusing especially - many commands take arguments even though the help text implies otherwise= =20 leaving the user to wonder "does this actually take an option?". so even a= =20 usage string showing it takes no arguments is useful. although it's funny you highlight this command because, when i was updating= =20 this text, i checked the command to see if it actually secretly took=20 arguments. this is what i found: static void finish_command (char *arg, int from_tty)=20 { ... /* Find out whether we must run in the background. */ if (arg !=3D NULL) async_exec =3D strip_bg_char (&arg); /* If we must run in the background, but the target can't do it, error out. */ if (async_exec && !target_can_async_p ()) error (_("Asynchronous execution not supported on this target.")); /* If we are not asked to run in the bg, then prepare to run in the foreground, synchronously. */ if (!async_exec && target_can_async_p ()) { /* Simulate synchronous execution. */ async_disable_stdin (); } if (arg) error (_("The \"finish\" command does not take any arguments.")); ... so it seems like finish *does* secretly accept options, but in this case it= 's=20 trying to be secret about it rather than someone just didn't fully document= =20 it. or i read the "arg" parsing logic above incorrectly. > > add_com ("next", class_run, next_command, _("\ > > Step program, proceeding through subroutine calls.\n\ > > +Usage: next [N]\n\ > > Like the \"step\" command as long as subroutine calls do not happen;\n\ > > when they do, the call is treated as one instruction.\n\ > > -Argument N means do this N times (or till program stops for another \ > > +Argument N means step N times (or till program stops for another \ >=20 > Isn't it better to say "N source lines"? hmm, probably. it can be a little confusing when the source debug informat= ion=20 isn't available for functions, so the "next" ends up skipping too much. bu= t=20 maybe that topic is too large to cover here, so wrapping it up into "source= =20 lines" should work. > Btw, I find this entire doc string completely obfuscated. How about > this instead: >=20 > Step program until it reaches a different source line. > Usage: next [N] > Unlike "step", if the current source line calls a subroutine, > this command does not enter the subroutine, but instead steps over > the call, in effect treating it as a single source line. SGTM -mike --nextPart6163593.UTF79VTbtY Content-Type: application/pgp-signature; name=signature.asc Content-Description: This is a digitally signed message part. Content-length: 836 -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.17 (GNU/Linux) iQIcBAABAgAGBQJQJpgpAAoJEEFjO5/oN/WBopUP/0eyq2WRgEbdvVfaL1LMu04x syn2SYZ9h8PZBFePAeV8DOFWF3Fc7Bi90ugBucvAI7arQp2CDSWj1xMMgkRNaD+W zNdsc1D1gDrH3yzSiOpsYVuuzVBLiz/4dmE4o5+6IVMV8bYDoeOCubOZtChteYJc +QqkNfujzNNuR/dKpgYqFHKe9pVkg0VAXOoRFZkcwpsL8CMc0Zy7D08+QkCavTIX iRjmIgwE48TogAzFH0P475lQc1sMQZQVl+kLsObhMIO3CqBXe2AGx4d6CBVETSOc d3y/7FO3u+4BdOcbaPxf/rIdKHyWF5UoqzSnH8nioGUccrnhoops6Ev+xcIuRqWA L1JiBD0Zgn4tk2mMDfjM2Q/IYpSV2gUMVYNzgcli4NS/RhEwG+HqpgXvPh04tg7Q BSI9uZjBcvB1pK3ys7HTzwijOvsiDM2vZY4n5rc3emisSOkFzJ9sQsEhsnY0kWJi AdkgnpcMcE4hrKebI5KqlNlX3ghI3c8R2FSgZCfilwPVdWd8D0hOxynjRNPW8K2Z McfMhSWQWmYwxjTdSJYPZXQZHdlS0htoO9iQ5aN7y08n7b77rP0vagzm+U48Cqqp RZSc0k5amvmsQ3in9Btf6Y9e3dPqr38VPFum/Ttk4l4E1NSXp45I92y8NmVAESH6 dwZ+YZo+Ti3kgBPFuLWd =mLpF -----END PGP SIGNATURE----- --nextPart6163593.UTF79VTbtY--