💾 Archived View for perso.pw › blog › articles › writing-article-with-mandoc.gmi captured on 2023-05-24 at 18:26:51. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
.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!