I have posted issues regarding the only directive and always get the reply that what is to me an issue 'it is a specification`.

I do understand that only is a bit peculiar, but still it's behavior is very annoying and limiting. Take thi as example: I want to have a caption for a literalinclude that differs depending on the target:

.. only:: latex

   .. literinclude:: filename
      :caption: c1
      :name: link
.. only:: html

   .. literinclude:: filename
      :caption: c2
      :name: link

Clearly, since I want to link to the block, I need the same name. The result is that using :numref: the link will be recognized as duplicate, and therefore not displayed.

The issue is that nodes in only are processed anyway. No matter on the condition. That is very annoying and in a sense misleading. I think that

1- it should be more clearly described in the docs

2- there should be a way to force the only condition to be evaluated before it's content is parsed, in order to remove it from the very beginning.

I know in some cases I can workaround, but it would require fiddling with extensions, which is not very handy and maintainable. Why cannot a proper conditional be introduced?

See also #1717, #1488 and #2143 (comment)