Lecture et recherche de longues pages de manuel

J'ai finalement eu marre quand on veut lire bash « s readet de l' -soption avec man bash. J'ai finalement trouvé le bon endroit (vers la ligne 4500), mais c'était frustrant comme d'habitude, car les recherches /readet même les /\s-s\srecherches ont beaucoup trop de correspondances.

La question est donc la suivante: comment lire efficacement de longues pages de manuel ou obtenir les mêmes informations d'une autre manière, localement ? À titre d'exemple spécifique, comment accéder à la documentation pertinente après avoir vu read -s pwddans un script shell? Une bonne réponse pourrait être un extrait de script shell, ou un indice sur un outil et la façon dont il est utilisé, ou quelque chose d'autre, tant qu'il aide à trouver le bon endroit pour lire.

Remarque: Je ne tague pas avec bash parce que je veux que la question porte sur la lecture des pages de manuel en général, même si c'est probablement la page de manuel la plus fréquemment rencontrée.

Pour obtenir rapidement de l'aide sur un module intégré Bash, utilisez help:

help read

c'est ce que tu veux.

Pour un formatage semblable à une page de manuel, utilisez

help -m read

ou, mieux encore,

help -m read | less

Si vous insistez toujours pour le rechercher dans la page de manuel, je trouve que ce qui m'amène rapidement à l'explication d'une commande est

/^\s*read [[]

Cela fonctionne car lorsqu'une commande est expliquée pour la première fois, son nom est légèrement en retrait depuis le début de la ligne. Dans le cas particulier de read, cela demande un peu de navigation avant d'accéder à la readdocumentation réelle car (pour des raisons évidentes) le mot "lire" est répété beaucoup tout au long de la page de manuel. Le [[] signifie faire correspondre un [qui précède généralement les paramètres facultatifs. (Je laisse généralement de côté / ^ \ s * et je fais simplement / <commande intégrée> [[])

Une autre alternative

Si le changement de format ne vous dérange pas, vous pouvez convertir votre page de manuel en fichier DVI ou PDF:

man -T dvi bash >bash.dvi

ou

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

Bien sûr, étant donné un document DVI ou PDF, vous pouvez ensuite effectuer une recherche de texte facilement.

Approche 1

man bashpuis /read \[alors/-s

Approche 2

Vous pouvez essayer un outil open source pour expliquer les arguments de la ligne de commande appelé expliquehell .

Il peut être utilisé localement. Lisez la documentation sur https://github.com/idank/explainshell

Avertissements: fonctionne généralement, mais uniquement avec les commandes trouvées dans le référentiel de pages de manuel d'Ubuntu

Dans votre cas, il ne peut pas reconnaître l' -sinterrupteur read -s pwd.

Approche 3

J'ai trouvé un autre outil qui semble prometteur mais qui ne fonctionne pas sur mon système.

expliquer: documentation courte pour les commandes Unix

Ce que je fais habituellement dans ce cas, c'est juste lancer man, rechercher l'en- SHELL BUILTIN COMMANDStête, puis rechercher le builtin, c'est-à-dire

man bash
/^SHELL BUILTIN
/  read 

cependant, en bash, vous pouvez faire

help read

ou, selon le système, soit

man 1 read
man bash-builtins

En général, j'ai un script appelé he("aide courte") pour ce faire. Vous le feriez comme ceci:

he bash read

Il n'y a pas de moyen générique pour trouver des informations dans une page de manuel, pas plus qu'il n'y a de manière générique pour trouver des informations dans un livre. Cela dépend de ce que vous recherchez.

Lorsque vous recherchez des informations sur un shell intégré, vous pouvez rechercher le builtin au début d'une ligne sauf pour l'indentation, et suivi d'un espace: rechercher ^ *read␣(par exemple, type /^ *read␣ Enter) ( ␣est un espace). Cela fonctionne avec dash, pdksh, mksh et bash. La page de manuel de Zsh est divisée, vous devez donc lire la zshbuiltinspage de manuel. Ksh93 a des symboles spéciaux devant les noms de certaines fonctions internes, vous devez rechercher ^ *†*␣en UTF-8 ou ^ *-*␣en ASCII. Il y a quelques faux positifs mais cela vous amènera rapidement à la bonne ligne. La recherche ^ *read($| [-[])réduit le nombre de faux positifs.

Vous pouvez accélérer la recherche en indiquant à votre téléavertisseur où vous voulez aller. Par exemple, PAGER='less "+/^ *read \["' man bashouvre la page de manuel bash sur la description de la fonction readintégrée. Vous pouvez en faire une fonction:

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

Pour accéder directement à la section SHELL BUILTINS COMMANDS de la page de manuel bash, je définis l'alias suivant dans mon $HOME/.bash_aliasesfichier.

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

Juste pour offrir une autre alternative, si vous préférez utiliser un navigateur Web qui vous permet de rechercher facilement dans la page actuelle, vous pouvez utiliser quelque chose comme man.cgi utilisé sur freeBSD.org qui vous permet également de visualiser les pages de manuel de différents systèmes pour voir comment ils diffèrent. J'ai vu similaire sur d'autres sites, alors attendez-vous à d'autres variations.

Le lien d'aide sous apropos offre quelques informations pour obtenir une copie du script à mettre sur votre propre serveur avec des liens pour télécharger les collections de pages de manuel.

Je me suis mis à créer une fonction bash à cet effet. Cet extrait peut être par exemple collé à la fin 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
  )
}

Les commentaires expliquent un peu ce qu'il fait. La chaîne de recherche par défaut, en particulier, recherche un mot donné depuis le début des lignes, en sautant l'espace initial. Exemples:

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

Remarque: Ce script n'a pas de concept de sections de page de manuel ... Je verrai si je modifie cela plus tard, mais la définition de MANSECTla variable d'environnement de man aide.

Pour rassembler les éléments de l'autre discussion , voici une fonction rapide que vous pouvez laisser dans votre .bashrcqui vous amènera directement à la fonction intégrée (si elle existe). Sinon, il s'ouvre mannormalement:

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

À partir de n'importe quelle distribution Linux, vous devriez pouvoir l'utiliser info bashsi vous voulez avoir des paragraphes séparés par type d'action où les informations sont identiques aux pages de manuel.