new trends in mandoc





The interactive transcript could not be loaded.



Rating is available when the video has been rented.
This feature is not available right now. Please try again later.
Published on May 29, 2014

by Ingo Schwarze

enhancing the modern toolbox for the classic documentation formats

Since its first presentation at BSDCan 2011, the mandoc(1) documentation formatting system has gained a lot of traction in all four major BSD operating systems and beyond. This talk will provide an update regarding recent feature additions, in particular the mdoc(7) to man(7) converter to produce high quality manual formatting for portable software packages, and the new SQLite3-based mandocdb(8) utility, a drop-in replacement for the traditional makewhatis(8)/apropos(1) combo, providing markup-sensitive search capabilities and flexible search result output formats.

I will give an overview of the adoption status of mandoc(1) and mandocdb(8) in OpenBSD, DragonFly, NetBSD, and FreeBSD as well as a few other free operating systems, comment on mandoc versus groff usage in the OpenBSD ports tree including recommendations for handling manuals in packaging systems in general, and comment on possible future development directions.

During its first three years of being the only documentation formatter in the OpenBSD base system, the mandoc(1) utility has matured considerably. While we certainly continue tuning mandoc to bring its output even closer to groff(1) output, development focus has shifted from implementing basic features and fixing bugs to extending its scope beyond the mere formatting of manuals.

After a brief introduction explaining the advantages of mdoc(7) as the markup language for writing manuals and of mandoc(1) as the manual formatter, this talk will focus on two features recently added to mandoc:

The mandoc -Tman output mode for converting hand-written mdoc(7) documents into autogenerated man(7) code. The talk will explain how to use this to produce high quality documentation for portable software packages. The portable sudo(8) distribution will be used as an example.

The usage, implementation, optimization, and performance of the SQLite3-based mandocdb(8) utility, a drop-in replacement for the traditional makewhatis(8) program, in concert with the SQLite3-based apropos(1) replacement. These tools add markup-sensitive search capabilities and flexible output formats to the traditional apropos(1) functionality. To name some examples, they let you specifically search for include file names, function and argument types, function argument names, variable types and names, preprocessor constants, error constants, environment variables, command arguments and flags, file system paths, kernel configuration directives, author names, standards, operating system releases and cross references across all manuals installed on the local machine. They support complex search queries supporting "or" and "and" operators and parentheses, and they allow to show the contents of user-chosen macros in place of the usual (Nd) description line in the output.


When autoplay is enabled, a suggested video will automatically play next.

Up next

to add this to Watch Later

Add to

Loading playlists...