The author argues that man pages themselves are a valuable and well-structured source of information, contrary to popular complaints. The problem, they contend, lies with the default man reader, which uses less, hindering navigation and readability. They suggest alternatives like mandoc with a pager like less -R or specialized man page viewers for a better experience. Ultimately, the author champions the efficient and comprehensive nature of man pages when presented effectively, highlighting their consistent organization and advocating for improved tooling to access them.
The blog post, titled "Man pages are great, man readers are the problem," argues that the often-maligned Unix manual pages (man pages) are not inherently flawed in their design or content, but rather suffer from inadequate tools for accessing and navigating them. The author posits that the default man command and its associated pager, usually less, present a significant barrier to entry for new users and hinder efficient information retrieval even for seasoned users. This barrier manifests in several ways. Firstly, the sheer volume of information presented can be overwhelming, especially for those unfamiliar with the specific conventions and structure of man pages. Secondly, the lack of sophisticated search functionality within the default pager makes pinpointing specific information a tedious and often frustrating process. Thirdly, the monochromatic, text-based presentation, while functional, lacks the visual appeal and interactive elements that modern users have come to expect from digital documentation.
The author contends that these deficiencies are not inherent limitations of the man page format itself. They are, instead, limitations of the tools used to interact with them. The core value proposition of man pages – concise, comprehensive, and readily available documentation directly within the terminal – remains strong. However, the experience is marred by the suboptimal user interface provided by traditional man readers.
The author proceeds to illustrate this point by comparing the experience of using the standard man command with that of using alternative man page readers, specifically highlighting the advantages of tldr and manpager. tldr (Too Long; Didn't Read) provides simplified, practical examples of common command usage, offering a quick reference for those who don't need the full depth of the man page. manpager, on the other hand, enhances the presentation and navigation of full man pages by utilizing features like syntax highlighting, improved search functionality, and automatic section linking. These alternative tools demonstrate the potential for a significantly improved user experience without sacrificing the inherent strengths of the man page format.
The author concludes by advocating for the adoption of these more modern and user-friendly man page readers as the default, arguing that this would dramatically improve the accessibility and utility of this valuable resource for both novice and experienced Unix users alike. The ultimate message is not to discard man pages, but rather to modernize the tools we use to interact with them, thereby unlocking their full potential.
Summary of Comments ( 63 )
https://news.ycombinator.com/item?id=43631672
HN commenters largely agree with the author's premise that man pages are a valuable resource, but the tools for accessing them are often clunky. Several commenters point to the difficulty of navigating long man pages, especially on mobile devices or when searching for specific flags or options. Suggestions for improvement include better search functionality within man pages, more concise summaries at the beginning, and alternative formatting like collapsible sections.
tldrandcheatare frequently mentioned as useful alternatives for quick reference. Some disagree, arguing that man pages' inherent structure, while sometimes verbose, makes them comprehensive and adaptable to different output formats. Others suggest the problem lies with discoverability, and tools likeaproposshould be highlighted more. A few commenters even advocate for generating man pages automatically from source code docstrings.The Hacker News post titled "Man pages are great, man readers are the problem" (linking to an article of the same name) generated a substantial discussion with diverse opinions. Several commenters agreed with the article's premise, citing the density and comprehensive nature of man pages as strengths, and pointing to the awkwardness of
man's default pager,less, as a major usability hurdle. They suggest alternative pagers likebator incorporating search functionalities within the pager as improvements. One commenter specifically praised the use oftldrpages for quicker access to common usage examples, while acknowledging man pages as the ultimate source of truth. Another commenter noted how valuable the full technical specifications and corner cases documented in man pages are, even if they are not needed for everyday usage. The verbosity and occasional outdatedness of man pages were mentioned as minor drawbacks, though not significant enough to detract from their overall value.Some commenters argued against the article's premise. They expressed frustration with the structure of man pages, finding the information organization illogical and difficult to navigate, even with improved pagers. They criticized the lack of consistency across different man pages, making it challenging to predict where specific information might be located. These commenters often suggested alternative documentation formats like web pages or dedicated documentation sites, which they perceived as being more user-friendly. One commenter pointed out that the author's preferred approach using
man -Tpdfand a PDF viewer was a workaround rather than a solution to the underlying usability issues withman.A few commenters took a more nuanced approach, acknowledging the strengths of man pages while also recognizing their shortcomings. They proposed improvements such as better indexing and search capabilities, more consistent formatting, and perhaps even incorporating some of the strengths of alternative documentation styles into man pages themselves. One commenter highlighted the importance of context and how man pages, being primarily designed for command-line use, fit well within that specific context. They also pointed to the benefit of man pages being readily available offline, a crucial advantage in certain situations. There was also some discussion about the learning curve associated with using man pages effectively, with some users appreciating the challenge while others found it unnecessarily steep.
Finally, there were a few tangential comments, including one about the history of Unix documentation and the cultural significance of man pages. Another commenter questioned the value of man pages in the modern software development landscape, arguing that many modern tools and libraries often lack adequate man page documentation. Overall, the comment section reflects a wide range of opinions on the utility and usability of man pages, with a general agreement that improvements are needed but disagreement on the best approach to achieve them.