From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from arjuna.pair.com (arjuna.pair.com [209.68.5.131]) by sourceware.org (Postfix) with ESMTPS id 723DE3857C77; Fri, 2 Jul 2021 23:53:51 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 723DE3857C77 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=bitrange.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=bitrange.com Received: by arjuna.pair.com (Postfix, from userid 3006) id C93308A56E; Fri, 2 Jul 2021 19:53:50 -0400 (EDT) Received: from localhost (localhost [127.0.0.1]) by arjuna.pair.com (Postfix) with ESMTP id C61178A548; Fri, 2 Jul 2021 19:53:50 -0400 (EDT) Date: Fri, 2 Jul 2021 19:53:50 -0400 (EDT) From: Hans-Peter Nilsson X-X-Sender: hp@arjuna.pair.com To: Eli Zaretskii cc: =?UTF-8?Q?Martin_Li=C5=A1ka?= , gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com Subject: Re: [PATCH] Port GCC documentation to Sphinx In-Reply-To: <83pmw3mrcg.fsf@gnu.org> Message-ID: References: <1446990946.2994.192.camel@surprise> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> <8641dc55-5412-fbd7-bafd-13604311f5ad@suse.cz> <5ffe3e32-ece0-a1b4-1fcf-e35177fa80b5@suse.cz> <87489d9a-44e2-411c-3f3a-534d07e78b95@suse.cz> <0866a0ea-c846-ea5e-ac7a-d1c8f106cc45@suse.cz> <5bb9a10d-f3b9-f16a-7430-bbae2d4978e2@suse.cz> <2f60f602-5d88-7674-9620-2172748664c5@suse.cz> <83a6n8obh4.fsf@gnu.org> <57743e51-04d5-ec2e-b684-54f0321ef0bd@suse.cz> <83pmw3mrcg.fsf@gnu.org> User-Agent: Alpine 2.20.16 (BSF 172 2016-09-29) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII X-Spam-Status: No, score=-3.9 required=5.0 tests=BAYES_00, KAM_DMARC_STATUS, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) 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, 02 Jul 2021 23:53:52 -0000 On Wed, 30 Jun 2021, Eli Zaretskii via Gcc-patches wrote: > > Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org > > From: Martin Li?ka > > Date: Wed, 30 Jun 2021 12:11:03 +0200 > > > 4. Menus lost the short descriptions of the sub-sections. Example: > > > > > > * Designated Initializers > > > * Case Ranges > > > * Cast to a Union Type > > > * Mixed Declarations, Labels and Code > > > * Declaring Attributes of Functions > > > > > > vs > > > > > > * Designated Inits:: Labeling elements of initializers. > > > * Case Ranges:: 'case 1 ... 9' and such. > > > * Cast to Union:: Casting to union type from any member of the union. > > > * Mixed Declarations:: Mixing declarations and code. > > > * Function Attributes:: Declaring that functions have no side effects, > > > or that they can never return. > > > > > > Looks like some bug to me. > > > > > > Note also that nodes are now called by the same name as the section, > > > which means node names generally got much longer. Is that really a > > > good idea? > > > > Well, I intentionally removed these and used simple TOC tree links > > which take display text for a section title. > > I would suggest to discuss these decisions first, perhaps on the > Texinfo mailing list? I'm accustomed to these short descriptions, but > I'm not sure how important they are for others. I'd miss them, and they're helpful when the title or term is not familiar, when looking for a concept you know is documented in there. I've read the discussion downthread, but I seem to miss (a recap of) the benefits of moving to Sphinx. Maybe other have too and it'd be a good idea to repeat them? Otherwise, the impression is not so good, as all I see is bits here and there getting lost in translation. brgds, H-P