Man Page Authoring and Documentation Alternatives
Manual pages, commonly known as man pages, serve as the standard form of software documentation in Unix-like operating systems. Creating these documents requires a specific understanding of formatting languages that allow text to be rendered consistently across various terminal environments.
Authoring Man Pages
There are two primary macro sets used to write manual pages: the traditional man macros and the modern mdoc macros. The older man macro set provides basic rich text functions, allowing authors to define title lines, section headers, and font styles such as bold, small, or italic, while managing paragraph indentation.
In contrast, the mdoc language is more semantic. Rather than focusing solely on visual layout, mdoc uses specialized macros for standard manual sections, including the program name, synopsis, function names, and author credits. This semantic structure allows tools like mandoc to implement advanced features such as semantic search. While mdoc still allows for direct styling control, the use of specialized macros is the intended standard. Consequently, both the mandoc and groff projects recommend mdoc for all new documentation.
ไม่มีภาพประกอบ
Rendering and Terminal Compatibility
Technically, man pages are viewed by troff (a typesetting system) as text laid out in 10-point Roman type. However, because most users view these pages in a terminal (TTY) rather than on printed paper, certain formatting choices are less relevant; for example, the "small font" macro is rarely used.
Styling support varies by tool. groff's grotty can emit bold and italic text via ECMA-48 (a standard for terminal control codes) when a supporting terminal is detected. The BSD mandoc tool, however, handles bold and underlined text (used as a substitute for italics) using a typewriter backspace-then-overstrike sequence, which requires the less pager to translate it into ECMA-48.
Conversion Tools and Localization
Because writing in raw macros can be cumbersome, several tools exist to convert other formats into man pages. help2man, a GNU tool, generates a manual page from a program's --help output. While this results in a manual that is only slightly more useful than the help output itself, it is a common practice for GNU programs, which primarily use texinfo for their main documentation.
Other popular tools like pandoc, ronn, and md2man allow authors to write in Markdown and convert the result to the man format. Because Markdown lacks the semantic depth of mdoc, these tools output the basic man format instead. Additionally, DocBook includes a built-in man(7) converter, though the author of mandoc has noted its poor quality and developed a separate mdoc(7) converter as an alternative.
While English is the primary language for man pages, localization is supported. Both the GNU man-db and mandoc man can search for translated manual pages stored in specific subdirectories.
Key Facts
- mdoc is the preferred format for new man pages due to its semantic nature.
- mandoc and groff are the primary projects supporting modern man page standards.
- Terminal rendering often relies on ECMA-48 for bold and italic text.
- Markdown can be converted to man pages via tools like pandoc, ronn, and md2man.
- help2man automates page creation using a program's own help output.
Documentation Alternatives
While man pages are the standard, other systems provide different ways to access software help. The GNU Project's info system is a notable alternative, functioning as an early and simple hypertext system.
For users seeking quick answers, TLDR pages (tldr) offer a community-driven alternative that provides simple examples for common use cases, acting more like a cheatsheet than a comprehensive manual.
In the realm of Graphical User Interfaces (GUI), particularly within the GNOME and KDE environments, documentation is often provided in HTML. These applications frequently include embedded HTML viewers, such as yelp, to allow users to read help files directly within the application.
| Format/Tool | Primary Characteristic | Best Use Case |
|---|---|---|
| man macros | Basic rich text | Legacy documentation |
| mdoc | Semantic structure | New, searchable man pages |
| GNU info | Hypertext system | Complex, linked manuals |
| TLDR pages | Example-based | Quick reference/Cheatsheets |
| HTML/Yelp | Web-based GUI | Desktop application help |
Frequently Asked Questions
What is the difference between man macros and mdoc?
Man macros provide basic formatting (bold, italics, indentation), whereas mdoc is semantic, using specific tags for program names, synopses, and authors to enable better tool integration and semantic searching.
Which format is recommended for new manual pages?
Both the mandoc and groff projects recommend using the mdoc format for all new documents.
Can I write man pages in Markdown?
Yes, tools such as pandoc, ronn, and md2man can convert Markdown files into the man format, although they cannot capture the full semantic detail of mdoc.
How do man pages handle bold and italic text in a terminal?
Groff's grotty uses ECMA-48 codes for supporting terminals. BSD mandoc uses a backspace-then-overstrike sequence that is typically translated into ECMA-48 by the less pager.
What are the alternatives to traditional man pages?
Alternatives include the GNU info hypertext system, TLDR pages for quick examples, and HTML-based help viewers like yelp for GUI applications.