-
Notifications
You must be signed in to change notification settings - Fork 452
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 orttvscodeshould 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
endI'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. Nearly every example in the "Links" section of markup_reference/rdoc.rdoc is broken now (the current rendered version). For example:
=== Class Links
- On-page: <tt>RDoc::Example::ExampleClass</tt> links to RDoc::Example::ExampleClass.
- Off-page: <tt>RDoc::Alias</tt> links to RDoc::Alias.This is currently rendered as:
Which is not at all helpful! And it's the same for many many other examples on that page.