¿Hay alguna razón por la cual la mayoría de las páginas man no incluyen algunos ejemplos comunes? Por lo general, explican todas las opciones posibles, pero eso hace que sea aún más difícil para un principiante entender cómo se usa "generalmente".
52
man jqtiene más de 1000 líneas de ejemplos (en Ubuntu 16.04)Respuestas:
Eso depende de las páginas de manual ... Tradicionalmente, han incluido una sección con ejemplos, pero por alguna razón generalmente falta en las páginas de manual en Linux (y supongo que otras usan comandos GNU, que son la mayoría en estos días). En Solaris, por otro lado, casi todas las páginas de manual incluyen la sección de Ejemplos, a menudo con varios ejemplos.
Si tuviera que adivinar, FSF / GNU ha desalentado durante mucho tiempo el uso de
manpáginas y prefiere que los usuarios usen información para la documentación.infopáginas tienden a ser más amplio que las páginas de manual, y por lo general no incluyen ejemplos.infolas páginas también son más "tópicas", es decir, los comandos relacionados (por ejemplo, comandos para buscar archivos) a menudo se pueden encontrar juntos.Otra razón puede ser que GNU y sus
manpáginas se usan en muchos sistemas operativos diferentes que pueden diferir entre sí (después de todo, hay muchas diferencias solo entre diferentes distribuciones de Linux). La intención puede haber sido que el editor agregue ejemplos relevantes para el sistema operativo / distribución particular, lo que obviamente rara vez se hace.También agregaría que las
manpáginas nunca tuvieron la intención de "enseñar a los principiantes". UNIX fue desarrollado por expertos en informática (antiguo término "piratas informáticos") y destinado a ser utilizado por expertos en informática. Por lo tanto, las páginas de manual no se hicieron para enseñar a un novato, sino para ayudar rápidamente a un experto en informática que necesitaba un recordatorio para alguna opción oscura o un formato de archivo extraño, y esto se refleja en cómo se divide una página de manual.man-páginas por lo tanto se pretende comomanpáginas, por ejemplo. para el formato de archivos de configuración y comandos relacionados / similares.Dicho esto, estoy muy de acuerdo con usted en que las
manpáginas deberían tener ejemplos, ya que pueden explicar el uso mejor que leer la página del manual. Lástima que los ejemplos generalmente no estén disponibles en lasmanpáginas de Linux ...Ejemplo de la parte de ejemplo de una página de manual de Solaris - zfs (1M):
(...) EJEMPLOS Ejemplo 1 Crear una jerarquía del sistema de archivos ZFS Los siguientes comandos crean un sistema de archivos llamado pool / home y un sistema de archivos llamado pool / home / bob. El punto de montaje / export / home está configurado para el sistema de archivos padre y es heredado automáticamente por el sistema de archivos hijo. # zfs create pool / home # zfs set mountpoint = / export / home pool / home # zfs create pool / home / bob Ejemplo 2 Crear una instantánea de ZFS El siguiente comando crea una instantánea llamada ayer. Esta instantánea se monta bajo demanda en .zfs / snapshot directorio en la raíz del sistema de archivos pool / home / bob. # grupo de instantáneas zfs / inicio / bob @ ayer Ejemplo 3 Crear y destruir múltiples instantáneas El siguiente comando crea instantáneas llamadas ayer de pool / home y todos sus sistemas de archivos descendientes. Cada la instantánea se monta bajo demanda en el directorio .zfs / snapshot en la raíz de su sistema de archivos. El segundo comando destruye las instantáneas recién creadas. # instantánea de zfs -r pool / home @ ayer # zfs destroy -r pool / home @ ayer SunOS 5.11 Último cambio: 23 de julio de 2012 51 Comandos de administración del sistema zfs (1M) Ejemplo 4 Deshabilitar y habilitar la compresión del sistema de archivos El siguiente comando deshabilita la propiedad de compresión para (...)Esta página de manual en particular viene con 16 (!) Tales ejemplos ... ¡Felicitaciones a Solaris!
(Y admito que yo mismo he seguido la mayoría de estos ejemplos, en lugar de leer la página de manual completa para este comando ...)
fuente
zfs) están diseñados de forma bastante natural. Por ejemplo,zfs destroy pool/filesystemes un uso básico y está bien para el 90% de los casos de uso. Las opciones cortas como-rforrecursiveson más especiales y necesitan consulta antes de su uso, ya que pueden tener efectos secundarios no deseados.No creo que haya una buena respuesta para esto. Es una cosa de cultura. Algunas páginas man tienen ejemplos de uso. Por ej
man rsync. Puede intentar cambiar la cultura escribiendo al autor de la página de manual y pidiéndole que agregue algunos ejemplos de uso o (mucho mejor) ofreciéndole algunos ejemplos de uso. Si le ofrece a un autor de software gratuito un parche, particularmente un parche de documentación, es aproximadamente diez mil veces más probable que logre el resultado deseado que una simple solicitud.fuente
Depende:
Para algunos programas, los desarrolladores prefieren proporcionar programas o scripts de muestra que muestren cómo utilizar un programa (o biblioteca) determinado. Nuevamente, esto se hace para resolver un problema: hacer que el programa sea más fácil de probar.
Algunos de los ejemplos pueden basarse en informes de errores de los usuarios y, cuando son breves, encuentran un lugar en el manual. Raramente se proporcionan ejemplos largos en los manuales, y los ejemplos cortos tienen el problema de que tienden a ser triviales, repetitivos y no proporcionan al usuario tanta información como una descripción bien organizada de la forma en que funciona un programa.
fuente
Si está buscando una alternativa a las páginas man, siempre puede probar páginas bro , que solo muestran varios ejemplos de un comando, que luego puede votar entre una lista de ejemplos enviados por la comunidad. Por ejemplo, el comando
bro tarte dará:fuente