From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 101752 invoked by alias); 10 Jul 2019 17:02:46 -0000 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 Received: (qmail 101728 invoked by uid 89); 10 Jul 2019 17:02:46 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-6.2 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_HELO_PASS,UNSUBSCRIBE_BODY autolearn=no version=3.3.1 spammy=harsh X-HELO: gateway30.websitewelcome.com Received: from gateway30.websitewelcome.com (HELO gateway30.websitewelcome.com) (192.185.147.85) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 10 Jul 2019 17:02:44 +0000 Received: from cm13.websitewelcome.com (cm13.websitewelcome.com [100.42.49.6]) by gateway30.websitewelcome.com (Postfix) with ESMTP id 7F8A19224 for ; Wed, 10 Jul 2019 12:02:43 -0500 (CDT) Received: from box5379.bluehost.com ([162.241.216.53]) by cmsmtp with SMTP id lFzPhkjc4YTGMlFzPhcMmq; Wed, 10 Jul 2019 12:02:43 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tromey.com; s=default; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=s9o6hs0b02OnTiqy7pl3jaQoi+hpzG4NNVG5VjL3zbI=; b=D0dD9KPqui9xTXIYt/US0f11/n RQvgX+dCDGCyg2j1CddsNxdlvt99tOVoyElAdECqhjayF0GriyJJTQEA23S6YO7Mek/kGNHrN64Yf S1rwUT0x10YA/8ARb/OaPjHYw; Received: from 97-122-178-82.hlrn.qwest.net ([97.122.178.82]:50872 helo=murgatroyd) by box5379.bluehost.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.92) (envelope-from ) id 1hlFzP-001H8Z-6Z; Wed, 10 Jul 2019 12:02:43 -0500 From: Tom Tromey To: Philippe Waroquiers Cc: gdb-patches@sourceware.org Subject: Re: [RFA] Make first and last lines of 'command help documentation' consistent. References: <20190616195804.9427-1-philippe.waroquiers@skynet.be> Date: Wed, 10 Jul 2019 17:02:00 -0000 In-Reply-To: <20190616195804.9427-1-philippe.waroquiers@skynet.be> (Philippe Waroquiers's message of "Sun, 16 Jun 2019 21:58:04 +0200") Message-ID: <874l3tg6vh.fsf@tromey.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-SW-Source: 2019-07/txt/msg00268.txt.bz2 >>>>> "Philippe" == Philippe Waroquiers writes: Philippe> With this patch, the help docs now respect 2 invariants: Philippe> * The first line of a command help is terminated by a '.' character. Philippe> * The last character of a command help is not a newline character. Thanks for doing this. I'm in favor of the change, as I think it improves the help experience and doesn't make anything worse. Philippe> gdb/ChangeLog Philippe> 2019-06-16 Philippe Waroquiers Philippe> * cli/cli-decode.h (print_doc_line): Add for_value_prefix argument. Philippe> * cli/cli-decode.c (print_doc_line): Likewise. It now prints Philippe> the full first line, except when FOR_VALUE_PREFIX. In this case, Philippe> the trailing '.' is not output, and the first character is uppercased. Philippe> (print_help_for_command): Update call to print_doc_line. Philippe> (print_doc_of_command): Likewise. Output a specific string Philippe> when doc string ends with a line feed to allow the testsuite Philippe> to detect the broken invariant. Philippe> * cli/cli-setshow.c (deprecated_show_value_hack): Likewise. Philippe> * cli/cli-option.c (append_indented_doc): Do not append newline. Philippe> (build_help_option): Append newline after first appended_indented_doc Philippe> only if a second call is done. Philippe> (build_help): Append 2 new lines before each option, except the first Philippe> one. Philippe> * compile/compile.c (_initialize_compile): Add new lines after Philippe> %OPTIONS%, when not at the end of the help. Philippe> C hange help doc or code Little hiccup in the ChangeLog. Philippe> + /* Checks that the documentation does not help with a new line. Philippe> + If it does, output a special marker string that gdb.base/help.exp Philippe> + will detect. */ Philippe> + if (c->doc[strlen (c->doc) - 1] == '\n') Philippe> + fprintf_filtered (stream, "END_OF_LINE@END_OF_DOC %s%s\n", Philippe> + prefix, c->name); I think this can't be an assertion, because user commands could hit it, and that seems too harsh; but could it be a unit test? That might be better than printing something magic, especially since IIUC the user can end up seeing this stuff. Philippe> -Usage: maintenance selftest [filter]\n\ Philippe> +Usage: maintenance selftest [FILTER]\n\ Thank you. Philippe> +gdb_test_no_output \ Philippe> + "|apropos .| grep -e '\[^\.\]$' -e '^END_OF_LINE@END_OF_DOC '" \ Philippe> + "command help doc first line ends with a dot, doc does not end with eol" I'm not sure we can rely on having grep in the test suite. If you switch the patch to a self-test, then this is moot; otherwise, is this used elsewhere? I think a different approach is to write to a log file and then examine it with Tcl. I believe some other tests do this. Tom