{"id":51,"date":"2013-10-17T19:30:00","date_gmt":"2013-10-17T19:30:00","guid":{"rendered":"http:\/\/esferas.org\/msqlu\/2013\/10\/17\/las-paginas-de-manual-de-los-scripts\/"},"modified":"2013-10-17T19:30:00","modified_gmt":"2013-10-17T19:30:00","slug":"las-paginas-de-manual-de-los-scripts","status":"publish","type":"post","link":"https:\/\/esferas.org\/msqlu\/2013\/10\/17\/las-paginas-de-manual-de-los-scripts\/","title":{"rendered":"Las p\u00e1ginas de manual de los scripts &#8230;"},"content":{"rendered":"<div class='__iawmlf-post-loop-links' style='display:none;' data-iawmlf-post-links='[{&quot;id&quot;:1378,&quot;href&quot;:&quot;http:\\\/\\\/www.linuxjournal.com\\\/content\\\/creating-custom-man-pages&quot;,&quot;archived_href&quot;:&quot;https:\\\/\\\/web-wp.archive.org\\\/web\\\/20260415213017\\\/https:\\\/\\\/www.linuxjournal.com\\\/content\\\/creating-custom-man-pages&quot;,&quot;redirect_href&quot;:&quot;https:\\\/\\\/www.linuxjournal.com\\\/content\\\/creating-custom-man-pages&quot;,&quot;checks&quot;:[],&quot;broken&quot;:false,&quot;last_checked&quot;:null,&quot;process&quot;:&quot;done&quot;},{&quot;id&quot;:1379,&quot;href&quot;:&quot;http:\\\/\\\/mvertes.free.fr\\\/txt2man&quot;,&quot;archived_href&quot;:&quot;&quot;,&quot;redirect_href&quot;:&quot;http:\\\/\\\/mvertes.free.fr\\\/txt2man\\\/&quot;,&quot;checks&quot;:[],&quot;broken&quot;:false,&quot;last_checked&quot;:null,&quot;process&quot;:&quot;done&quot;}]'><\/div>\n<p><img loading=\"lazy\" decoding=\"async\" alt=\"debian-logo\" src=\"https:\/\/esferas.org\/mt\/msqlu\/logos\/openlogo-100.png\" class=\"mt-image-left\" style=\"float: left; margin: 0 20px 20px 0;\" height=\"123\" width=\"100\" \/>&#8230; tambi\u00e9n son necesarias. A ver si aprendemos.<\/p>\n<\/p>\n<p><!--more--><\/p>\n<p>Creo que ya lo he mencionado antes pero por si acaso alguien se lo ha perdido lo cuento de nuevo. Llevo algunos a\u00f1os creando software para mi empresa que funciona espec\u00edfica y concretamente en Debian. Construyo los paquetes nativos y mantengo un repositorio para actualizar todas las m\u00e1quinas de una manera que yo considero c\u00f3moda.<\/p>\n<p>Hasta ahora no he echado en falta los detalles porque eran aplicaciones muy autocontenidas y pod\u00eda saber lo que estaban haciendo. Pero ahora, como desde hace unos meses he refactorizado varias de ellas, tengo una peque\u00f1a gran colecci\u00f3n de paquetes con sus correspondientes <em>scripts<\/em> y las dependencias entre ellos. Ya no puedo saber qu\u00e9 hace un programa simplemente analizando su nombre; antes algo como <em>imprimir-facturas-venta<\/em> era informativo. Ahora algo como <em>ucs-build-root-trace<\/em> me fuerza a mirar el c\u00f3digo en el ejecutable o en el repositorio de donde viene. Y como no siempre incluyen un par\u00e1metro <em>help<\/em> que me ense\u00f1e qu\u00e9 hacen empiezo a ponerme un poco tenso.<\/p>\n<p>He buscado una soluci\u00f3n que me sea m\u00e1s o menos c\u00f3moda. Cuando escribo programas Perl no tengo ning\u00fan problema. La documentaci\u00f3n est\u00e1 contenida en los fuentes y existen herramientas autom\u00e1ticas de sobra para construir p\u00e1ginas de manual e instalarlas en los lugares adecuados del sistema operativo. Pero si los scripts est\u00e1n hechos en otro lenguaje no quiero tener que aprender m\u00e1s herramientas; me bastar\u00eda con algo tipo formulario, donde escribiese la informaci\u00f3n m\u00ednima, y que luego, autom\u00e1gicamente, se convirtiese en una p\u00e1gina de manual est\u00e1ndar.<\/p>\n<p>Una entrada en <a href=\"http:\/\/www.linuxjournal.com\/content\/creating-custom-man-pages\">Linux Journal<\/a> me ha puesto sobre la pista del programa <a href=\"http:\/\/mvertes.free.fr\/txt2man\/\">txt2man<\/a> de Marc Vertes y le he dado una oportunidad para ver si puedo integrarlo r\u00e1pidamente en mi ciclo de desarrollo.<\/p>\n<p>Este programa lee un archivo de texto plano, busca en \u00e9l secuencias concretas que identifican las secciones y crea el fuente correspondiente en formato <em>troff\/groff\u00a0<\/em>(residuo de otros tiempos y que funciona maravillosamente siempre que est\u00e9 muy, muy lejos de un humano). <span style=\"text-decoration: underline;\"><\/span><\/p>\n<p>El texto de entrada puede ser algo tan sencillo como lo siguiente:<\/p>\n<pre><br \/>NAME\n    scriptname - script short description\nSYNOPSIS\n    Example of use\nDESCRIPTION\n    Long description \nOPTIONS\n  -h    Show help\n  -v    Show version\nENVIRONMENT\n    Special environment settings\nBUGS \n    List of program's bugs\nAUTHOR\n    Victor Moral \n\n<\/pre>\n<p>La integraci\u00f3n de este programa en mi desarrollo la he conseguido mezclando los siguientes elementos:<\/p>\n<ol>\n<li>Creaci\u00f3n de un directorio con las p\u00e1ginas de manual en <em>docs\/manpages.<\/em><\/li>\n<li>Creaci\u00f3n de unas reglas en el archivo Makefile que reconstruyen la versi\u00f3n final reconocible por la extensi\u00f3n <em>.1<\/em> desde el fuente correspondiente con la extensi\u00f3n <em>.txt<\/em>.<\/li>\n<li>A\u00f1adir a la instalaci\u00f3n en el archivo Makefile la copia de las p\u00e1ginas finales en el directorio correspondiente del sistema. <\/li>\n<li>Ignorar las p\u00e1ginas con la extensi\u00f3n final en el repositorio dado que cambian mucho y son \u00fatiles \u00fanicamente para construir el paquete.<\/li>\n<\/ol>\n<p>El archivo Makefile las declara de esta forma:<\/p>\n<pre>MANPAGES=$(subst txt,1,$(wildcard docs\/manpages\/*.txt))<br \/>...<br \/>build: build-manpages<br \/><br \/>build-manpages:\t$(MANPAGES)<br \/><br \/>%.1: %.txt<br \/>\ttxt2man $? &gt; $@<br \/><br \/>install-manpages: build-manpages<br \/>        install $(MANPAGES) $(DESTDIR)\/usr\/share\/man\/man1\/<\/pre>\n<p>Y s\u00f3lo tengo que preocuparme de mantenerlas actualizadas con los scripts a los que documentan. <\/p>\n","protected":false},"excerpt":{"rendered":"<p>&#8230; tambi\u00e9n son necesarias. A ver si aprendemos.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"1","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","webmentions_disabled_pings":false,"webmentions_disabled":false,"footnotes":""},"categories":[6],"tags":[85,86,87],"class_list":["post-51","post","type-post","status-publish","format-standard","hentry","category-debian","tag-documentacion","tag-marc-vertes","tag-txt2man"],"_links":{"self":[{"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/posts\/51","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/comments?post=51"}],"version-history":[{"count":0,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/posts\/51\/revisions"}],"wp:attachment":[{"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/media?parent=51"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/categories?post=51"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/tags?post=51"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}