* [PATCH v2 0/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments
@ 2022-01-05 14:36 James Clark
2022-01-05 14:36 ` [PATCH v2 1/1] " James Clark
0 siblings, 1 reply; 5+ messages in thread
From: James Clark @ 2022-01-05 14:36 UTC (permalink / raw)
To: nfraprado, n, linux-doc; +Cc: mchehab+huawei, corbet, James Clark, linux-kernel
Changes since v1:
* Re-ordered comments so that they align with the correct code
* Add Nícolas's review tag
James Clark (1):
docs: automarkup.py: Fix invalid HTML link output and broken URI
fragments
Documentation/sphinx/automarkup.py | 25 ++++++++++++++++++-------
1 file changed, 18 insertions(+), 7 deletions(-)
--
2.28.0
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH v2 1/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments
2022-01-05 14:36 [PATCH v2 0/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments James Clark
@ 2022-01-05 14:36 ` James Clark
2022-01-06 22:25 ` Jonathan Corbet
0 siblings, 1 reply; 5+ messages in thread
From: James Clark @ 2022-01-05 14:36 UTC (permalink / raw)
To: nfraprado, n, linux-doc; +Cc: mchehab+huawei, corbet, James Clark, linux-kernel
Since commit d18b01789ae5 ("docs: Add automatic cross-reference for
documentation pages"), references that were already explicitly defined
with "ref:" and referred 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")
Reviewed-by: Nícolas F. R. A. Prado <n@nfraprado.net>
Signed-off-by: James Clark <james.clark@arm.com>
---
Documentation/sphinx/automarkup.py | 25 ++++++++++++++++++-------
1 file changed, 18 insertions(+), 7 deletions(-)
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index acf5473002f3..cc348b219fca 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -271,19 +271,30 @@ def get_c_namespace(app, docname):
def auto_markup(app, doctree, name):
global c_namespace
c_namespace = get_c_namespace(app, name)
+ def text_but_not_a_reference(node):
+ # The nodes.literal test catches ``literal text``, its purpose is to
+ # avoid adding cross-references to functions that have been explicitly
+ # marked with cc:func:.
+ 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
+
#
# This loop could eventually be improved on. Someday maybe we
# want a proper tree traversal with a lot of awareness of which
# kinds of nodes to prune. But this works well for now.
#
- # The nodes.literal test catches ``literal text``, its purpose is to
- # avoid adding cross-references to functions that have been explicitly
- # marked with cc:func:.
- #
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
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v2 1/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments
2022-01-05 14:36 ` [PATCH v2 1/1] " James Clark
@ 2022-01-06 22:25 ` Jonathan Corbet
2022-01-07 10:04 ` James Clark
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2022-01-06 22:25 UTC (permalink / raw)
To: James Clark, nfraprado, n, linux-doc
Cc: mchehab+huawei, James Clark, linux-kernel
James Clark <james.clark@arm.com> writes:
> Since commit d18b01789ae5 ("docs: Add automatic cross-reference for
> documentation pages"), references that were already explicitly defined
> with "ref:" and referred to other pages with a path have been doubled.
> This is reported as the following error by Firefox:
[...]
> 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.
This seems like a good fix. Applied, thanks.
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2 1/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments
2022-01-06 22:25 ` Jonathan Corbet
@ 2022-01-07 10:04 ` James Clark
2022-01-07 16:33 ` Nícolas F. R. A. Prado
0 siblings, 1 reply; 5+ messages in thread
From: James Clark @ 2022-01-07 10:04 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: mchehab+huawei, linux-kernel, nfraprado, n, linux-doc
On 06/01/2022 22:25, Jonathan Corbet wrote:
> James Clark <james.clark@arm.com> writes:
>
>> Since commit d18b01789ae5 ("docs: Add automatic cross-reference for
>> documentation pages"), references that were already explicitly defined
>> with "ref:" and referred to other pages with a path have been doubled.
>> This is reported as the following error by Firefox:
> [...]
>> 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.
>
> This seems like a good fix. Applied, thanks.
>
> jon
>
Thanks Jonathan. Do you have a git repo that these get applied to?
I wasn't able to find it on https://git.kernel.org/
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2 1/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments
2022-01-07 10:04 ` James Clark
@ 2022-01-07 16:33 ` Nícolas F. R. A. Prado
0 siblings, 0 replies; 5+ messages in thread
From: Nícolas F. R. A. Prado @ 2022-01-07 16:33 UTC (permalink / raw)
To: James Clark
Cc: Jonathan Corbet, mchehab+huawei, linux-kernel, nfraprado, linux-doc
On Fri, Jan 07, 2022 at 10:04:44AM +0000, James Clark wrote:
>
>
> On 06/01/2022 22:25, Jonathan Corbet wrote:
> > James Clark <james.clark@arm.com> writes:
> >
> >> Since commit d18b01789ae5 ("docs: Add automatic cross-reference for
> >> documentation pages"), references that were already explicitly defined
> >> with "ref:" and referred to other pages with a path have been doubled.
> >> This is reported as the following error by Firefox:
> > [...]
> >> 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.
> >
> > This seems like a good fix. Applied, thanks.
> >
> > jon
> >
>
> Thanks Jonathan. Do you have a git repo that these get applied to?
> I wasn't able to find it on https://git.kernel.org/
Yeah, it's not listed there. His tree lives at git://git.lwn.net/linux . I can
see your patch in the docs-next branch.
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2022-01-07 16:33 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-01-05 14:36 [PATCH v2 0/1] docs: automarkup.py: Fix invalid HTML link output and broken URI fragments James Clark
2022-01-05 14:36 ` [PATCH v2 1/1] " James Clark
2022-01-06 22:25 ` Jonathan Corbet
2022-01-07 10:04 ` James Clark
2022-01-07 16:33 ` Nícolas F. R. A. Prado
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).