Grant Report: Markdown Support for GNU AutoGen

Grant Report: Markdown Support for GNU AutoGen

2025 ARIN Community Grant Program Recipient Report

Network Time Foundation (NTF) received an ARIN Community Grant of US$14,000 in 2025 to fund its work adding Markdown as a supported documentation markup format in GNU AutoGen. The NTP Project uses GNU AutoGen to generate consistent manual pages, Texinfo, and HTML documentation for the NTP Reference Implementation from a single set of source stanzas.

Before this project began, the NTP Project replaced its WordPress and HTML sites with Hugo to improve consistency, security, and performance while reducing CPU and memory usage. The new ntp.org website uses Markdown, but GNU AutoGen could not produce it. That left our documentation team manually converting the documentation for every NTP release before it could be published to our online archive. The goal of this project was to close that gap by adding Markdown output to GNU AutoGen, replacing a time-consuming, tedious, and error-prone manual process with an automated one.

Learn more about all the 2025 ARIN Community Grant Program Recipients.

Project Implementation

We set out to complete the following tasks, with all grant funds going toward worker hours:

  • Add Markdown to the list of known markup types in the GNU AutoGen .def file processor
  • Create an mdoc2md conversion script and, time permitting, man2md and texi2md scripts to convert existing man, mdoc, and texi directives into Markdown
  • Time permitting, create md2man, md2mdoc, and md2texi scripts to convert in the other direction
  • Time permitting, build an automated test suite to provide unit and regression testing for GNU AutoGen’s documentation markup processing

By our March 2026 progress update, we had updated the AutoGen codebase and documentation to reflect the new functionality and were listing all tags needed to convert documentation stanzas between Markdown, man, mdoc, and texi formats. From there, the plan was to complete each converter and use existing documentation files to test and validate the conversions to Markdown.

Because all relevant NTP Project documentation already uses mdoc markup, the proper solution is an mdoc2md converter script. However, a long list of unforeseeable situations prevented us from completing the implementation plan as designed. One unexpected lesson along the way: Bootstrapping GNU AutoGen is remarkably difficult, because it relies on the GNU Project’s gnulib mechanism to add new Makefile targets.

We did identify and deploy an acceptable interim solution. The mandoc program does an adequate job of translating mdoc to Markdown, which minimally satisfies our need to produce NTP documentation in Markdown for our Hugo-based website.

Watch the recording or read the transcript of the interim project update presented at the ARIN 57 Public Policy and Members Meeting.

Outcome and Impact

Our top priority was to ease the burden on the NTP Project’s documentation team. Until now, every NTP release required manual work across the entire documentation collection before it could be integrated into our public archive. Automating that step will greatly improve how quickly we can integrate new releases into the archive, and our documentation team will be able to devote the hours saved on manual conversion to improving the documentation itself and to other projects.

That matters well beyond our own team. Accurate network time underpins reservation systems, multiuser databases, timestamping, logging, and other services that depend on proper timekeeping across interrelated devices. Network administrators and security researchers throughout the ARIN region rely on the NTP Reference Implementation, and an evolving, easier-to-maintain documentation archive will make it easier for them to improve and secure their NTP deployments.

Once fully deployed, any documentation fix made in the source tree will ripple automatically through every generated format, including manual pages, HTML, Markdown, Texinfo, info, and PDF. We are integrating these enhancements upstream into the public release of GNU AutoGen so that any open source project using the framework can generate documentation in a wider range of formats, including Markdown for modern web-based documentation.

The work is also already shaping the future of NTP documentation. With ntp.org now driven by Hugo, generating NTP Project documentation directly into Markdown is the natural next step in our multiyear effort to refactor and overhaul that documentation. This new capability is already driving design and content discussions around that overhaul.

What’s Next?

We will continue building the native mdoc2md converter so AutoGen can produce Markdown directly, without relying on mandoc. That approach will give us automatically generated documentation that is more usable, and we aim to complete it by the end of 2026. The GNU AutoGen repository will also be updated soon with our work and documentation.

Network Time Foundation and the NTP Project are grateful to ARIN for its support, and we look forward to continuing our work to benefit the Internet community in the ARIN region and beyond.


About the ARIN Community Grant Program

ARIN provides financial grants in support of initiatives that improve the overall Internet industry and Internet user environment. Are you working on a project that advances ARIN’s mission and broadly benefits the Internet community within the ARIN region through informational outreach, research, Internet technical improvements, or registry processes and technology improvements? Visit the ARIN Community Grant Program page for more information and to find out how your organization can apply in 2027. For application tips and support, read this post on our blog.

Post written by:

Harlan Stenn
President, Network Time Foundation, Inc.

Harlan Stenn began programming computers in 1971. He holds a bachelors degree in Business Administration (Accounting) from The Colorado College in Colorado Springs, and an MSE in Computer Science from Washington University in St. Louis. He has worked directly with NTP since 1992 and has been managing NTF’s progress in the first implementation of the Network Time Security draft IETF specification, driving NTF’s General Timestamp API Project, and incorporating the Ntimed Project into NTF.

Any views, positions, statements, or opinions of a guest blog post are those of the author alone and do not represent those of ARIN. ARIN does not guarantee the accuracy, completeness, or validity of any claims or statements, nor shall ARIN be liable for any representations, omissions, or errors contained in a guest blog post.

Recent blogs categorized under: Grant Program


Sign up to receive the latest news about ARIN and the most pressing issues facing the Internet community.

SIGN ME UP →

Grant Program •  Security •  Public Policy •  Tips •  Training •  Elections •  ARIN Bits •  Fellowship Program •  Caribbean •  IPv6 •  Data Accuracy •  IPv4 •  Guest Post •  Customer Feedback •  Outreach •  Internet Governance •  RPKI •  Updates •  IRR •  Business Case for IPv6

 

Connect with us on Instagram!