Em Sat, 26 Dec 2020 13:18:58 +0000 Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxxx> escreveu: > During the process of converting the documentation to reST, some links > were converted using the following wrong syntax (and sometimes using %20 > instead of spaces): > The patch itself looks ok, although the description has an issue (IMHO). Also, some references can be cleaned. See below. > `Display text <#section-name-in-html>`__ > > This syntax can work in html, but isn't the one described in docutils, Well, docutils define two types of references at: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-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. > and it also doesn't work on pdf. The following syntax should be used > instead: > > `Display text <Section Name_>`__ > > The usual toolchain doesn't mind this unusual syntax, but it causes > errors when trying to build using the not-yet-merged rst2pdf: > > ValueError: format not resolved, probably missing URL scheme or undefined destination target for 'Forcing%20Quiescent%20States' > > Fixes: ccc9971e2147 ("docs: rcu: convert some articles from html to ReST") > Fixes: c8cce10a62aa ("docs: Fix the reference labels in Locking.rst") > Fixes: e548cdeffcd8 ("docs-rst: convert kernel-locking to ReST") > Fixes: 7ddedebb03b7 ("ALSA: doc: ReSTize writing-an-alsa-driver document") > Signed-off-by: Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxxx> ... > @@ -596,7 +596,7 @@ maintain ordering. For example, if the callback function 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 <Grace-Period 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/Documentation/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 <Summary_>`__, however, the answers to Hmm... why are you ending "Summary" with a "_"? This should be equivalent to: `summary <summary>`__ In this specific case, however, you could use, instead[1]: summary_ as there's no need to use an indirect hyperlink target here. (the same applies to a few other similar cases on your patch) [1] https://docutils.sourceforge.io/docs/user/rst/quickref.html#hyperlink-targets Thanks, Mauro
