Flight-manual.atom.io: Suporte aprimorado de keymap

Nesse tópico, menciono um sistema por meio do qual a vinculação de chave apropriada para o sistema operacional do visualizador do documento pode ser determinada.

A detecção do UserAgent pode ser uma boa opção pela primeira vez. Mas eu não o usaria para gerar o mapa de teclado, mas sim para ocultar os irrelevantes usando CSS. Eu gosto da ideia de não ter que escrever a combinação de teclas para cada sistema operacional ao escrever os documentos, mas em vez de substituir seu <span class="keyboard">...</span> em tempo de execução, vejo algo na fase de geração.

Então, digamos que terminemos com a seguinte marcação:

<kbd data-os='mac'>cmd-shift-a</kbd>
<kbd data-os='linux'>ctrl-shift-a</kbd>
<kbd data-os='win'>ctrl-shift-a</kbd>

Poderíamos ter algo assim no script da página:

html = document.querySelector('html')
if /Macintosh/.test navigator.userAgent
  html.classList.add('mac')
else if /Linux/.test navigator.userAgent
  html.classList.add('linux')
else if /Windows/.test navigator.userAgent
  html.classList.add('win')

E então as regras de CSS, como abaixo, escondem o elemento irrelevante:

html.mac [data-os='linux'], 
html.mac [data-os='win'] {
  display: none;
}

html.win [data-os='linux'], 
html.win [data-os='mac'] {
  display: none;
}

html.linux [data-os='win'], 
html.linux [data-os='mac'] {
  display: none;
}

O bom desse truque é que ele não se aplica apenas a tags kbd . Você pode ter seções inteiras na documentação que são específicas do sistema operacional e, ao colocar um atributo data-os nelas, você pode exibir apenas as relevantes. Além disso, não impede a troca do sistema operacional exibido no tempo de execução, apenas troque a classe no elemento html e você exibirá a documentação específica do Windows no OSX e no Linux.

Esse é um ótimo sistema, @ abe33. Eu voto nisso!

Eu voto contra um sistema que esconde documentação. Eu trabalho em vários sistemas operacionais e gostaria de ler toda a documentação relevante para mim de uma vez.

Talvez, em vez de ficarem ocultas, as seções irrelevantes para o seu sistema operacional possam ser reduzidas? O título pode indicar que o conteúdo não é relevante para o seu sistema operacional, mas quando clicado, ele expande a seção de qualquer maneira. Para coisas que não são uma seção inteira sobre si mesmas - atalhos de teclado, por exemplo - as relevantes podem ser destacadas.

Se tivéssemos um menu suspenso, poderia haver simplesmente uma quarta opção "Todos". Eu realmente prefiro não ter que ver os vínculos do Windows / Linux na maioria das vezes ... mas seria útil ao fornecer suporte. Se o padrão é "Todos" ou o sistema operacional detectado pelo agente do usuário é uma questão adicional.

Isso parece ótimo! Nesse caso, eu preferiria a detecção do SO como padrão

@olmokramer Eu entendo seu ponto, mas você também deve considerar como a documentação é escrita.

Aqui está um exemplo dos documentos atuais:

Se você pressionar cmd-shift-P enquanto estiver focado em um painel do editor, a paleta de comandos aparecerá.

Colocar todas as ligações de SO nesta frase a torna mais legível? Eu acredito que não.
Podemos considerar a adição de alguma marcação extra para especificar para qual sistema operacional um kbd se aplica, ou seja, exibindo um ícone em uma regra :before ou :after , já que as ligações linux / windows podem ser semelhantes. Mas mesmo com isso não tenho certeza, de um ponto de vista do leitor, se isso torna as coisas mais legíveis.

A solução que proponho oferece a possibilidade de mudar o sistema operacional de referência em tempo de execução. Podemos até adicionar alguns controles extras a cada elemento com um atributo [data-os] para exibir as alternativas. Ou, como @lee-dohm sugere, podemos selecionar para escolher como exibir coisas específicas do sistema operacional.

Mas, como sempre, é apenas uma proposta, provavelmente omiti alguns casos de uso em que esse truque não será tão eficaz quanto penso.

@ abe33 É por isso que votei em detectar sistema operacional por padrão. Ao selecionar "todos" os sistemas operacionais, você desiste de um pouco mais de legibilidade.

