Writing an article using mdoc format

Author: Solène

Date: 03 July 2018

Tags: unix

NIL.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!