1. 2

    Oh, please let this project be successful. The worst thing about writing a man page is the troff syntax that mandoc uses. On *BSD, there’s now a custom renderer for only the mandoc syntax, rather than a full troff implementation (such as groff), which is a lot smaller and faster. That helps with the rendering path, but not the authoring bit.

    To give a concrete example, this is a man page that I’ve written, without any rendering. It is not human readable, for any reasonable definition of ‘human’. I would love to have something that would either render Markdown pages natively in man, or would translate Markdown to mdoc so humans never have to write mdoc again.

    1. 1

      Amen. When I was a younger man, I thought troff was cool because I could make cool looking documentation while retaining some interesting (to me) properties:

      1. still using a programmer like work flow
      2. my documentation source files were a ton smaller than any of the binary formats offered by MS Word et al (important because disk space was limited and expensive) and
      3. it was diff-able.

      Much time passed…

      1. retains some residual appeal – but nobody cares
      2. disk space? nobody care
      3. a useful property but if you have tried merging conflicting man page edits in *roff you are painfully aware of the additional friction created by *roff itself

      markdown, IMHO, is a legit contender to replace *roff in the context of man pages (which I still refer to all the time)

      So yes. Chapeau. I hope to see more of this kind of work.

      1. 1

        See ddevault’s scdoc.