Qual é a diferença entre a macro mdoc definida para troff e a macro homem simples configurada para criar novas páginas de manual?

Question

Estou tentando criar páginas de manual para um projeto paralelo e nunca usei o troff antes e estou tentando descobrir qual é exatamente a diferença entre o conjunto de macro man e os conjuntos de macros mdoc e que é mais portátil entre POSIX OS'es e as várias implementações de troff.

O que eu notei é que o mdoc e o plain man compartilham algumas macros e que o BSD (pelo menos o FreeBSD) usa o formato manual do mdoc enquanto o GNU usa o formato plain man.

Então, minhas perguntas são basicamente:

O mdoc é um superconjunto das macros man? e isso faz com que se use o legado do homem comum? A groff manpage para mdoc afirma que as macros do homem comum são as predecessoras do mdoc, mas não diz se o mdoc substitui o homem.

A diferença é algo do tipo BSD vs SYSV e / ou GNU?

Qual é mais portátil em sistemas POSIX e várias implementações de troff além do groff (como o troff de herança)?

    

Answer 1

What exactly is the difference between the man macro set and the mdoc macro sets?

man é mínimo e simplista, tendo apenas comandos básicos para definir cabeçalhos de seção, parágrafos e subtítulos. O pacote inclui alguns comandos básicos de formatação como .B , .BI e pouco mais.

mdoc , por outro lado, é um DSL com todos os recursos, com comandos de marcação dedicados para elementos de página comuns como opções, listas de opções e parâmetros, tipos de função e valores de retorno, sinalizadores, sinopses de comando e praticamente tudo o que você esperaria de uma linguagem de marcação de página do manual. Veja mdoc(7) para uma referência completa.

Is mdoc a superset of the man macros?

Não. mdoc e man são pacotes completamente não relacionados, compartilhando apenas um ancestral comum e o mesmo objetivo de marcar as páginas de manual do computador.

What I have noticed is that both mdoc and plain man share some macros

Eles não compartilham nada. É possível que o que você viu sejam comandos nativos do Roff, que é a linguagem de composição subjacente na qual as macros mdoc e man estão escritas. Elas tendem a ser muito usadas em documentos que usam man , mas menos Então, naqueles que usam mdoc .

Você pode facilmente distinguir comandos Roff nativos de macros pela maneira como os pacotes Roff padrão capitalizam seus nomes de macro. Para man , o nome de cada macro é maiúscula, como .PP , .TH , .SH , etc. Para mdoc , apenas a primeira letra é maiúscula: .Pp , .Dt , .Sh , etc.

The Groff manpage for mdoc states that the plain man macro's are the predecessor to mdoc but does not say if mdoc supersedes man.

groff_mdoc(7)
A complete reference for writing UNIX manual pages with the -mdoc macro package; a content-based and domain-based formatting package for GNU troff(1). Its predecessor, the -man(7) package, addressed page layout leaving the manipulation of fonts and other typesetting details to the individual author.

Eu não acho que "antecessor" aqui foi concebido para significar algo mais do que "algo semelhante que estava sendo usado antes". : -)

Which is more portable across POSIX systems and various implementations of troff other than Groff (like Heirloom Troff)?

As macros mdoc já são bem suportadas há um bom tempo, tendo sido lançadas pela primeira vez no 4.4BSD e enviadas com cada instalação do Groff por padrão. Ambos os pacotes podem ser considerados igualmente portáteis, a menos que você esteja preparando documentos para terminais antigos de meados dos anos 70. :)

Is the difference some BSD vs SYSV and/or GNU thing?

Você está no caminho certo. Os modernos sistemas BSD usam um programa chamado mandoc para formatar e exibir manpages, o que é uma reimplementação limpa de mdoc usando C. compilado nativamente. Ele suporta apenas um subconjunto da linguagem Roff - suficiente para que as páginas de manual legadas sejam exibidas corretamente. / p>

Mandoc não é um verdadeiro programa de composição como Groff e Heirloom são. Seu foco é especificamente em manuais de computador: e é garantido que apenas documentos criados com mdoc sejam renderizados de forma consistente e correta em plataformas derivadas do BSD. Críticas mais detalhadas sobre man podem ser encontradas em man(7) .

and does that make using plain man legacy?

Mais ou menos. A menos que você seja um autor experiente de manpages com uma sólida compreensão da gramática Roff e da mecânica do pipeline, você realmente não deveria estar usando nada além de mdoc para criar suas páginas de manual. Veteranos troff usuários podem achar mdoc desnecessariamente verboso ou restritivo, achando man mais leve e menos intrusivo. No entanto, esses autores são experientes o suficiente para saber muito bem o que estão fazendo - , a menos que você seja um veterano grisalho, basta usar mdoc .

Mais informações

Se você estiver interessado em saber mais sobre o histórico do Roff, e esta resposta não foi FMTEYEWTK já, aqui ' re alguns links para material de aprendizagem autoritativo:

• História das Manipulações UNIX : Linha do tempo abrangente de mais de 50 anos de evolução
• CSTR # 54 : versão em PDF do manual do usuário do Nroff / Troff original - amplamente considerada a Bíblia do Troff
• "Desprovando o Groff para exibição manual do BSD" : Um trabalho do autor de mandoc , que explica o raciocínio para a obsolescência de man .