On 4/3/23 08:37, Ken Goldman wrote: > The answers below explain __how__, which I already know. > > My question is whether this is a good or bad idea. What happens if I change labels? Do I break people's links? Must my labels be stable forever? For in-kernel-tree links, they will be fixed up. > On 3/24/2023 10:45 PM, Bagas Sanjaya wrote: >> On Fri, Mar 24, 2023 at 04:28:02PM -0600, Jonathan Corbet wrote: >>>> Are links to other documents stable? >>>> >>>> How about sections within the page? >>> I don't understand those questions. >> You need to first add the label before desired section heading, like: >> >> ``` >> ... >> .. _foo: >> >> Foo >> === >> >> ... >> ``` >> >> Then elsewhere use :ref: role and specify the target label, ideally also >> specifying anchor text: >> >> ``` >> ... >> This assumes that you have knowledge on :ref:`foo <foo>`. >> ... >> ``` > > I know I can do that. > > However, what happens if someone links to my :ref:, and then I change the label? Is this "someone" a document in the kernel tree? If so, it will be fixed up. If it's some document on the internet, we have no control over that. It's up to "them" to keep it current. We don't guarantee stable links. >>>> I found that this .rst works. >>>> >>>> See >>>> https://www.kernel.org/doc/html/latest/security/keys/trusted-encrypted.html >>>> >>>> Is that OK, or is there a better way? >>> You wouldn't link to the rendered kernel docs normally, you'd just say >>> "See Documentation/security/keys/trusted-encrypted.rst". >>> >>> Look at the Sphinx cheatsheets on the net for the various other ways of >>> making links if you need to link outside of the kernel docs. >> As with internal linking, you can simply write out the link: >> >> ``` >> ... >> Check out the documentation at https://foo.bar/baz for complete >> treatment on this topic. >> ... >> >> ``` >> >> Or if you need anchor text: >> >> ``` >> ... >> Check out `baz documentation <https://foo.bar/baz>`_ for complete >> treatment on this topic`. >> ... >> ``` >> >> There is also :doc: directive if you need internal linking with anchor >> text. The target can be either relative to the doc or absolute in respect >> to documentation root (`Documentation/`). Do not specify filename >> suffix. For example: >> >> ``` >> ... >> The general guide on :doc:`submitting patches >> </process/submitting-patches>` also applies to this subsystem. -- ~Randy
