Restore ability to disable cross references for inline `tt`

Aberta
  • Algo errado?
#1,643 2 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
35/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
ruby
Domínio
documentation

Direção de pesquisa

Comece pelos exemplos quebrados em markup_reference/rdoc.rdoc e reproduza seus links renderizados, incluindo os casos Heading Links, Section Links e Class Links. Compare o comportamento documentado para a marcação tt e code com as alternativas de escape propostas; a tarefa estará concluída quando o comportamento selecionado estiver implementado de forma consistente e os exemplos afetados forem renderizados conforme o esperado.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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
Linguagem predominante
Ruby
Estrelas
928
Forks
471
Merge médio
2d 4min
PRs com merge (30d)
13

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de ruby/rdoc

Todas as issues de ruby/rdoc

Issues semelhantes

Mais issues de Ruby

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.