Skip to content

Restore ability to disable cross references for inline tt #1643

@nevans

Description

@nevans

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:

  1. <code>some text</code> should go back to the way it used to behave, with no cross-linking. The semantics or tt vs code should make it easy to remember.
  2. Inside <tt> (and <code>) tags, \ should be able to disable linking without disabling any of other inline styles.
  3. 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. 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:

Image

Which is not at all helpful! And it's the same for many many other examples on that page.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions