Title: Writing an article using mdoc format | |
Author: Solène | |
Date: 03 July 2018 | |
Tags: unix | |
Description: | |
.Dd July 03, 2018 | |
.Dt "Test using mandoc" | |
I never wrote a man page. I already had to read at the source of a | |
man page, but I was barely understand what happened there. As I like | |
having fun and discovering new things (people call me a Hipster since | |
last days days ;-) ). | |
I modified cl-yag (the website generator used for this website) to be | |
only produced by mdoc files. The output was not very cool as it has | |
too many html items (classes, attributes, tags etc...). The result | |
wasn't that bad but it looked like concatenated man pages. | |
I actually enjoyed playing with mdoc format (the man page format on | |
OpenBSD, I don't know if it's used somewhere else). While it's pretty | |
verbose, it allows to separate the formatting from the paragraphs. As | |
I'm playing with | |
.Ic ed | |
editor last days, it is easier to have an article written with small | |
pieces of lines rather than a big paragraph including the formatting. | |
Finally I succeded at writing a command line which produced an usable | |
html output to use it as a converter in cl-yag. Now, I'll be able to | |
write my articles in the mdoc format if I want :D (which is fun). The | |
convert command is really ugly but it actually works, as you can see | |
if you read this. | |
.Bd -literal -offset indent | |
cat data/%IN | mandoc -T markdown | sed -e '1,2d' -e '$d' | | |
multimarkdown -t html -o %OUT | |
.Ed | |
The trick here was to use markdown as an convert format between mdoc | |
to html. As markdown is very weak compared to html (in | |
possibilities), it will only use simple tags for formatting the html | |
output. The sed command is needed to delete the mandoc output with | |
the man page title at the top, and the operating system at the | |
bottom. | |
By having played with this, writing a man page is less obscure to me | |
and I have a new unusual format to use for writing my articles. Maybe | |
unusual for this use case, but still very powerful! |