search

brechtm / rinohtype

The Python document processor
http://www.mos6581.org/rinohtype
GNU Affero General Public License v3.0
498 stars 59 forks source link

Support for reST raw:: #392

Closed BobDenny closed 1 year ago

BobDenny commented 1 year ago

Is there an existing issue for this?

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 :sunglasses: Thank you for rinohtype. it is spectacular!!

brechtm commented 1 year ago

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 https://github.com/brechtm/rinohtype/issues/341#issuecomment-1168790666.

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 https://github.com/brechtm/rinohtype/issues/186#issuecomment-711041417 and https://github.com/brechtm/rinohtype/issues/186#issuecomment-711796523.

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