From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 720BFC433E0 for ; Thu, 31 Dec 2020 11:02:35 +0000 (UTC) Received: from alsa0.perex.cz (alsa0.perex.cz [77.48.224.243]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 93266223C8 for ; Thu, 31 Dec 2020 11:02:33 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 93266223C8 Authentication-Results: mail.kernel.org; dmarc=fail (p=quarantine dis=none) header.from=protonmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=alsa-devel-bounces@alsa-project.org Received: from alsa1.perex.cz (alsa1.perex.cz [207.180.221.201]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by alsa0.perex.cz (Postfix) with ESMTPS id 2A8CF16E3; Thu, 31 Dec 2020 12:01:42 +0100 (CET) DKIM-Filter: OpenDKIM Filter v2.11.0 alsa0.perex.cz 2A8CF16E3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=alsa-project.org; s=default; t=1609412552; bh=eBizkGspz5n53OqUrHFiSqdRKLs+PAGUiZURbEGysxw=; h=Date:To:From:Subject:In-Reply-To:References:Cc:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: Reply-To:From; b=kVYCz8cpb6g/tjUQ9sSekHCH5Jptt8zLKhfaS2CC5+CRpEr7TaZXSDkSPmZpvTgNe mJ2CkQXtgVTwfCtcnk0jOZeeE1wW2KH808hBCgWPDiuwoFY0kIOe81qrvwllQt5wPj O3yDof2lyfUfD3FPVIJmw1Gm7+rshhbGRoD3UBWY= Received: from alsa1.perex.cz (localhost.localdomain [127.0.0.1]) by alsa1.perex.cz (Postfix) with ESMTP id C4F92F8020C; Thu, 31 Dec 2020 12:01:41 +0100 (CET) Received: by alsa1.perex.cz (Postfix, from userid 50401) id 23BC4F8022B; Sun, 27 Dec 2020 14:59:37 +0100 (CET) Received: from mail-40134.protonmail.ch (mail-40134.protonmail.ch [185.70.40.134]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by alsa1.perex.cz (Postfix) with ESMTPS id CDD18F80085 for ; Sun, 27 Dec 2020 14:59:30 +0100 (CET) DKIM-Filter: OpenDKIM Filter v2.11.0 alsa1.perex.cz CDD18F80085 Authentication-Results: alsa1.perex.cz; dkim=pass (1024-bit key) header.d=protonmail.com header.i=@protonmail.com header.b="DlSga1RD" Date: Sun, 27 Dec 2020 13:59:18 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail; t=1609077564; bh=YljSvU7AD7QZcNa1WxrVV3YXtj4LJS3zWAnWwLu+YdA=; h=Date:To:From:Cc:Reply-To:Subject:In-Reply-To:References:From; b=DlSga1RDI35jH7OyuyfnRdQpU7t7h0g7Lgf+e3vNkYtFTSvjV1Gfp+2fLnNS0gZWP 35nYnspdqU+KhExqPaBNCaLSH37GZu2IwH48o4KjmMVRXfvNXU15gztsWd++c8q+bH L0ZXyFfRV/dzkr6+oelyu/IENWuzVz86BumTwgEg= To: Mauro Carvalho Chehab From: =?utf-8?Q?N=C3=ADcolas_F=2E_R=2E_A=2E_Prado?= Subject: Re: [PATCH] docs: Fix reST markup when linking to sections Message-ID: In-Reply-To: <20201227105949.549cc6ea@coco.lan> References: <20201226131759.724711-1-nfraprado@protonmail.com> <20201227105949.549cc6ea@coco.lan> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Mailman-Approved-At: Thu, 31 Dec 2020 12:01:39 +0100 Cc: alsa-devel@alsa-project.org, Jonathan Corbet , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, Lai Jiangshan , Takashi Iwai , Steven Rostedt , rcu@vger.kernel.org, lkcamp@lists.libreplanetbr.org, Mathieu Desnoyers , andrealmeid@collabora.com, Joel Fernandes , Stephen Boyd X-BeenThere: alsa-devel@alsa-project.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: "Alsa-devel mailing list for ALSA developers - http://www.alsa-project.org" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: =?utf-8?Q?N=C3=ADcolas_F=2E_R=2E_A=2E_Prado?= Errors-To: alsa-devel-bounces@alsa-project.org Sender: "Alsa-devel" On Sun Dec 27, 2020 at 6:59 AM -03, Mauro Carvalho Chehab wrote: > Well, docutils define two types of references at: > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#refere= nce-names > > The first one are "simple reference names", defined as: > > ``Simple reference names are single words consisting of > alphanumerics plus isolated (no two adjacent) internal > hyphens, underscores, periods, colons and plus signs; > no whitespace or other characters are allowed.`` > > On this type, "-_.,+" characters are allowed. "%" and "#" aren't. > > The second one is "phrase-references", defined as: > > ``Reference names using punctuation or whose names are phrases (two or > more space-separated words) are called "phrase-references".`` > > Here, the spec doesn't specify the charset associated with > "punctuation". > > As this kind of reference is auto-generated from the chapter titles, > I would expect it to allow all ASCII punctuation characters > (e. g. all non-alphanumeric symbols between 0x20-0x7f). > > So, a reference like those: > #Summary > #Forcing%20Quiescent%20States > > Violates the spec, as it would be a simple reference with invalid > chars, but: > > #Forcing Quiescent States > > Should be valid, according with the spec (still, while doing such > cleanup, I would remove "#"). > > I would add something like the above at the patch description. Indeed, some of those references aren't even valid according to the spec, b= ut that isn't even the real issue. The issue is that they only work in html. T= hey *don't* work in the LaTeX pdf (already supported) and in the rst2pdf's pdf = (not yet supported).=20 Even "#Forcing Quiescent States" only works in html, and doesn't in pdf. "Forcing Quiescent States_", on the other hand, works in all of them. More details below. I should have been more clear in the commit message about that, and I will = for v2. > > @@ -596,7 +596,7 @@ maintain ordering. For example, if the callback fun= ction wakes up a task > > that runs on some other CPU, proper ordering must in place in both the > > callback function and the task being awakened. To see why this is > > important, consider the top half of the `grace-period > > -cleanup <#Grace-Period%20Cleanup>`__ diagram. The callback might be > > +cleanup `__ diagram. The callback might be > > running on a CPU corresponding to the leftmost leaf ``rcu_node`` > > structure, and awaken a task that is to run on a CPU corresponding to > > the rightmost leaf ``rcu_node`` structure, and the grace-period kernel > > diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/D= ocumentation/RCU/Design/Requirements/Requirements.rst > > index 1ae79a10a8de..d4125caf394e 100644 > > --- a/Documentation/RCU/Design/Requirements/Requirements.rst > > +++ b/Documentation/RCU/Design/Requirements/Requirements.rst > > @@ -45,7 +45,7 @@ requirements: > > #. `Other RCU Flavors`_ > > #. `Possible Future Changes`_ > > > > -This is followed by a `summary <#Summary>`__, however, the answers to > > +This is followed by a `summary `__, however, the answers to > > Hmm... why are you ending "Summary" with a "_"? This should be > equivalent to: > > `summary `__ Actually, that doesn't work. To reference a target in rst, like a section, = an _ is needed at the end of the reference (and when it is a named link, this ha= ppens inside the <>). Take a look at [1]. While reading [1], though, I noticed that it should also be possible to not have the link anonymous, that is, to use _ instead of __ at the end. And th= at fails in rst2pdf specifically, so that's an issue I'll report there. > In this specific case, however, you could use, instead[1]: > > summary_ > > as there's no need to use an indirect hyperlink target here. You're right, this does work. I didn't realize these references were case-insensitive. So for v2, I'll also see if there are any other reference= s in my patch whose text only differs the target in casing, and use this simplif= ied syntax for those. Thanks, N=C3=ADcolas [1] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embe= dded-uris-and-aliases From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id CDA59C433DB for ; Sun, 27 Dec 2020 14:00:23 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 8E8E42250F for ; Sun, 27 Dec 2020 14:00:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726158AbgL0OAI (ORCPT ); Sun, 27 Dec 2020 09:00:08 -0500 Received: from mail-40134.protonmail.ch ([185.70.40.134]:33716 "EHLO mail-40134.protonmail.ch" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726137AbgL0OAH (ORCPT ); Sun, 27 Dec 2020 09:00:07 -0500 Date: Sun, 27 Dec 2020 13:59:18 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail; t=1609077564; bh=YljSvU7AD7QZcNa1WxrVV3YXtj4LJS3zWAnWwLu+YdA=; h=Date:To:From:Cc:Reply-To:Subject:In-Reply-To:References:From; b=DlSga1RDI35jH7OyuyfnRdQpU7t7h0g7Lgf+e3vNkYtFTSvjV1Gfp+2fLnNS0gZWP 35nYnspdqU+KhExqPaBNCaLSH37GZu2IwH48o4KjmMVRXfvNXU15gztsWd++c8q+bH L0ZXyFfRV/dzkr6+oelyu/IENWuzVz86BumTwgEg= To: Mauro Carvalho Chehab From: =?utf-8?Q?N=C3=ADcolas_F=2E_R=2E_A=2E_Prado?= Cc: Jonathan Corbet , Steven Rostedt , Mathieu Desnoyers , Lai Jiangshan , Joel Fernandes , Takashi Iwai , Jaroslav Kysela , Stephen Boyd , rcu@vger.kernel.org, alsa-devel@alsa-project.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, lkcamp@lists.libreplanetbr.org, andrealmeid@collabora.com Reply-To: =?utf-8?Q?N=C3=ADcolas_F=2E_R=2E_A=2E_Prado?= Subject: Re: [PATCH] docs: Fix reST markup when linking to sections Message-ID: In-Reply-To: <20201227105949.549cc6ea@coco.lan> References: <20201226131759.724711-1-nfraprado@protonmail.com> <20201227105949.549cc6ea@coco.lan> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org On Sun Dec 27, 2020 at 6:59 AM -03, Mauro Carvalho Chehab wrote: > Well, docutils define two types of references at: > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#refere= nce-names > > The first one are "simple reference names", defined as: > > ``Simple reference names are single words consisting of > alphanumerics plus isolated (no two adjacent) internal > hyphens, underscores, periods, colons and plus signs; > no whitespace or other characters are allowed.`` > > On this type, "-_.,+" characters are allowed. "%" and "#" aren't. > > The second one is "phrase-references", defined as: > > ``Reference names using punctuation or whose names are phrases (two or > more space-separated words) are called "phrase-references".`` > > Here, the spec doesn't specify the charset associated with > "punctuation". > > As this kind of reference is auto-generated from the chapter titles, > I would expect it to allow all ASCII punctuation characters > (e. g. all non-alphanumeric symbols between 0x20-0x7f). > > So, a reference like those: > #Summary > #Forcing%20Quiescent%20States > > Violates the spec, as it would be a simple reference with invalid > chars, but: > > #Forcing Quiescent States > > Should be valid, according with the spec (still, while doing such > cleanup, I would remove "#"). > > I would add something like the above at the patch description. Indeed, some of those references aren't even valid according to the spec, b= ut that isn't even the real issue. The issue is that they only work in html. T= hey *don't* work in the LaTeX pdf (already supported) and in the rst2pdf's pdf = (not yet supported).=20 Even "#Forcing Quiescent States" only works in html, and doesn't in pdf. "Forcing Quiescent States_", on the other hand, works in all of them. More details below. I should have been more clear in the commit message about that, and I will = for v2. > > @@ -596,7 +596,7 @@ maintain ordering. For example, if the callback fun= ction wakes up a task > > that runs on some other CPU, proper ordering must in place in both the > > callback function and the task being awakened. To see why this is > > important, consider the top half of the `grace-period > > -cleanup <#Grace-Period%20Cleanup>`__ diagram. The callback might be > > +cleanup `__ diagram. The callback might be > > running on a CPU corresponding to the leftmost leaf ``rcu_node`` > > structure, and awaken a task that is to run on a CPU corresponding to > > the rightmost leaf ``rcu_node`` structure, and the grace-period kernel > > diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/D= ocumentation/RCU/Design/Requirements/Requirements.rst > > index 1ae79a10a8de..d4125caf394e 100644 > > --- a/Documentation/RCU/Design/Requirements/Requirements.rst > > +++ b/Documentation/RCU/Design/Requirements/Requirements.rst > > @@ -45,7 +45,7 @@ requirements: > > #. `Other RCU Flavors`_ > > #. `Possible Future Changes`_ > > > > -This is followed by a `summary <#Summary>`__, however, the answers to > > +This is followed by a `summary `__, however, the answers to > > Hmm... why are you ending "Summary" with a "_"? This should be > equivalent to: > > `summary `__ Actually, that doesn't work. To reference a target in rst, like a section, = an _ is needed at the end of the reference (and when it is a named link, this ha= ppens inside the <>). Take a look at [1]. While reading [1], though, I noticed that it should also be possible to not have the link anonymous, that is, to use _ instead of __ at the end. And th= at fails in rst2pdf specifically, so that's an issue I'll report there. > In this specific case, however, you could use, instead[1]: > > summary_ > > as there's no need to use an indirect hyperlink target here. You're right, this does work. I didn't realize these references were case-insensitive. So for v2, I'll also see if there are any other reference= s in my patch whose text only differs the target in casing, and use this simplif= ied syntax for those. Thanks, N=C3=ADcolas [1] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embe= dded-uris-and-aliases