From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.220.28]) by sourceware.org (Postfix) with ESMTPS id 3C80E398B14C; Fri, 11 Jun 2021 14:34:41 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 3C80E398B14C Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=suse.cz Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=suse.cz Received: from imap.suse.de (imap-alt.suse-dmz.suse.de [192.168.254.47]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp-out1.suse.de (Postfix) with ESMTPS id E221621969; Fri, 11 Jun 2021 14:34:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1623422079; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=snYF78v5JvbBX3weEztYs6l1Jtot6lj+Cp+dmFOXuG0=; b=JmJVgBJ8148qeiyKLnHLjMpGQcAW/Wki9UfehoMzBJ9UKO6eAQspKi9+4FM7e8DuLfhFKH 71XC4urO+KX1VfnJNKmo1POU4XZPaSbhbGOVlYyQooera5LKUg8YmO83SK3681kIH+g6bC NbY0oxlh0M5pUxCHxS/RAKctLuMRiDk= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1623422079; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=snYF78v5JvbBX3weEztYs6l1Jtot6lj+Cp+dmFOXuG0=; b=oPeimKGB+OzcNfr1EECXyPI+WfH2aIQW7megLjzrDLN+9VtOkfxCV5LAtqCH+pl7ZsMbwX ORhIsrhwyDo5oHAw== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id B2D04118DD; Fri, 11 Jun 2021 14:34:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1623422079; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=snYF78v5JvbBX3weEztYs6l1Jtot6lj+Cp+dmFOXuG0=; b=JmJVgBJ8148qeiyKLnHLjMpGQcAW/Wki9UfehoMzBJ9UKO6eAQspKi9+4FM7e8DuLfhFKH 71XC4urO+KX1VfnJNKmo1POU4XZPaSbhbGOVlYyQooera5LKUg8YmO83SK3681kIH+g6bC NbY0oxlh0M5pUxCHxS/RAKctLuMRiDk= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1623422079; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=snYF78v5JvbBX3weEztYs6l1Jtot6lj+Cp+dmFOXuG0=; b=oPeimKGB+OzcNfr1EECXyPI+WfH2aIQW7megLjzrDLN+9VtOkfxCV5LAtqCH+pl7ZsMbwX ORhIsrhwyDo5oHAw== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id BXzVKn90w2APewAALh3uQQ (envelope-from ); Fri, 11 Jun 2021 14:34:39 +0000 Subject: Re: GCC documentation: porting to Sphinx To: Martin Sebor , David Malcolm , gcc-patches@gcc.gnu.org Cc: GCC Development , "Joseph S. Myers" References: <1446990946.2994.192.camel@surprise> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> <298e21f2-7d04-7a28-1827-e87f2e70d187@suse.cz> <7bc0c42f-5cd7-130a-49cf-2df6cb23d6da@gmail.com> <9fbfa220-0708-bc7a-6e6b-0865d413d1ed@suse.cz> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: Date: Fri, 11 Jun 2021 16:34:39 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-2.4 required=5.0 tests=BAYES_00, BODY_8BITS, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_ASCII_DIVIDERS, KAM_EU, NICE_REPLY_A, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gcc@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 11 Jun 2021 14:34:42 -0000 On 6/11/21 1:48 AM, Martin Sebor wrote: > On 6/10/21 7:18 AM, Martin Liška wrote: >> On 6/10/21 11:07 AM, Martin Liška wrote: >>> Doing that, one has 2 unique links, that would be needed for get_option_url function. >>> Plus, both :option:`-Wfoo` and :option:`-Wno-foo` references are going to work. >> >> And I've actually did the transformation and one can see it e.g. here: >> https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wprio-ctor-dtor > > I find the style you have below right now clearer than keeping both > options in the same heading and adding a Note explaining the default > etc.  I.e., this > >   _________________ >   -Wchar-subscripts > >     Warn if an array subscript has type char. This is a common cause >     of error, as programmers often forget that this type is signed on >     some machines. This warning is enabled by -Wall. > >   ____________________ >   -Wno-char-subscripts > >    Default option value for -Wchar-subscripts. Yes, fully agree with you! Thanks, Martin > > on this page right now: > https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wchar-subscripts > > seems better than this: > >   _________________________________________________________ >   -Wno-shift-overflow, -Wshift-overflow=n, -Wshift-overflow > >     +--------------------------------------------------------------+ >     | (!) Note                                                     | >     +--------------------------------------------------------------- >     | Default value is -Wno-shift-overflow, -Wshift-overflow is    | >     | enabled by -Wall.                                            | >     +--------------------------------------------------------------+ > >     These options control warnings about left shift overflows. > > and also better than the alternative with (non-default) after the option > in the heading. > > https://splichal.eu/scripts/sphinx/demo/_build/html/#cmdoption-Wno-shift-overflow3 > > Martin > >> >> >> Martin >