Gosto da ideia de controles extras. Uma ideia: ao passar um [data-os] um pop-up pode mostrar informações para outros sistemas operacionais

Agora que os documentos vêm em formatos de e-books, como essa abordagem se traduziria em exportações de e-books? Isso significaria listar todos os atalhos de teclado embutidos? Tendo exportações de e-books separadas para cada plataforma?

Eu: heart: ver isso acontecer também, acho que seria muito útil para novos usuários. Já fazemos algo semelhante (visualmente) nos documentos de Ajuda do github.com (por exemplo, aqui ):

Portanto, seu sistema operacional é detectado automaticamente, mas você também pode alternar entre eles.

Não tenho certeza de como isso seria difícil de fazer, mas é assim que estou pensando sobre isso em alto nível:

1. Tenha uma maneira de coletar automaticamente todos os atalhos de teclado no núcleo Atom e em todos os pacotes principais. Qualquer coisa discutida no manual de vôo, basicamente.
2. Substitua todos os pressionamentos de tecla no livro por referências de comando Atom.
3. Tenha uma maneira de substituir automaticamente as referências de comando por pressionamentos de tecla, usando os atalhos de teclado coletados da etapa 1.
4. Tem uma maneira de mostrar um ou mais pressionamentos de tecla para cada referência com base no sistema operacional selecionado. Para formatos de saída diferentes, provavelmente funcionará de maneira diferente. Por exemplo, na versão HTML, podemos usar um seletor, mas na versão PDF podemos fazer outra coisa.

Parece uma ótima ideia. Eu gostaria de contribuir com algum tempo para que isso aconteça (já que eu também o transferi para o site de Ajuda: stick_out_tongue_winking_eye :).

Para os documentos de ajuda, escrevemos conteúdo específico do sistema operacional como este :

