Existe uma especificação para o formato usado por man pages?

Question

Eu gostaria de analisar páginas man em um formato mais estruturado, mas não consigo encontrar uma especificação adequada para o formato de dados em uso por páginas man. Eu deveria estar procurando por troff ou nroff ou groff ou algo mais? groff (7) diz que

The groff system has all features of the classical roff, but adds many extensions.

Essas extensões são os vários pré-processadores, como o tbl ou outra coisa?

Até agora, encontrei os seguintes recursos:

• troff.org - Isto tem notas históricas e alguns tutoriais, e alguns links mortos.

• roff (7) ( OpenBSD , Linux ) - Realmente não tem uma especificação, apenas uma breve visão geral e um monte de histórico.

• man-pages (7) ( Linux ) - Isso fornece diretrizes sobre seções em man pages (o que é útil), mas não fala sobre o formato dos dados.

• Uma TROFF independente de tipógrafos e Troff - Manual do Usuário - estes são bastante antigos, então eu não posso realmente julgar quais são as diferenças entre o troff em esses papéis e na prática.

Existe alguma especificação clara em algum lugar para o formato exato em uso por páginas man?

    

Answer 1

Não existe um formulário de fonte única.

Algumas pessoas escrevem páginas de manual no roff. Quase ninguém usa roff cru; mas as pessoas escrevem páginas de manual usando vários conjuntos de macros roff, como an ou mdoc . Esses conjuntos de macros diferem extensivamente um do outro. Mas muitas pessoas hoje em dia não escrevem páginas de manual no roff .

As pessoas também podem criar páginas de manual em Docbook XML, POD perl, T _E , T _e χinfo, ASCIIDOC, HTML simples ou outros sistemas.

Alguns destes, mais notavelmente Docbook XML, são bastante estruturados em primeiro lugar e a conversão para roff é com perdas. É melhor você ignorar o roff se ele for a fonte e usar os formulários de origem reais diretamente, o que provavelmente já terá o formulário estruturado que você está procurando.

De fato, não há intermediário quando visualizamos alguns desses formulários. (Todos os acima mencionados podem ser convertidos diretamente para formatos como HTML sem passar por um estágio intermediário. Páginas de manual criadas no Docbook XML, mais uma vez notavelmente, podem ser vistas diretamente como o XML usando vários navegadores WWW, sem um intermediário HTML, se Docbook CSS ou similar é empregado.)

Muitos desses formulários de fonte são eles padronizados, mas não há uma única forma de fonte universal para páginas de manual.

Exemplos

• A origem XML do Docbook da página de manual do comando halt do systemd
• A fonte T _e χinfo da página de manual para o GNU gdb
• A fonte POD da página de manual do POD-Readme
• A origem ASCIIDOC da página de manual do comando asciidoc

Answer 2

Sim. Pense como HTML ... mas pré-HTML. Basicamente, um monte de macros de composição para groff ...

Primeiro, há algumas seções comumente aceitas - é claro que você pode adicionar mais ...

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
BUGS
AUTHOR
SEE ALSO

E para cada um (e em qualquer outro lugar) você usa a sintaxe da macro groff typesetting.

Por exemplo, um TITLE HEADER pode ser feito assim -

.TH [name of program] [section number] [center footer] [left footer] [center header]

Ou um SECTION HEADER -

.SH [section name]

E, claro, você pode negrito, itálico, sublinhado, etc. -

.B = bold
.BI = bold alternating italic
.BR = bold alternating Roman
.I = italic
.IB = italic alternating bold
.IR = italic alternating Roman
.RB = Roman alternating bold
.RI = Roman alternating italic 

E você pode até fazer comentários no seu arquivo de texto -

." This is a comment

E, em seguida, coisas como o parágrafo (como o conjunto de tags <p></p> html) com .PP

Não se esqueça de nomear o arquivo adequadamente e, em seguida, gzip quando terminar.

Esta informação (e mais) é do link