1. 7
  1. 3

    What’s the real benifit over this as compared to mandoc -Thtml? From what I see, the mai difference would be that you’d get to write HTMl, instead of mdoc’s roff, but is this an advantage?

    1. 2

      So you can add it to a “mandoc -Thtml” output so that a man page looks like a man page? hehe

      1. 2

        I was not aware you could do this. I’ll have to remember that.

        1. 1

          Monocypher is going down this route, actually.

        2. 2

          The main benefit that I can see is actually having access to raw HTML. Sometimes, you want to put a screenshot on your website so people can see what your tool does. mandoc does not support images in any way, though it’s on the TODO list for two years now.

          Most people know some degree of HTML, but learning mandoc properly does take a few days of looking at well-formatted man pages and going over mdoc(7) as well as Practical Manuals: mdoc. mandoc -Thtml has the advantage that you already have written a “proper” man page that you can ship as such.

          1. 1

            with mandoc you have to learn man language, looks like a big disavantage

            1. 2

              But assuming that if you’re already going to have a man page styles homepage, you should probably also have a manpage, and you don’t have a html option for that.

              And even if you disregard that, mdoc is really not that difficult to get into, and is (unsurprisingly) well documented.

            2. 1

              HTML is a less esoteric format than manual pages, and the HTML output of mandoc is less useful for styling than it could be, probably due to limitations of the original format.

              If you try to say ‘I want the second entry in SYNOPSIS to be blue’, it seems hard/impossible to do, as the entries in SYNOPSIS are not distinguishable as such, and aren’t even distinguishable from CSS as separate entries.