Should "linktargets" be in main menu?

[sypets]

A while ago, someone requested via Slack if linktargets could be removed from main menu. This is only relevant for editing the documentation. It clutters up the menu and may be confusing.

https://docs.typo3.org/m/typo3/tutorial-sitepackage/master/en-us/Preface/Index.html

---

Explanation: The "Linktargets" page is a list of all link targets (for crossreferencing with :ref:) in the manual. A link target can also be determined by looking in the source code of a page and using the header label.

---

While this is useful for editing, perhaps it is possible to remove it from the main menu and put the link somewhere else.

[susannemoog]

I think it should stay, as it's really helpful when writing documentation and pretty unobtrusive even in the longer manuals. Additionally, it's not only for the doc team internally, but can and should also be used by extension authors cross-linking to core / other manuals.

[kaystrobach]

Please keep it - maybe find a better label for it.

[sypets]

My 2c: I am not happy with it being in the main menu. I think the main menu should not be cluttered with things that are only relevant for editing the manual.

I try to avoid confusion and information overload by keeping things simple. (Most times I don't succeed and it is not always possible, but I try). Every additional menu point adds information. Menus should be kept short and we are already bending the best practices of usability with our menus in some manuals.

It would be great if we could find a place for it, e.g. in the footer or on the start page.

That being said, I will be ok with whatever is decided and I think consistency is more important than this choice or that. So, if we do it one way, let's always do it - at least in the official docs.

---

Apart from that: I have never used this. I look in the source of the page for the header label. Maybe I am missing something.

[susannemoog]

hm, I never look into the source, usually only open the link targets and search for something approximately like the thing I want to link. Different workflows probably.

Ok, so basically from a "cluttering" point of view all three:

Sitemap
About This Manual
Link Targets

should move to somewhere like a meta navigation I guess.

[DanielSiepmann]

Did someone try to include it, always under the same url, but without mentioning it in the menu? That way it would not be visible, but "everyone" would know how to access it.

[sypets]

Did someone try to include it, always under the same url, but without mentioning it in the menu? That works: If a Targets.rst exists, it is rendered, even if not included in menu. See https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/Targets.html

[sypets]

See latest discussion in Slack:

Christian:

i don't think they're useful for casual readers and only of very limited use for editors (did you ever use that?). ... it would have my +1 to drop them everywhere

Daniel:

What about having it there (accessable via url) but not listed in navigation? That way People can access it, as they know the url, it would always be the same

Mathias:

I'd prefer a reliable location for this like the footer or similar. With this solution it depends on the manual content. Not sure if we can automatically add this to all manuals with some global include or so.

Mathias:

Not sure how else i can quickly find and confirm link targets otherwise ...

Christian:

my main concern is having it in the main menu. moving it elsewhere so casual readers don't stumble upon it at a prominent place like main menu would be very fine with me.

[marble]

My opinion: I definetely want to have the linktargets page and want to be able to find it. I don't need that link prominently in the menu, especially not at the top level. I would go looking for it in the sitemap though. And it would be a good idea to have a line on the frontpage - below the "bibliographic data table" showing links to Index | Sitemap | Targets. Sometimes we had that, but inconsistently. Would be ease to achieve using

:ref:`Index` | :ref:`Sitemap` | :ref:Linktargets\

(fill in the proper names).

If we have that link (one link on the frontpage would do) we could "orphan" that page. This means, it doesn't need to be included in the toctree at all. So it won't appear in the menu and neither in the sitemap. Would be fine with me. https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#special-metadata-fields

[marble]

• I recommend this basic structure for Targets.rst [TESTED!]
• DO NOT include it in any toctree directive. This is the only way to have it excluded from 'singlehtml'. And this way it also is excluded from 'latex' ('pdf').
• The :orphan: line just suppresses the Sphinx warning

:orphan:

.. include:: /Includes.rst.txt
.. index:: Linktargets
.. _Linktargets:

===========
Linktargets
===========

.. you may write reST here

.. ref-targets-list::

.. you may write reST here            

[sypets]

We have now decided to remove link targets from menu and add a link to the start page. Has already been done for TCA, see https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-TCA/pull/330

I am updating the rest of the official manuals as well.

A PR for adding the conventions to "Writing Documentation" has been created: https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/pull/188

[sypets]

I would like to reopen this: Adding link targets to start page and changing this everywhere is a lot of work.

I never quite understood why we need this. You can look in the source code of a page to find the link target. That is what I usually use.

The linktargets page - if in menu - clutters up the menu.

Figureing out what is on start page prooved difficult. Especially structuring the start page with the current methods.

I would suggest to find a decision that is realistic.

[alexander-nitsche]

The "Linktargets" page is a list of all link targets (for crossreferencing with :ref:) in the manual. A link target can also be determined by looking in the source code of a page and using the header label.

There is also the automatically compiled objects.inv.json in every manual, ready for looking up the link targets, even searchable etc., for example

• https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/objects.inv.json
• https://docs.typo3.org/m/typo3/guide-security/8.7/en-us/objects.inv.json
• https://docs.typo3.org/m/typo3/book-extbasefluid/main/en-us/objects.inv.json

Recommended by Martin. Just by reviewing the documentations of the documentation awards, these Target.html files are all empty pages - not maintained.

[sypets]

Only partially related, but right now the "Link targets" does not seem to work in general, see https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/Targets.html

[sypets]

these Target.html files are all empty pages - not maintained.

That they are empty is not their fault. This should work automatically.

[marble]

1. Yes, it seems "linktargets" fails at the moment, probably because of our jump from Sphinx v1.8.5 to v4.2. I will fix that.
2. Personally I find that page and overview helpful.
3. I would prefer to not include the page in the menu, at least not as a top level page.
4. In private documentation I'm using this approach: ⓐ I do not include the "Linktargets" page in any toctree. Instead, I write :orphan: at the top of the page, so that Sphinx doesn't complain. ⓑ I add an index entry "Linktargets" on that page. ⓒ I make sure that the documentation has an Index page.
5. As a result it's easy to find the Linktargets page via the Index.

[alexander-nitsche]

Linktargets.rst and Targets.rst have been removed completely from TYPO3 documentation in meantime. Common sense is

1. to use either the "View source" button of the target page, or
2. to read the always available /objects.inv.json in a documentation, e.g. https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/objects.inv.json

and look up the label.

Furthermore, a meta menu has form part of the documentation standards in meantime, where all functional pages like sitemap, index, etc. should be collected.

[sypets]

@alexander-nitsche Alex, thank you for taking care of it. Sounds good.