Chapter/section numbers in document internal references

[Chris Johns]

On 13/8/19 12:06 am, Sebastian Huber wrote:
> On 08/08/2019 08:52, Sebastian Huber wrote:
>> On 06/08/2019 10:23, Sebastian Huber wrote:
>>>
>>>
>>> On 06/08/2019 10:05, Chris Johns wrote:
>>>> On 6/8/19 4:36 pm, Sebastian Huber wrote:
>>>>> Hello,
>>>>>
>>>>> when you use document internal references, e.g.
>>>>>
>>>>> :ref:`RSB`
>>>>>
>>>>> then this is turned into:
>>>>>
>>>>> "Chapter 12 - RTEMS Source Builder"
>>>>>
>>>>> I think this "Chapter 12 - " prefix makes it harder to read the document. In a
>>>>> default configuration of Sphinx this stuff is not included. Would it be
>>>>> possible
>>>>> to remove this from the RTEMS customization?
>>>>>
>>>>
>>>> What are you suggesting instead? Could you put something online so I could
>>>> compare?
>>>>
>>>> I did play around with this but I cannot remember all the variations and why I
>>>> selected this one.
>>>
>>> To see the default behaviour, please create a new document with
>>> sphinx-quickstart and copy the attached index.rst over the default. Run "make
>>> latexpdf".
>>>
>>> On page 1 you see "See Section.". With the RTEMS style you would probably see
>>> "See Chapter 1 - Section".
>>
>> Here is an example in the RTEMS style:
>>
>> https://docs.rtems.org/branches/master/user/support/bugs.html
>>
>> I think the "Chapter/Section X" prefix makes it harder to read.
> 
> I manage to figure out where this comes from:
> 
> common/rtemsext.py
> 
> Could we please remove this?
> 

What happens when you print the page or like me are looking at `test.pfd` in
Thunderbird's PDF viewer where all I see on the 5th page is "See Section." where
`Section` is blue but the viewer does has not have the ability to click through
the link? That can be frustrating in a large complex document you do not know well.

The PDF documentation has to be able to take a single printed sheet and let us
know the origin, version, document and where a reference points to in text. It
is difficult to click on a printed link. ;)

If you wish to make a change to the reference please suggest one. For example
the ARM manual's "Blah blah on page 6-9" is simple and compact. I am also fine
if the written version is only present in the PDF format as the HTML version has
to support links.

Chris