Man-страницы традиционно составлялись на языке набора текста под названием roff с использованием пакета макросов под названием an (поэтому командная строка была roff -man, sic), но теперь мало кто пишет сырой roff.
Существуют различные форматы документации SGML и XML, которые позволяют генерировать man исходных кодов страниц, хотя в наши дни Markdown, вероятно, становится де-факто стандартом для новой документации. Для меня самым популярным поиском в Google является https://github.com/remarkjs/remark-man. хотя я бы определенно посоветовал вам взглянуть на pandoc.
# NAME
Markdown - popular text markup language
# SYNOPSIS
man markdown
# DESCRIPTION
This is a popular lightweight syntax
to generate styled text from an
editor-friendly text source.
It is used on [Stack Overflow][1],
[Github][2], and increasingly on
blogging and authoring platforms.
[1]: https://stackoverflow.com/
[2]: https://github.com/
Я также упомяну формат POD, который имеет долгую историю в сообществе Perl и многие имеет общие черты с популярными, более поздними облегченными форматами. Если у вас нет других причин, чтобы вам это понравилось, я бы не выбрал его для новой документации, но раньше он был умеренно популярен даже далеко за пределами мира Perl, когда это был один из единственных вариантов с простым удобочитаемым исходным форматом, очевидным семантика, а также универсальная и хорошо поддерживаемая цепочка инструментов и экосистема поддержки. Некоторые, вероятно, сказали бы, что это все еще так.
=head1 NAME
Pod::Example - Example POD document
=head1 SYNOPSIS
pod2man thisdoc.pod >thisdoc.1
=head1 DESCRIPTION
Lightweight syntax for subheads,
hyperlinks, indented lists,
and not much else.
Natively supported in Perl source files
to facilitate a crude form of
literate programming.
person
tripleee
schedule
03.06.2018
