* How to cross-link to another document?
@ 2022-07-06 17:15 Matthew Wilcox
2022-07-07 8:10 ` Akira Yokosawa
0 siblings, 1 reply; 2+ messages in thread
From: Matthew Wilcox @ 2022-07-06 17:15 UTC (permalink / raw)
To: linux-doc
I've tried several variants of this without success. What's the
correct incantation?
+++ b/Documentation/core-api/idr.rst
@@ -17,6 +17,8 @@ solution to the problem to avoid everybody inventing their own. The IDR
provides the ability to map an ID to a pointer, while the IDA provides
only ID allocation, and as a result is much more memory-efficient.
+The IDR interface is deprecated; please use the _`XArray` instead.
+
IDR usage
=========
+++ b/Documentation/core-api/xarray.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0+
+.. XArray_
======
XArray
I first tried "named reference, reStructuredText_;"
and then "_`inline internal target`" and I've tried both prefixing and
suffixing both destination and target with an underscore. Nothing seems
to work and sometimes I get error messages telling me it won't work,
and sometimes I just get non-hyperlinks.
Do I have to do something like
:ref:`Documentation/core-api/xarray.rst <XArray>`
? That would seem unnecessarily verbose.
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: How to cross-link to another document?
2022-07-06 17:15 How to cross-link to another document? Matthew Wilcox
@ 2022-07-07 8:10 ` Akira Yokosawa
0 siblings, 0 replies; 2+ messages in thread
From: Akira Yokosawa @ 2022-07-07 8:10 UTC (permalink / raw)
To: Matthew Wilcox; +Cc: linux-doc, Akira Yokosawa
Hi Matthew,
On Wed, 6 Jul 2022 18:15:43 +0100, Matthew Wilcox wrote:
> I've tried several variants of this without success. What's the
> correct incantation?
>
> +++ b/Documentation/core-api/idr.rst
> @@ -17,6 +17,8 @@ solution to the problem to avoid everybody inventing their own. The IDR
> provides the ability to map an ID to a pointer, while the IDA provides
> only ID allocation, and as a result is much more memory-efficient.
>
> +The IDR interface is deprecated; please use the _`XArray` instead.
You can cross-link using .rst file's path, in this case the relative path.
(This is an extension to Sphinx for kernel documentation.)
+The IDR interface is deprecated; please use the xarray.rst instead.
If you think "the xarray.rst" looks weird in plain-text, then maybe:
+The IDR interface is deprecated; please use :doc:`the XArray <xarray>`
+instead.
Here, <xarray> points xarray.rst. <xarray.rst> doesn't work behind
:doc:.
Or simply drop "the":
+The IDR interface is deprecated; please use xarray.rst instead.
In this case, as both idr.rst and xarray.rst are under core-api/,
the relative path would be a reasonable option. As a bonus, it
works in both full and partial (subdirectory-wise) builds.
Cross-links using absolute paths don't work in partial builds.
> +
> IDR usage
> =========
>
> +++ b/Documentation/core-api/xarray.rst
> @@ -1,4 +1,5 @@
> .. SPDX-License-Identifier: GPL-2.0+
> +.. XArray_
In any case, a reference label at the top of a .rst file is pointless.
Please don't add a new one.
See: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#cross-referencing
Hope this helps.
Thanks, Akira
>
> ======
> XArray
>
> I first tried "named reference, reStructuredText_;"
> and then "_`inline internal target`" and I've tried both prefixing and
> suffixing both destination and target with an underscore. Nothing seems
> to work and sometimes I get error messages telling me it won't work,
> and sometimes I just get non-hyperlinks.
>
> Do I have to do something like
>
> :ref:`Documentation/core-api/xarray.rst <XArray>`
> ? That would seem unnecessarily verbose.
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2022-07-07 8:11 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-07-06 17:15 How to cross-link to another document? Matthew Wilcox
2022-07-07 8:10 ` Akira Yokosawa
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.