BSDCan2014 - 20140606
BSDCan 2014
The Technical BSD Conference
| Speakers | |
|---|---|
|
Ingo Schwarze |
| Schedule | |
|---|---|
| Day | Talks - Day 2 - Sat May 17 - 2014-05-17 |
| Room | Montpetit 201 |
| Start time | 10:00 |
| Duration | 01:00 |
| Info | |
| ID | 459 |
| Event type | Lecture |
| Track | Hacking |
| Language used for presentation | English |
| Feedback | |
|---|---|
|
Did you attend this event? Give Feedback |
new trends in mandoc
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 implementating 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.