Lendo e pesquisando longas páginas de manual

Eu finalmente se encheu quando se quer ler sobre o bash 's read-lo de e -sopção com man bash. Eu encontrei o local certo eventualmente (por volta da linha 4500), mas foi frustrante, como sempre, pois as pesquisas /reade até as /\s-s\spesquisas têm muitas correspondências.

Portanto, a pergunta é: como posso ler páginas de manual longas com eficiência ou obter as mesmas informações de outras maneiras localmente ? Como um exemplo específico, como alcançar a documentação relevante depois de ver read -s pwdem um script de shell? Uma boa resposta pode ser um trecho de script de shell, ou dica sobre alguma ferramenta e como ela é usada, ou algo completamente diferente, desde que ajude a encontrar o local certo para ler.

Nota: Não estou marcando com bash porque quero que a pergunta seja sobre a leitura da página de manual em geral, mesmo que essa seja possivelmente a página de manual mais comum encontrada.

Para obter ajuda rápida em um Bash integrado, use help:

help read

é o que você quer.

Para formatação de página de manual, use

help -m read

ou, melhor ainda,

help -m read | less

Se você ainda insistir em procurá-lo na página de manual, acho que o que rapidamente me leva à explicação de um comando é

/^\s*read [[]

Isso funciona porque, quando um comando é explicado pela primeira vez, seu nome é recuado levemente desde o início da linha. No caso particular de read, isso leva um pouco de navegação antes de você chegar à readdocumentação real , porque (por razões óbvias) a palavra "ler" é repetida muito por toda a página do manual. O [[] significa combinar um [que geralmente precede parâmetros opcionais. (Normalmente deixo de fora / ^ \ s * e simplesmente faço / <comando interno> [[])

Outra alternativa

Se você não se importa com a alteração do formato, pode converter sua página de manual em um arquivo DVI ou PDF:

man -T dvi bash >bash.dvi

ou

man -T ps bash | ps2pdf - bash.pdf # Requires the Ghostscript suite for ps2pdf

Obviamente, dado um documento DVI ou PDF, você pode fazer uma pesquisa de texto facilmente.

Abordagem 1

man bashentão /read \[então/-s

Abordagem 2

Você pode tentar uma ferramenta open source para explicar os argumentos de linha de comando chamados explainshell .

Pode ser usado localmente. Leia a documentação em https://github.com/idank/explainshell

Advertências: Geralmente funciona, mas apenas com comandos encontrados no repositório de páginas de manual do Ubuntu

No seu caso, ele não pode reconhecer a -stroca read -s pwd.

Abordagem 3

Eu encontrei outra ferramenta que parece promissora, mas não funciona no meu sistema.

explicação: Documentação curta para comandos Unix

O que eu costumo fazer neste caso é apenas executar man, procurar o SHELL BUILTIN COMMANDScabeçalho e depois o builtin, ou seja,

man bash
/^SHELL BUILTIN
/  read 

no entanto, no bash você pode fazer

help read

ou, dependendo do sistema, um dos

man 1 read
man bash-builtins

Em geral, eu tenho um script chamado he("ajuda curta") para fazer isso. Você executaria assim:

he bash read

Não existe uma maneira genérica de encontrar informações em uma página de manual, assim como não há uma maneira genérica de encontrar informações em um livro. Depende do que você está procurando.

Ao procurar informações sobre um shell embutido, você pode procurar pelo embutido no início de uma linha, exceto pelo recuo, e seguido por um espaço: pesquise ^ *read␣(por exemplo, tipo /^ *read␣ Enter) ( ␣é um espaço). Isso funciona com dash, pdksh, mksh e bash. A página de manual do Zsh é dividida, portanto você precisa ler a zshbuiltinspágina de manual. O Ksh93 possui símbolos especiais antes dos nomes de alguns componentes internos, você precisa procurar ^ *†*␣em UTF-8 ou ^ *-*␣em ASCII. Existem alguns falsos positivos, mas isso o levará rapidamente à linha certa. A pesquisa ^ *read($| [-[])reduz a quantidade de falsos positivos.

Você pode acelerar a pesquisa dizendo ao seu pager para onde deseja ir. Por exemplo, PAGER='less "+/^ *read \["' man bashabre a página de manual do bash na descrição do readbuiltin. Você pode fazer disso uma função:

man-builtin () {
  PAGER="less '+/^ *$1(\$|\\[|-)'" man ${SHELL##*/}
}

Para pular diretamente para a seção SHELL BUILTINS COMMANDS da página de manual do bash, defino o seguinte alias no meu $HOME/.bash_aliasesarquivo.

alias man-builtin="man -P 'less -p ^SHELL\ BUILTIN\ COMMANDS' bash"

Apenas para oferecer outra alternativa, se você preferir usar um navegador da Web que permita pesquisar facilmente na página atual, você pode usar algo como man.cgi usado no freeBSD.org, que também permite exibir páginas de manual de diferentes sistemas para ver como eles diferem. Eu já vi similar em outros sites, então espero que haja outras variações.

O link de ajuda em apropos oferece algumas informações para obter uma cópia do script para colocar em seu próprio servidor com links para baixar as coleções de páginas de manual.

Comecei a criar uma função bash para esse fim. Este fragmento pode ser, por exemplo, colado no final de ~/.bashrc:

manfind() {
  # required args
  test "$1" -a "$2" || return 1                  

  # create temp file and get its name
  local tmp=$(mktemp /tmp/manfindXXXXXX) || return 1
  ( # subshell for trap
    trap "rm $tmp" EXIT

    # grep all matching lines with line numbers and pipe them to dialog
    if man "$1" |                   # get the whole man page
      grep -n "^\s*$2" |            # grep for the search string, with line nums
      sed 's/:/\n/' |               # replace line num separator with newline for dialog
      cut -c-70  |                  # cut long lines to nice length
      xargs -d'\n' -n 999999 \
        dialog --output-fd 3 --menu "Select line to go to" 0 0 0 3>$tmp -- 1 '(start of man page)'
    then
      # selected line number is now in $tmp, get man page and
      # use vim in read only mode to view it at right line
      man "$1" | vim -R +"$(< $tmp)" -
    else
      # cancel selected from dialog
      exit 1
    fi
  )
}

Comentários explicam um pouco sobre o que fazem. A sequência de pesquisa padrão, em particular, pesquisa uma determinada palavra desde o início das linhas, ignorando o espaço inicial. Exemplos:

# find every line which starts with 'read' followed by space
manfind bash 'read '
# research bash subshells
manfind bash '.*subshell'

Nota: Este script não tem conceito de seções da página de manual ... Vou ver se eu ajusto isso mais tarde, mas a configuração da MANSECTvariável de ambiente man ajuda.

Juntando as peças da outra discussão aqui, aqui está uma função rápida que você pode deixar na sua .bashrcque o levará diretamente ao built-in (se existir). Caso contrário, ele abre mannormalmente:

man() {
    case "$(/bin/bash -c 'type -t '"$1")" in 
        builtin)
            LESS=+?"^       $1 " command -p man bash
            ;;
        *)
            command -p man $@
            ;;
    esac
}

Em qualquer distribuição Linux, você poderá usar info bashse desejar ter parágrafos separados por tipo de ação, onde as informações são idênticas às páginas de manual.