Lien vers les sections de la page de manuel?

13

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

Il serait bon d'avoir une version en ligne des pages de manuel Ubuntu avec des liens directs dans les sous-sections. Cela permettrait de 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 quelles manières cela serait utile. Je ne pense pas qu'une solution complète soit disponible quelque part, donc la question est

Quelles solutions partielles existent aujourd'hui?

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


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

Cela signifie que si je veux pointer vers la section "Expansion des paramètres" en man bashligne, je dois utiliser

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

Cela ouvre la page de manuel bash en haut, comme une longue page Web.

Dans la coquille, je peux dire

Voir man bash | less "+/Parameter Expansion"

qui saute au bon endroit au démarrage.


Il serait vraiment utile d'avoir des ancres de liens nommées comme les en-têtes vers lesquels elles pointent. Les ancres nommées par une sorte de numéro d'index seraient toujours utiles, mais nécessitent une recherche manuelle sur la page Web réelle pour l'utiliser.

Comme il n'est pas difficile au niveau HTML d'ajouter des ancres aux titres, je suis sûr que de telles pages de manuel existent;
Mais y a-t-il une collection de pages de manuel Ubuntu avec des ancres en ligne quelque part, ou au 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
qui redirige en quelque sorte 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 accéder directement à 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
       [ ... ]


Cela 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 comme

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


Utilisation d'autres documents de référence

Dans de nombreux cas, des documents de référence alternatifs sont disponibles, à l'exception de la page de manuel. Celles-ci ont souvent une bonne structure de liens qui est utilisée pour faire le lien entre une table des matières et les sections, exactement ce dont nous avons besoin.
Mais cela ne résout pas le problème général , car il n'existe aucun moyen commun de savoir si / où un tel document existe et d'utiliser la structure des liens.

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

Bash Reference Manual section Shell-Parameter-Expansion
écrit comme
[Bash Reference Manual section Shell-Parameter-Expansion] (http://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion)

Mise en œuvre proposée

Pour proposer la mise en œuvre effective de cette idée sur 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 HTML a tags pour autoriser les liens externes vers des sous-sections de man pages

Volker Siegel
la source
3
Ça semble être une bonne idée. Veuillez déposer un rapport de bogue pour cela.
Florian Diesch
@FlorianDiesch Bien sûr, c'est la partie évidente;) En fait, manpages.ubuntu.com ressemble à une implémentation très propre, mais je me souviens que c'est fait par un seul développeur. Voyons voir ...
Volker Siegel
1
@AlaaAli Meta est uniquement destiné aux questions sur Ask Ubuntu , pas sur le projet Ubuntu ou d'autres sites Web liés à Ubuntu.
Eliah Kagan
1
Au fait, j'ai écrit une question très similaire ici: unix.meta.stackexchange.com/q/3960/135943
Wildcard

Réponses:

7

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

PS. Ajoutez le site à vos moteurs de recherche, puis vous pouvez simplement taper man printfvotre barre d'adresse, et cela vous amènera à la bonne page, super génial!

Gerhard Burger
la source
1
Excellente idée pour l'intégration du navigateur comme moteur de recherche!
Philipp Wendler
Votez sans commentaire?
Gerhard Burger
2

Sur unix.stackexchange , il existe également des moyens d' utiliser les pages de manuel hors ligne comme hypertexte . Le moyen le plus simple pour moi semble w3mman, qui fait partie du package w3m, donc:

sudo apt-get install w3m

Lorsque vous avez ouvert une page de manuel, fe w3mman man, vous pouvez utiliser TABpour naviguer vers le lien suivant. (D'autres raccourcis clavier typiques de l'homme fonctionnent de la même manière: défilement, recherche, fermeture :-)

Pour désactiver la confirmation de fermeture (comme les mancomportements):

  • Éditer ~/.w3m/config

    • s'il n'existe pas: cp /etc/w3m/config ~/.w3m/
  • ensemble confirm_qq 0

Pour remplacer la commande man normale :

  • Éditer ~/.bashrc

    • ajouter alias man='w3mman'
  • source ~/.bashrc

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

PythoNic
la source