☰

Vinculando para seções da página de manual?

tag-icon • tag-icon documentation html manpage
Vinculando para seções da página de manual?

Páginas de manual on-line em HTML com âncoras de seção?

Seria bom ter uma versão online das páginas de manual do Ubuntu com links diretos para subseções. Isso permitiria indicar a alguém a documentação relevante em muitos casos - por exemplo, nas respostas de vários sites StackExchange.

Descreverei como seria uma solução completa e de que maneira isso seria útil. Não creio que uma solução completa esteja disponível em algum lugar, então a questão é

Quais soluções parciais existem hoje?

Por exemplo, formas sistemáticas de pesquisar nas páginas de manual, em vez de vincular, seriam uma solução parcial.


As páginas de manual empáginas de manual.ubuntu.comresolvem a maior parte do problema, mas não possuem âncoras nos títulos ou seções.

Isso significa que, se eu quiser apontar para a seção "Expansão de Parâmetros" em man bashon-line, tenho que usar

Consulte "Expansão de parâmetros" emman bash
[...e use seu navegador para pesquisar "Expansão de parâmetros"]

Isso abre a página de manual do bash na parte superior, como uma longa página da web.

Na casca, posso dizer

Verman bash | less "+/Parameter Expansion"

que salta para o lugar certo na inicialização.


Seria muito útil ter âncoras de link nomeadas de acordo com os títulos para os quais apontam. Âncoras nomeadas por algum tipo de número de índice ainda ajudariam, mas exigiriam uma pesquisa manual na página da web real para serem usadas.

Como não é difícil no nível HTML adicionar âncoras aos títulos, tenho certeza de que tais páginas de manual existem;
Mas existe uma coleção dePáginas de manual do Ubuntu com âncorasonline em algum lugar, ou pelo menos um bom subconjunto?

Código de exemplo

O cabeçalho da seção "Expansão de parâmetros" de
http://manpages.ubuntu.com/bash
que meio que redireciona para
http://manpages.ubuntu.com/manpages/trusty/en/man1/bash.1.html

       [ ... ]
       tildes in assignments to <b>PATH</b>, <b>MAILPATH</b>,  and  <b>CDPATH</b>,  and  the  shell
       assigns the expanded value.

   <b>Parameter</b> <b>Expansion</b>
       The `<b>$</b>' character introduces parameter expansion, command substitution,
       or arithmetic expansion.  The parameter name or symbol to  be  expanded
       [ ... ]

Para poder vincular diretamente a esta seção, precisamos de algo como:

       [ ... ]
       tildes in assignments to <b>PATH</b>, <b>MAILPATH</b>,  and  <b>CDPATH</b>,  and  the  shell
       assigns the expanded value.

   <a href="#ParameterExpansion"><b>Parameter</b> <b>Expansion</b></a>
       The `<b>$</b>' character introduces parameter expansion, command substitution,
       or arithmetic expansion.  The parameter name or symbol to  be  expanded
       [ ... ]


Isso adiciona uma tag ao código HTML e um atributo, o nome da seção sem espaços:

<b>Parameter</b> <b>Expansion</b>
<a href="#ParameterExpansion"><b>Parameter</b> <b>Expansion</b></a>

Agora, podemos vincular à seção como

http://manpages.ubuntu.com/bash#ParameterExpansion
ou mesmo
manpages.ubuntu.com/bash#ParameterExpansion

que usa uma nota de rodapé e é escrito como
[manpages.ubuntu.com/bash#ParameterExpansion][6]

Uso de outros documentos de referência

Em muitos casos, existem documentos de referência alternativos disponíveis, além da página de manual. Eles geralmente têm uma boa estrutura de links que é usada para vincular um índice às seções, exatamente o que precisamos.
Mas issonão resolve o problema geral, pois não há uma maneira comum de descobrir se/onde tal documento existe e de fazer uso da estrutura de links.

Para o exemplo bash usado acima, oManual de referência do Bashpoderia ser usado como uma solução individual pesquisada manualmente:

Seção do Manual de Referência do Bash Shell-Parameter-Expansion
escrito como
[seção do Manual de Referência do Bash Shell-Parameter-Expansion](http://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion)

Implementação proposta

Propor implementar efectivamente esta ideia empáginas de manual.ubuntu.com,
registrei uma solicitação de bug/aprimoramento intimamente relacionada no projeto associado "ubuntu-manpage-repository": launchpad #1355271: Use tags HTML a para permitir links externos para subseções de páginas de manual

Responder1

Sim, existe, éhttp://man.cx/. O objetivo é ter todas as páginas de manual em um site, também em vários idiomas. Infelizmente, as âncoras não têm nome, mas são numeradas: por exemplohttp://man.cx/printf#heading1o levará ao primeiro título da printfpágina de manual. Mesmo assim acho melhor do que sem âncoras ;)

PS. Adicione o site aos seus mecanismos de busca, basta digitar man printfna barra de endereço e ele o levará para a página correta, super incrível!

Responder2

Sobreunix.stackexchange, existem maneiras descritas parause as páginas de manual offline como hipertextotambém. A maneira mais fácil para mim parece ser o w3mman, que faz parte do pacote w3m, então:

sudo apt-get install w3m

Quando você abre uma página de manual, fe w3mman man, você pode usar TABpara navegar para o próximo link. (Outros atalhos de teclado típicos funcionam da mesma forma: rolar, pesquisar, sair :-)

Para desativar a confirmação de encerramento (como manse comporta):

  • editar~/.w3m/config

    • se não existir:cp /etc/w3m/config ~/.w3m/

  • definirconfirm_qq 0

Para substituir o normalhomemcomando:

  • editar~/.bashrc

    • adicionaralias man='w3mman'

  • source ~/.bashrc

Agora man <some command>vou usar w3mman em vez do homem normal :) Gosto assim. Obrigado por perguntar! :)

Responder3

8 anos depois,
vincular páginas de manual com âncoras de seção ainda não é fácil hoje.

A página de manual do archlinux parece ser a única que conheço

homem do archlinux

tem algumas âncoras, mas não o suficiente

um link de demonstração: https://man.archlinux.org/man/bash.1.en#extglob

homem gnu

tem algumas âncoras

link de demonstração: https://www.gnu.org/software/bash/manual/bash.html#Indexes
https://www.gnu.org/software/bash/manual/bash.html#Pattern-Matching

informação relacionada