From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-oi1-x233.google.com (mail-oi1-x233.google.com [IPv6:2607:f8b0:4864:20::233]) by sourceware.org (Postfix) with ESMTPS id 4F670385DC14; Thu, 10 Jun 2021 23:48:30 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 4F670385DC14 Received: by mail-oi1-x233.google.com with SMTP id z3so3996331oib.5; Thu, 10 Jun 2021 16:48:30 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=sDyPUW00bt5uRzCt1zbz/6Pbdh93VUs7jpvFwfqcrdE=; b=tXUd3BYUm8IBX9XfYTnuRSNVgtNdNHYVIfFlaTpAk15Gu2qQmgYtdqT2UBq4/BrXZA TVlgl8wF95Ow1PaSKImiECidcziVkKgH+WuXGJzjLJyAIezRWWkDgJemK3r74HRkBAKb l2zL2FSnDXWr5IDxoKe8EDheFOk1lp9MhCbdLX9PL+TmZn7xpvbVYhlz7mB/+J192RpD 1W2Ti5LkazrRHnMNxTkNhENfuAE0qGsRDTzhlCtJ7ShjzNuQabxb2qPcXmC/akra2VDS VxqUFbiSgqj++/rfarK9nT1Csq/6+UTd0FcjP/ACkM3zobTjbhyP4CHbH2bZptdjIKrc r8GA== X-Gm-Message-State: AOAM5316GvPVRxM6apGtDGv1UjNHPbd6iXU7RhmD5vsrvUdmd83fZo02 DWwrUON8/1YG0WoX7waau2k= X-Google-Smtp-Source: ABdhPJwUamrdTjkRe4xMI4Ngg5I4GVi1rLMix6krppWk6z9MXxnFpQ/xlI/vB43LGEg6mvuVIP9cyQ== X-Received: by 2002:a05:6808:1522:: with SMTP id u34mr32087oiw.100.1623368909733; Thu, 10 Jun 2021 16:48:29 -0700 (PDT) Received: from [192.168.0.41] (97-118-122-241.hlrn.qwest.net. [97.118.122.241]) by smtp.gmail.com with ESMTPSA id c11sm835066oot.25.2021.06.10.16.48.28 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 10 Jun 2021 16:48:29 -0700 (PDT) Subject: Re: GCC documentation: porting to Sphinx To: =?UTF-8?Q?Martin_Li=c5=a1ka?= , 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: Martin Sebor Message-ID: Date: Thu, 10 Jun 2021 17:48:28 -0600 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.2.2 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=-3.4 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, KAM_ASCII_DIVIDERS, KAM_EU, NICE_REPLY_A, RCVD_IN_DNSWL_NONE, 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: Thu, 10 Jun 2021 23:48:32 -0000 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. 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