向 Pandoc 贡献一个 mdoc 阅读器 —— Duckrabbit Solutions

Summary: The author loves Pandoc and Unix manual pages, especially those in OpenBSD's mdoc macro language. They contributed mdoc input support to Pandoc. The mdoc reader was shipped with Pandoc 3.6 on December 7, 2024. The author discusses the nature of the work, including adding mdoc support beyond personal interest. They mention related tools like Pandoc, mdoc, and mandoc. The author faced challenges in implementing the mdoc reader, such as dealing with different mdoc implementations and parser combinators. They also discuss testing and using OpenBSD's man pages for testing. In the end, the author reflects on the motivation and persistence required to complete the project and encourages support on GitHub Sponsors.
Key Information:
- Pandoc is a software for converting markup languages and document formats.
- mdoc is a markup language for manual pages with specific semantics.
- mandoc is a program for formatting mdoc manual pages.
- The author contributed mdoc support to Pandoc and faced challenges in parsing and implementing it.
- Testing was done using OpenBSD's man pages and comparing the result with the intended Pandoc AST.
- Motivation and persistence were key factors in completing the project.
Important Details:
- The author started with a blank page and worked on the mdoc reader until it was completed.
- They decided to use mandoc as the exclusive reference implementation due to practical reasons.
- The author faced issues with mandoc's documentation and made judgment calls in some cases.
- The built-in readers of Pandoc use Parsec for parsing.
- Lexing was done before parsing mdoc to handle roff escape sequences.
- The author's code has some areas that could be improved in terms of organization and correctness.