Restore ability to disable cross references for inline `tt`
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 930
- Forks
- 465
- Avg merge
- 3d 10h
- Merged PRs (30d)
- 27
Description
The problem
Prior to #1240, tt text (created by +word+, <tt>some text</tt>, or <code>some text</code> would not automatically convert cross-references into links. Now it does.
This is a huge improvement! However, sometimes we don't want a monospace text to automatically cross-reference.
Outside of tt text, we can disable automatic linking by prefixing \. Unfortunately, \ seems to disable all inline attributes?
My proposal
Leave +word+ and <tt>some text</tt> the exact same as they are today. This is a big improvement. \ should still disable all inline attributes for +\WORD+, as it + only works with words (and \ isn't a word char) and it also allows the +s to be rendered.
But make one or more of these changes, in my personal order of preference:
<code>some text</code>should go back to the way it used to behave, with no cross-linking. The semantics forttvscodeshould make it easy to remember.- Inside
<tt>(and<code>) tags,\should be able to disable linking without disabling any of other inline styles. - Alternatively: maybe add support for
<pre>...</pre>?
Two examples
Here's one example, which may not be the best example, but it's the most recent one I've run up against:
module Net
# Implements a \IMAP protocol client.
# ^^^^^
# \
# This refers to the protocol, not the class,
# so we've escaped it.
class IMAP
# A message flag that is set on deleted messages, before they are expunged.
DELETED = Flag[:Deleted]
# Sends a +STATUS+ command for a +mailbox+ and returns a hash of status
# attributes and their values.
#
# +attrs+ lists the requested status attributes, as an array of strings.
#
# Supported attributes:
# +MESSAGES+::
# number of messages in the mailbox
# +DELETED+::
# Links to Net::IMAP::DELETED, which is a slightly different concept.
# That's a message flag, this is a status attribute name.
# <code>DELETED</code>::
# Also links to Net::IMAP::DELETED.
# +\DELETED+::
# Not a link, not monospace font, and renders both of the +s too.
# <code>\DELETED</code>::
# Not linked, not monospace, but the code tags aren't rendered
#
# <tt"DELETED"</tt>::
# The arguments are provided as strings, so _technically_ this is a
# potential solution for _this_ example.
#
# But the status attribute names are referenced in other ways elsewhere,
# and they refer back to this rdoc. And, because the \IMAP protocol
# distinguishes between <tt>"quoted text"</tt> and +ATOM+ values, the
# documentation avoids using quotation marks for protocol atoms, even
# when they are provided as string arguments.
#
def status(mailbox, attrs)
mailbox = String(mailbox.to_str)
command "STATUS", mailbox, attrs, handle_untagged: ->req {
req in name: "STATUS", data: StatusData[mailbox: ^mailbox]
}
end
end
end
I've come across other examples in Net::IMAP, which might be better than this one. But none of them are as good as the example I found in this repository when I went looking to see if there's a solution.
Several examples in the "Links" section of markup_reference/rdoc.rdoc (source) are broken now. This is worst for Heading links and Section links:
=== Heading Links
Link: <tt>RDoc::RD@LICENSE</tt> links to RDoc::RDoc::RD@LICENSE.
Note that spaces in the actual heading are represented by <tt>+</tt> characters
in the linkable text.
- Link: <tt>RDoc::Options@Saved+Options</tt> links to RDoc::Options@Saved+Options.
=== Section Links
See Directives for Organizing Documentation above.
- Link: <tt>RDoc::Markup::ToHtml@Visitor</tt> links to RDoc::Markup::ToHtml@Visitor.
are rendered as
Which is not at all helpful!
For most of the other link examples, it isn't a big deal that they're linked because the text is still identical. But, for documentation purposes, I still wouldn't expect the example to be processed at all. For example, class links:
=== Class Links
- On-page: <tt>RDoc::Example::ExampleClass</tt> links to RDoc::Example::ExampleClass.
- Off-page: <tt>RDoc::Alias</tt> links to RDoc::Alias.
So, it's not a big deal, but it does feel a bit strange. It's like "if you input this link, rdoc will produce this link" but it should be "if you input this text, rdoc will produce this link".
A slightly different issue: the instance method links lose their tt formatting if they are missing on the page:
=== Instance Method Links
- On-page: <tt>#instance_method_example</tt> links to #instance_method_example
(when in the same class context).
renders as:
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the broken examples in markup_reference/rdoc.rdoc and reproduce their rendered links, including the Heading Links, Section Links, and Class Links cases. Compare the documented behavior for tt and code markup with the proposed escaping alternatives; done means the selected behavior is implemented consistently and the affected examples render as intended.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100