texinfo tags in doc headings don't seem to be needed
sthesing opened this issue · 3 comments
In CONTRIBUTING.org, we currently write:
+ Use =@@texinfo:@code{}@@= or =@@texinfo:@samp{}@@= tags in
headers, captions, or other places where org formatting does not
directly translate correctly.
However, at least for org headings, all of the following are rendered identically into `foo` in the info file:
=foo=~foo~@@texinfo:@code{foo}@@@@texinfo:@samp{foo}@@
Am I overlooking something here? If not, we can remove the "headers, captions or other" from the sentence above.
Removing the unnecessary texinfo tags should also mitigate #311 somewhat.
I also noticed that (and from my testing, the doc export tool seems to also not care).
Might have been dependent on Emacs configuration (like some indentation things that we know change the exporter's functionality)?
In any case, I (personally) don't see a reason to keep them (at least for exporting to info).
Hmm.. They are there because when I first started writing docs, the places where I wanted to put code in headers didn't render the monospaced font as expected in the info files. That was back in Emacs 27 and Rational Emacs days, so I haven't tried removing those markup tags in favor of staying with the ~ or = to make sure they rendered correctly. Personally, I'd rather not have them in the org files since those are browsable on GitHub, but I do want the code rendering "correctly" in info files. If that can happen with just the normal Org markers for code or verbatim that would be great and we can just remove the @@texinfo... tags.