Como criar uma manpage?

Question

Estou empacotando um programa para o Ubuntu, e estou recebendo um aviso lintiano dizendo que meu binário precisa de uma página manpage.

Como é possível criar uma página de manual para um programa?

    

Answer 1

Com a ajuda de Gmanedit você é capaz de criar manpages com uma GUI gráfica.

  

O Gtk + Manpages Editor é um editor para páginas man executadas no X com o GTK +.

     

Gmanedit é uma aplicação que permite editar páginas de manual (man) em sistemas Linux / Unix.

     

É como os editores de HTML mais comuns, mas é mais fácil. Você precisa saber o formato das páginas de manual.

De acordo com os manpages do Debian FHS , os manpages do programa do usuário são armazenados em usr/share/man/man1 ou usr/local/share/man/man1 .

Depois de alterar as páginas de manual, convém atualizar o banco de dados de manpages executando mandb em um terminal.

Os detalhes sobre a sintaxe do manpage estão resumidos em na manpage for man .

    

Answer 2

Você pode escrever manpages em docbook / refentry, um formato de documentação XML,

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id='vfplot1'>
<refentryinfo><date>1 July 2008</date></refentryinfo>
<refmeta>
<refentrytitle>VFPLOT</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='date'>1 July 2008</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>vfplot</refname>
<refpurpose>plot vector fields with curved arrows.</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>
<cmdsynopsis>
  <command>vfplot</command>    
  <arg choice='opt'>-a <replaceable>aspect</replaceable></arg>
  <arg choice='opt'>-d <replaceable>file</replaceable></arg>
  <arg choice='opt'>-D <replaceable>pen</replaceable></arg>
    :

e depois converter os resultados para o formato man usando

xsltproc /path/to/docbook.xsl vfplot.xml

para html com

docbook2html docbook2html

e assim por diante. Esta não é a maneira mais fácil de escrever uma manpage, mas se você tiver escrito XML antes, então você já conhece a sintaxe, é apenas uma questão de aprendendo as tags para usar.

    

Answer 3

Dê um giro Eu acabei de fazer o upload dele Eu escrevo vários aplicativos e tenho tido problemas com um editor decente de manpages

link

Este é um aplicativo gtk2 com uma guia separada para cada seção importando manpages visualização e exportação são todos suportados, sem comandos de formatação esotéricos, isso ainda está em desenvolvimento, mas é certamente estável o suficiente para usar.

    

Answer 4

Você pode fazer isso com autotools. O GNU publicou um exemplo em que um projeto C instala uma manpage com ferramentas automáticas.