Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Restore ability to disable cross references for inline `tt`

Abierto
  • ¿Algo no está bien?
#1,643 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
35/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
ruby
Área
documentation

Línea de trabajo

Comienza con los ejemplos defectuosos de markup_reference/rdoc.rdoc y reproduce sus enlaces renderizados, incluidos los casos Heading Links, Section Links y Class Links. Compara el comportamiento documentado para el marcado tt y code con las alternativas de escape propuestas; la tarea estará terminada cuando el comportamiento seleccionado esté implementado de forma coherente y los ejemplos afectados se rendericen como se espera.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
Ruby
Estrellas
929
Forks
469
Merge medio
1 d 2 h
PR fusionados (30 d)
19

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de ruby/rdoc

Todos los issues de ruby/rdoc

Issues similares

Más issues de Ruby

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.