Mandoc : ouvrir les manpages aux formats html, markdown, pdf, ps (OpenBSD)

Article publié, le
4 minute(s) de lecture

Cet article contient 664 mots.
Source brute de l'article : MD

Description

Lire les manpages n’est pas forcément agréable, voire aisé - heureusement il est possible avec des outils natifs à OpenBSD de les agrémenter pour en faire une sortie html, markdown, pdf, postscript puis de les lire dans un lecteur adéquat.

De petites fonctions pertinentes à se rajouter dans son ~/.kshrc qui utilisent principalement l’outil mandoc.

Astuce

Dans tous les cas, il est possible de modifier à souhait la variable editor :

Fonction man2html

Testé avec firefox, links+.

Code : sh

man2html() {

    editor=firefox
    [ -n "$1" ] && name="$1"
    [ -z "$2" ] && ext="1" || ext="$2"
        
    tmp="/tmp/$name.$ext.html"

    for dir in /usr/share/man /usr/local/man /usr/X11R6/man; do
        [ -f "$dir/man$ext/$name.$ext" ] && { file="$dir/man$ext/$name.$ext"; break; }
    done

    [ -f "$file" ] && mandoc -K utf-8 -T html -O toc "$file" > "$tmp"
    [ -f "$tmp" ] && $editor "$tmp"

    unset editor ext file name tmp`

}

Utilisation

man2html nom-manpage numero-section-manpage - s’il n’y a pas de numéro de section, alors la fonction essaye d’appeler le manpage de la section 1.

Exemple : $ man2html man

Fonction man2md

Testé avec geany

Code : sh

man2md() {

    editor=geany
    [ -n "$1" ] && name="$1"
    [ -z "$2" ] && ext="1" || ext="$2"

    tmp="/tmp/$name.$ext.md"

    for dir in /usr/share/man /usr/local/man /usr/X11R6/man; do
        [ -f "$dir/man$ext/$name.$ext" ] && { file="$dir/man$ext/$name.$ext"; break; }
    done

    [ -f "$file" ] && mandoc -K utf-8 -T markdown "$file" > "$tmp"
    [ -f "$tmp" ] && $editor "$tmp" 

    unset editor ext file name tmp`

}

Utilisation

man2md nom-manpage numero-section-manpage - s’il n’y a pas de numéro de section, alors la fonction essaye d’appeler le manpage de la section 1.

Exemple : $ man2md hostname.if 5

Fonction man2pdf

Testé avec evince.

Code : sh

man2pdf() {

    editor=evince
    [ -n "$1" ] && name="$1"
    [ -z "$2" ] && ext="1" || ext="$2"

    tmp="/tmp/$name.$ext.pdf"

    for dir in /usr/share/man /usr/local/man /usr/X11R6/man; do
        [ -f "$dir/man$ext/$name.$ext" ] && { file="$dir/man$ext/$name.$ext"; break; }
    done

    [ -f "$file" ] && mandoc -K utf-8 -T pdf "$file" > "$tmp"
    [ -f "$tmp" ] && $editor "$tmp" && rm -fP "$tmp"

    unset editor ext file name tmp`

}

Utilisation

man2pdf nom-manpage numero-section-manpage - s’il n’y a pas de numéro de section, alors la fonction essaye d’appeler le manpage de la section 1.

Exemple : $ man2pdf man.conf 5

Fonction man2ps

Testé avec gs, ghostview

Code : sh

man2ps() {

    editor=gs
    [ -n "$1" ] && name="$1"
    [ -z "$2" ] && ext="1" || ext="$2"

    tmp="/tmp/$name.$ext.ps"

    for dir in /usr/share/man /usr/local/man /usr/X11R6/man; do
        [ -f "$dir/man$ext/$name.$ext" ] && { file="$dir/man$ext/$name.$ext"; break; }
    done

    [ -f "$file" ] && mandoc -K utf-8 -T ps "$file" > "$tmp"
    [ -f "$tmp" ] && $editor "$tmp" 

    unset editor ext file name tmp`

}

Utilisation

man2ps nom-manpage numero-section-manpage - s’il n’y a pas de numéro de section, alors la fonction essaye d’appeler le manpage de la section 1.

Exemple : $ man2ps dhclient 8

Fonction man2doc

LA fonction qui réunit toutes les précédentes !!!

Code : sh

man2doc() {

    #ed2html=firefox 
    #ed2md=geany 
    #ed2pdf=evince 
    #ed2ps=gs

    [ -n "$1" ] && format="$1"
    [ -n "$2" ] && name="$2"
    [ -z "$3" ] && nb="1" || nb="$3"

    #eval "editor=\${ed2$format}"

    tmp="/tmp/$name.$nb.$format"
    [ -f "$tmp" ] && rm -fP "$tmp"

    case "$format" in 
        "md") type="markdown" ;;
        *) type="$format" ;;
    esac

    for file in $(find /usr/{local,share,X11R6}/man/ -name $name.$nb)do mandoc -K utf-8 -T "$type" "$file" >> "$tmp"done

    [ -f "$tmp" ] && xdg-open "$tmp"    # $editor

    unset editor file format name nb tmp

}

Utilisation

À la différence des précédentes fonctions, cette dernière cherchera tous les manpages correspondants, et les incluera les uns à la suite des autres…

man2doc format-fichier nom-manpage numero-section-manpage.

  • format-fichier : html, md, pdf, ou ps
  • Toujours si le numéro de section n’est pas spécifié, la fonction cherchera dans la section 1.

Exemples :

  • $ man2doc html man
  • $ man2doc pdf doas.conf 5
  • $ man2doc md makewhatis 8
  • $ man2doc ps vmm 4

Inspiré par Mi@mondo