ruby / ruby/rdoc

Restore ability to disable cross references for inline `tt`

Open
#1,643 2 comments 0 reactions 0 assignees View on GitHub

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:

  1. <code>some text</code> should go back to the way it used to behave, with no cross-linking. The semantics for 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.

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
Image

Image

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.
Image

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:

Image

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.