From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-x42c.google.com (mail-wr1-x42c.google.com [IPv6:2a00:1450:4864:20::42c]) by sourceware.org (Postfix) with ESMTPS id B092F388CC21; Mon, 12 Jul 2021 16:01:25 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org B092F388CC21 Received: by mail-wr1-x42c.google.com with SMTP id p8so26336365wrr.1; Mon, 12 Jul 2021 09:01:25 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=ah+CKng/GCrBUp2pB0t3bCEQoqFNxKBhgiJx4aLP2zc=; b=bXslaHz5T79D1mC5gbdcCCORR4fBaiB04bq/YX9b42ojgmWN3CsS+/Dz8kIpRtW9TF JcLXO7kTkrS1MBoXvpBjAT2Z/RGPKf/JwTIky4wYPY1ADYncydy9oOU0ZzJXKQI+c0c7 guAJ3B3naQzZ1iFh0pe5LkGwezTO9ypTfldvZJ9By7HwRX6SClgs47Mfm9NJXEOvagYB fJKjuLj9eTBe1doS6uV3Lu9B+PMljK5HxgBT3DtfN4LNREnD/B42EIhK/VyP/rXsAGKT bF4YbuB0B8xNTdL4Yzqq7+WLr8m6iK5Bkw+BzVw4vrOF0AwXt/vpEHqKCOwgv7X91ITX IozQ== X-Gm-Message-State: AOAM533v0UmUwP0jWotpNNH8L1qcFE6iMfKymT8m1l/kWbW8LEyV4/OD RI3EnlCwpotWTBKxZOUyTlEKwkR7igr+wv6EETQ= X-Google-Smtp-Source: ABdhPJwE2/IFsxmd+gi0b3LIyaQUaicdqnopbAuHS9M+pT7E2sXy0mFLKocIynAjNhgFGe9xn/5R6sc1Nd/zr0OELxU= X-Received: by 2002:a5d:4573:: with SMTP id a19mr22536947wrc.346.1626105684783; Mon, 12 Jul 2021 09:01:24 -0700 (PDT) MIME-Version: 1.0 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> <98388e12-3712-575b-9387-45b6ea7ef498@suse.cz> <83v95fabwx.fsf@gnu.org> <83r1g3aady.fsf@gnu.org> In-Reply-To: From: Gavin Smith Date: Mon, 12 Jul 2021 17:00:58 +0100 Message-ID: Subject: Re: Benefits of using Sphinx documentation format To: Jonathan Wakely Cc: Eli Zaretskii , "gcc@gcc.gnu.org" , gcc-patches , "Joseph S. Myers" X-Spam-Status: No, score=0.5 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM, HTML_MESSAGE, KAM_SHORT, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP, T_HTML_ATTACH autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org Content-Type: text/plain; charset="UTF-8" X-Content-Filtered-By: Mailman/MimeDel 2.1.29 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: Mon, 12 Jul 2021 16:01:30 -0000 On Mon, Jul 12, 2021 at 4:04 PM Jonathan Wakely via Gcc wrote: > GNU Hello has the same problem with its docs: > https://www.gnu.org/software/hello/manual/hello.html#index-_002dg > That URL is garbage because of the URL-encoded %2d character, and the > fact it links to the wrong place (the description of the option, not > the option itself). The former is no longer an issue for GCC (it was > for many years) but the latter is still a problem. > > If you don't know where to find it yourself, the source is visible here: > https://github.com/yugui/example/blob/master/doc/hello.texi#L208 I downloaded the source for the "hello" manual and recreated it with Texinfo 6.8 (running " texi2any --html hello.texi --no-split"). I've attached the results. The current output doesn't exhibit the problem with the scrolling being at the wrong place - this problem has evidently resolved itself since the time when the online "hello" manual was generated. (I don't remember many complaints about it on the mailing list, though: if we don't know about problems, we can't fix them.) The URL is mangled because index entries can have more characters in them than what is suitable for a URL. A space character becomes a "-", so a "-" has to become something else. They have to be distinguished because there may be two separate index entries in different places which wouldn't be distinguishable otherwise. However, I find that adding an extra index entry means you can use hello.html#index-greeting instead: @item --greeting=@var{text} @itemx -g @var{text} @opindex greeting @opindex --greeting @opindex -g Output @var{text} instead of the default greeting.