Support for reST raw::

[BobDenny]

Is there an existing issue for this?

• I have searched the existing issues

Your suggestion

I make extensive use of external links like this so my HTML readers get the external page in a separate tab.

.. |rinoh| raw:: html

    <a href="https://github.com/brechtm/rinohtype" target="_blank">
    Alpyca Device GitHub repository</a>

And inline |rinoh|. These things appear all over my documentation. Since rinohtype doesn't support this, the |xxxx| refs disappear (and also the raw:: blocks) in the PDF. This forces me to chop up my docs into .. only html and .. only rinoh chunks, with the normal reST hyperlinks for PDF.

I'm requesting this as a feature, not reporting it as a bug 😎 Thank you for rinohtype. it is spectacular!!

[brechtm]

The raw directive, role and substitution [1] are ways to bypass reStructuredText processing. They should only be used as a last resort, since they make your source material per definition dependent on the builder used.

The raw directives are similar to only, in that their content only needs to be interpreted by the builder referenced by it. I hope you understand it doesn't make sense for rinohtype to parse and interpret HTML input. See also #341 (comment).

While your goal seems very reasonable, I'm afraid it is not possible to implement this easily today. As far as I can see, you won't get there by means of substitution directives or custom roles. I think you would need to create a Sphinx extension that provides a custom role, e.g. :extref:, which outputs a plain hyperlink for all builders but HTML. I think it would make sense to provide such a role in Sphinx (or even docutils). Or maybe it would suffice to provide a Sphinx option to open all HTTP(S) links in a new window? I found this possible solution that achieves this: sphinx-doc/sphinx#1634. Please consider creating an issue with the Sphinx project if that doesn't solve your problem.

[1] I can't find documentation on the raw substitution, so it may not be a supported feature. See also #186 (comment) and #186 (comment).

Closing this issue, since it cannot be solved in rinohtype. Sorry!