web-dev-qa-db-fra.com

Lien vers les sections de page de manuel?

Pages de manuel en ligne en HTML avec des ancres de section?

Il serait bon d’avoir une version en ligne des pages de manuel Ubuntu avec des liens directs vers des sous-sections. Cela permettrait de faire pointer quelqu'un vers la documentation pertinente dans de nombreux cas - par exemple dans les réponses de divers sites StackExchange.

Je décrirai à quoi pourrait ressembler une solution complète et de quelle manière cela pourrait être utile. Je ne pense pas qu'une solution complète soit disponible quelque part, alors la question est

Quelles solutions partielles existent aujourd'hui?

Par exemple, des solutions systématiques pour rechercher dans les pages de manuel, au lieu de créer des liens, constitueraient une solution partielle.


Les pages de manuel de pages de manuel.ubuntu.com résolvent la plupart du problème, mais elles n'ont pas d'ancrage dans les en-têtes ou les sections.

Cela signifie que si je veux pointer sur la section "Extension de paramètre" dans man bash en ligne, je dois utiliser

Voir "Extension des paramètres" dans man bash
[... et utilisez votre navigateur pour rechercher "Extension de paramètre"]

Cela ouvre la page de manuel bash en haut, en tant que page Web longue.

Dans la coquille, je peux dire

Voir _man bash | less "+/Parameter Expansion"_

qui saute au bon endroit au démarrage.


Il serait vraiment utile de nommer les ancres de liens comme les en-têtes auxquelles elles pointent. Les ancres désignées par un numéro d’index seraient toujours utiles, mais elles nécessiteraient une recherche manuelle sur la page Web pour pouvoir les utiliser.

Comme il n’est pas difficile au niveau HTML d’ajouter des ancres aux en-têtes, je suis sûr que de telles pages de manuel existent;
Mais existe-t-il une collection de pages de manuel Ubuntu avec des ancres en ligne quelque part, ou du moins un bon sous-ensemble?

Exemple de code

L'en-tête de la section "Expansion des paramètres" de
http://manpages.ubuntu.com/bash
Quel type de redirection vers
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
       [ ... ]
_

Pour pouvoir créer un lien direct vers cette section, nous avons besoin de quelque chose comme:

_       [ ... ]
       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
       [ ... ]
_


Ceci ajoute une balise au code HTML et un attribut, le nom de la section sans espaces:

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

Maintenant, nous pouvons créer un lien vers la section telle que

http://manpages.ubuntu.com/bash#ParameterExpansion
ou même
manpages.ubuntu.com/bash#ParameterExpansion

qui utilise une note de bas de page et est écrit comme
[manpages.ubuntu.com/bash#ParameterExpansion][6]

Utilisation d'autres documents de référence

Dans de nombreux cas, il existe d'autres documents de référence disponibles, en dehors de la page de manuel. Ceux-ci ont souvent une bonne structure de liens qui est utilisée pour faire le lien entre une table de contenu et les sections, exactement ce dont nous avons besoin.
Mais ceci ne résout pas le problème général , car il n’existe aucun moyen courant de déterminer si/où un tel document existe, et de utiliser la structure de lien.

Pour l'exemple bash utilisé ci-dessus, le Manuel de référence de Bash peut être utilisé comme solution individuelle recherchée manuellement:

section Manuel de référence de Bash, Shell-Parameter-Expansion
écrit comme
[Section Shell-Parameter-Expansion du manuel de référence Bash] (http://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion)

Mise en oeuvre proposée

Pour proposer réellement la mise en œuvre de cette idée à manpages.ubuntu.com ,
J'ai déposé une demande de bogue/amélioration étroitement liée au projet associé "ubuntu-manpage-repository": tableau de bord # 1355271: utilisez les balises HTML a pour autoriser les liens externes vers des sous-sections de pages de manuel

documentationhtmlmanpage
13
Volker Siegel

Oui, il y a http://man.cx/ . Il vise à avoir toutes les pages de manuel sur un site, également dans plusieurs langues. Les ancres ne sont malheureusement pas nommées, mais numérotées: par exemple, http://man.cx/printf#heading1 vous mènera au premier en-tête de la page de manuel printf. Pourtant je pense que c'est mieux que sans ancres;)

PS Ajoutez le site à vos moteurs de recherche, vous pouvez simplement taper man printf dans votre barre d’adresse, et cela vous mènera à la bonne page, super génial!

7
Gerhard Burger

Sur nix.stackexchange , il existe des méthodes permettant d'utiliser les pages de manuel hors connexion comme hypertexte . Le moyen le plus simple pour moi semble être w3mman, qui fait partie du paquet w3m, donc:

Sudo apt-get install w3m

Lorsque vous avez ouvert une page de manuel, par exemple, w3mman man, vous pouvez utiliser TAB pour accéder au lien suivant. (Les autres raccourcis clavier classiques fonctionnent de la même manière: défilement, recherche, abandon :-)

Pour désactiver la confirmation de fermeture (comme man se comporte):

  • edit ~/.w3m/config

    • si non existant: cp /etc/w3m/config ~/.w3m/

  • set confirm_qq 0

Pour remplacer la commande normale man :

  • edit ~/.bashrc

    • ajouter alias man='w3mman'

  • source ~/.bashrc

Maintenant, man <some command> utilisera w3mman à la place de l'homme normal :) Je l'aime comme ça. Merci d'avoir posé la question! :)

2
PythoNic