{{#mac}}

Apples

{{/mac}}

{{#windows}}

Oranges

{{/windows}}

Os documentos de Ajuda também detectam seu sistema operacional por padrão; você é livre para escolher entre eles se essa for sua preferência (assim como modificar o hash da URL para fornecer um hardlink ).

Esse problema meio que me "estimulou" @ # 112 (obrigado @lee-dohm por me apontar na direção certa;)).

Achei a pergunta de @mnquintana uma boa para se ter em mente. Como as exportações de e-books seriam tratadas? Entre as 2 opções mencionadas, eu definitivamente escolheria a abordagem de versão específica da plataforma (em vez de listar todos os atalhos de teclado embutidos).

Além disso, e depois de verificar as tarefas mencionadas no atom / atom # 7995, parece que não há trabalho planejado para trabalhar nesse assunto, certo?

Acabei de encerrar um tópico que levantei porque é semelhante a este (https://discuss.atom.io/t/keyboard-mapping-for-windows/23220). Como um novato, estou tendo um pesadelo ao aprender mapeamentos de teclado no Windows. O mapeamento do teclado documentado no manual de vôo não corresponde ao que acontece no windows, e mesmo o mapeamento do teclado no próprio Atom nem sempre funciona como o esperado. O que se deve fazer? Por exemplo, no manual de vôo, ctrl-t é documentado como caracteres de transposição, o que parece uma função útil. Como faço para invocar isso no Atom no Windows? ctrl-t, apenas abre o arquivo que está destacado na visualização em árvore. Se eu conseguir fazer isso funcionar, será mais fácil descobrir como fazer as outras funções que não consigo fazer, pois estão listadas no mapa de teclas do Atom.

@TheNephilim você pode usar a guia Atalhos de teclado na Visualização de configurações no Atom para descobrir quais atalhos de teclado são realmente usados ​​em sua plataforma. Você pode chegar aqui por:

1. Lançando Atom
2. Abrindo a visualização de configurações com Ctrl +, no Windows ou Linux
3. Clicar na guia "Atalhos de teclado" à esquerda

Uma vez aqui, você pode pesquisar o comando que deseja digitando apenas parte do nome do comando na caixa de pesquisa:

(Estou no OS X, então a combinação de teclas é Ctrl + T para mim. A combinação de teclas provavelmente é diferente.)

Obrigado Lee por sua ajuda. Na verdade, essa guia de atalhos de teclado é bastante útil. No entanto, quando procuro a função transpor, não há mapeamento de teclas para ela, o que torna essa função específica totalmente inútil. É mais rápido inverter os caracteres manualmente, em vez de invocar os atalhos de teclado e digitar transpor. Então, para mim, parece que foi implementado para OSX de uma forma útil, mas para todos os outros, ficamos apenas pendurados. O que me faz pensar, quais outras funções foram negligenciadas no Windows, e por que isso não se tornou mais consistente com o OSX. Não há razão para que ctrl-T não seja igual no Windows. E já que estou nisso, qual é a diferença entre ctrl-t e ctrl-T. O último exigiria a tecla shift, mas essa é uma combinação de teclas diferente. (Espero que não seja uma pergunta muito boba)

Não tenho uma máquina Windows (ou Linux) à mão, então não posso comentar por que ela não foi implementada para outros sistemas operacionais. Tentamos manter as coisas o mais consistentes possível em todas as plataformas.

Um problema com o mapeamento de atalhos de teclado no Windows (e até certo ponto no Linux) versus OS X é que o OS X tem mais uma tecla modificadora do que o Windows. OS X tem Shift , Ctrl , Alt (também chamado de Option ) e finalmente Cmd . A tecla Cmd no OS X é igual à tecla Windows no Windows ... mas enquanto o Windows reserva a tecla Windows para funções no nível do sistema operacional, o OS X permite que a tecla Comando seja usada para funções no nível do aplicativo. Se contarmos as combinações no Windows:

• 73 teclas primárias (alfanuméricas, símbolo, Esc , teclas de função e navegação)
• 3 teclas modificadoras

Se estou me lembrando de minhas combinatórias corretamente, são 73 * 2 * 2 * 2 = 584 combinações de teclas possíveis. No OS X há o dobro, 1168. Isso significa que é mais difícil encontrar uma combinação de teclas não conflitante no Windows do que no OS X. O que também significa que, para deixar algumas das "boas chaves" para pacotes ... pode haver algumas funções que não são mapeadas no Windows que podem ser mapeadas no OS X.

Você tentou pesquisar ctrl-t na visualização de atalhos de teclado para ver se já está mapeado para outra coisa?

E já que estou nisso, qual é a diferença entre ctrl-t e ctrl-T.

Se você está perguntando qual é a diferença entre ctrl-t na captura de tela e meu Ctrl + T em meu comentário, a resposta é que não há diferença além dos estilos notacionais. Ou eu entendi mal sua pergunta?

Obrigado Lee. Você entendeu minha pergunta sobre ctrl-t e ctrl-T corretamente. Na verdade, pensei que eram iguais, mas não pude ter certeza porque vi maiúsculas e minúsculas especificadas, e devido à dificuldade que tenho tido para invocar algumas funções pelo teclado, pensei que talvez caso deve ser levado em consideração.

Como estou usando um teclado apple no Windows 7 com bootcamp, tentarei definir um mapa de teclado personalizado que use a tecla fn. Talvez assim eu possa tentar consertar as anomalias que estou experimentando, mas é uma pena, porque eu só quero usar o Atom o mais próximo possível da configuração padrão e sem ter que pular obstáculos, como me lembro de ter feito uma das reivindicações no material promocional do Atom. Ansioso para que isso seja resolvido adequadamente.

Uma coisa seria se transpor fosse atribuído a outra coisa, mas " editor: transpor " nem está nas configurações do Windows.

Isso torna a documentação confusa na melhor das hipóteses, e enganosa na pior. Apertei as teclas esperando que algo acontecesse e algo totalmente diferente acontecesse.

Seria bom se a versão do Windows também usasse ligações do tipo Emacs ... Você sabe, como o Emacs para Windows faz. No momento, grande parte da documentação sobre atalhos de teclado é confusa e irrelevante para usuários do Windows.

Eu finalmente consegui construir isso. Ele está ativo no site agora, embora eu tenha apenas construído a infraestrutura. Ainda tenho que revisar e atualizar todas as combinações de teclas para o novo padrão .

Se você quiser ver o novo sistema em ação, pode vê-lo aqui:

http://flight-manual.atom.io/using-atom/sections/editing-and-deleting-text/