Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

[Guenter M. <mi...@us...>]

On 2023-08-04, engelbert gruber via Docutils-develop wrote:

> **[feature-requests:#72] rst2man: Show reference targets**
> **Created:** Wed Aug 26, 2020 03:47 PM UTC by Petr Viktorin

> Currently, the manpage writer writes a reference like `ALT TEXT <URL>`
> as just `ALT TEXT`, with alternate font. Would it be better to render
> it as, for example, `ALT TEXT [URL]`, so the information is not lost?


> line of thought 

> * Reading a manpage  on screen in a terminal is like a printout 
> * printing links at the end, in or near section SEE ALSO might be far away

> plan

> * printing in place the one without label
> * printing at end of paragraph for labeled urls ?

The `target-notes`__ directive creates a footnote for each external
target in the text at the place where it occures in the source, and
corresponding footnote references after each reference.

However the distinction is not done by labeled vs. anonymous links but by
explicit vs. implicit hyperlink targets::
    
  Inlined targets like `du <ex1>`_ do not appear in the footnotes.

  External targets  like_ this are collected.
  Also `anonymous targets`__
  
  .. _like: ex2
  __ ex3
  
  .. target-notes::

__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#target-footnotes


Suggestion:

* Print links with `implicit hyperlink targets 
  <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
  #implicit-hyperlink-targets>`_ including the target in ``[]`` or
  ``<>``, whatever is more common in man pages).
 
* Add a paragraph recommending the "target-notes" directive for man
  pages with explicit links to the manpage writer documentation.
  
  The "target-notes" directive allows custom placement of the footnotes
  containing the link targets.
  
This gives document authors a choice for link placement.
(Currently, the "target-notes" directive can only be used once in a document,
subsequent uses repeat the complete list with new footnote numbers.)  

Günter