Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Restore ability to disable cross references for inline `tt`

Aperta
  • Qualcosa non va?
#1,643 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
35/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
ruby
Ambito
documentation

Direzione di ricerca

Inizia dagli esempi non funzionanti in markup_reference/rdoc.rdoc e riproduci i relativi link renderizzati, inclusi i casi Heading Links, Section Links e Class Links. Confronta il comportamento documentato per il markup tt e code con le alternative di escaping proposte; il lavoro è completato quando il comportamento selezionato è implementato in modo coerente e gli esempi interessati vengono renderizzati come previsto.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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
Lingua principale
Ruby
Stelle
929
Fork
469
Merge medio
1g 2h
PR unite (30g)
19

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di ruby/rdoc

Tutte le issue di ruby/rdoc

Issue simili

Altre issue su Ruby

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.