From: James Clark <james.clark@arm.com>
To: mchehab+huawei@kernel.org, nfraprado@protonmail.com,
corbet@lwn.net, linux-doc@vger.kernel.org
Cc: James Clark <james.clark@arm.com>, linux-kernel@vger.kernel.org
Subject: [PATCH 1/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments
Date: Thu, 16 Dec 2021 19:27:04 +0000 [thread overview]
Message-ID: <20211216192704.413216-2-james.clark@arm.com> (raw)
In-Reply-To: <20211216192704.413216-1-james.clark@arm.com>
Since commit d18b01789ae5 ("docs: Add automatic cross-reference for
documentation pages"), references that were already explicitly defined
with "ref:" and reffered to other pages with a path have been doubled.
This is reported as the following error by Firefox:
Start tag "a" seen but an element of the same type was already open.
End tag "a" violates nesting rules.
As well as the invalid HTML, this also obscures the URI fragment links
to subsections because the second link overrides the first. For example
on the page admin-guide/hw-vuln/mds.html the last link should be to the
"Default Mitigations" subsection using a # URI fragment:
admin-guide/hw-vuln/l1tf.html#default-mitigations
But it is obsured by a second link to the whole page:
admin-guide/hw-vuln/l1tf.html
The full HTML with the double <a> tags looks like this:
<a class="reference internal" href="l1tf.html#default-mitigations">
<span class="std std-ref">
<a class="reference internal" href="l1tf.html">
<span class="doc">L1TF - L1 Terminal Fault</span>
</a>
</span>
</a>
After this commit, there is only a single link:
<a class="reference internal" href="l1tf.html#default-mitigations">
<span class="std std-ref">Documentation/admin-guide/hw-vuln//l1tf.rst</span>
</a>
Now that the second link is removed, the browser correctly jumps to the
default-mitigations subsection when clicking the link.
The fix is to check that nodes in the document to be modified are not
already references. A reference is counted as any text that is a
descendant of a reference type node. Only plain text should be converted
to new references, otherwise the doubling occurs.
Testing
=======
* Test that the build stdout is the same (ignoring ordering), and that
no new warnings are printed.
* Diff all .html files and check that the only modifications occur
to the bad double links.
* The auto linking of bare references to pages without "ref:" is still
working.
Fixes: d18b01789ae5 ("docs: Add automatic cross-reference for
documentation pages")
Signed-off-by: James Clark <james.clark@arm.com>
---
Documentation/sphinx/automarkup.py | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index acf5473002f3..3fee247b55b3 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -280,10 +280,22 @@ def auto_markup(app, doctree, name):
# avoid adding cross-references to functions that have been explicitly
# marked with cc:func:.
#
+ def text_but_not_a_reference(node):
+ if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal):
+ return False
+
+ child_of_reference = False
+ parent = node.parent
+ while parent:
+ if isinstance(parent, nodes.Referential):
+ child_of_reference = True
+ break
+ parent = parent.parent
+ return not child_of_reference
+
for para in doctree.traverse(nodes.paragraph):
- for node in para.traverse(nodes.Text):
- if not isinstance(node.parent, nodes.literal):
- node.parent.replace(node, markup_refs(name, app, node))
+ for node in para.traverse(condition=text_but_not_a_reference):
+ node.parent.replace(node, markup_refs(name, app, node))
def setup(app):
app.connect('doctree-resolved', auto_markup)
--
2.28.0
next prev parent reply other threads:[~2021-12-16 19:27 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-16 19:27 [PATCH 0/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments James Clark
2021-12-16 19:27 ` James Clark [this message]
2022-01-04 14:17 ` [PATCH 1/1] " James Clark
2022-01-04 21:58 ` Nícolas F. R. A. Prado
2022-01-05 14:42 ` James Clark
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20211216192704.413216-2-james.clark@arm.com \
--to=james.clark@arm.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab+huawei@kernel.org \
--cc=nfraprado@protonmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.