docutils-users

[Docutils-users] Inline internal target with custom target name

[Tobias D. <hax...@po...>]

Hi,
                                                                    
a short question on inline internal targets. Consider this example:
   
 A short generic target  _`is` going to cause conflicts. A target with same name
 but different meaning _`is` likely to be defined somewhere else.

To avoid such ambiguous targets, is it possible to assign custom target names to
inline internal targets that differ from their inline text?

Tobias

PS: Thanks for making docutils!

Re: [Docutils-users] Inline internal target with custom target name

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

Dear Tobias,

On 2024-02-17, Tobias Deiminger wrote:

> a short question on inline internal targets. Consider this example:

>  A short generic target _`is` going to cause conflicts. A target with
>  same name but different meaning _`is` likely to be defined somewhere
>  else.

> To avoid such ambiguous targets, is it possible to assign custom target
> names to inline internal targets that differ from their inline text?

I don't know of any way to achieve the exact result except raw HTML::

  .. role:: raw-html (raw)
     :format: html
  
  This short generic target 
  :raw-html:`<span class="target" id="is-2">is</span>`
  hopefully not going to cause conflicts. 

However, in most situations, it would be OK to simply use a larger part of
the sentence as target::

  A _`longer generic target` is not going to cause conflicts.
  
put the target on the containing block element::
  
  .. _block target:

  A "block target" with an id that differs from the content.
  
  .. container::
     :name: container-target
     
     (Almost) all directives accept the "name" option to specify a target
     name.
     
Hope this helps,
     
Günter