Issue #1286 wontfix

:ref:`section title` should work w/o explicit label

Ben Franksen
created an issue

Currently I have to write:

.. _Built-in Functions:

Built-in Functions

if I want to refer to the section from other documents using :ref:.

I think this is redundant and also goes against the spirit of documentation being human readable even as plain text.

Comments (4)

  1. Georg Brandl repo owner

    The label doesn't have to have the same text as the heading: you could use .. _builtins: for example.

    This is by design: so that you don't need to change lots of links when changing the heading (or translating it).

  2. Ben Franksen reporter

    Well, it is your decision, of course, but I suggest you re-think your rationale.

    First, the feature I requested would not prevent you from using a separate label if that is the way you like to work.

    Second, I do not plan to ever translate the documentation for my project. I just do not have the manpower for that, and since I often work to improve it, any translation would be out of date very soon. I think this situation is not untypical, there are lots of one-man projects out there.

    Last not least, chosing a different text for the label actually makes things more difficult for me. Each time I want to add a cross-reference, I have to look up the name of the label. I find it a lot easier to remember the section name. Besides, I usually have a web-browser open where I can read the formatted version of what I write, and I can find section headings there easily via the local TOC. The label I have to look up in the rst sources.

    Having to add a separate label makes it harder for people to add cross-references. This is bad since in my experience, the more cross-references, the easier it is to navigate around a complex project, especially if you are still unfamiliar with it. Therefore adding a cross-reference should be as easy as possible for the documentation writer.

  3. Log in to comment