Hacker News Reader

Comment by rwmj | Hacker News Reader

I use perldoc / POD to write man pages and that works well. It's simple to write and there are tools to convert it straight to man pages, text or HTML.

For example: https://raw.githubusercontent.com/libguestfs/libguestfs/mast... and the output as HTML: http://libguestfs.org/virt-p2v.1.html

(The output in 'man' looks really good too, but I don't have an easy way to demonstrate that.)

View on HN

I used POD for a while; but after using DocBook XML for manuals for a work project some years ago I switched to primarily using that, and generating HTML, roff, and others from it.

Instead of explicit italicization and boldface

    to the hard disks: Firstly, the qemu-nbd I<-r> (readonly) option is

I write semantic markup

    The <arg choice='plain'>--upstart-compatibility</arg> option causes <command>tcp-socket-listen</command> to set the <envar>UPSTART_FDS</envar> environment variable to 3, and the <envar>UPSTART_EVENTS</envar> environment variable to <literal>socket</literal>.

which I find preferable.

DocBook XML isn't bad, but don't you find the markup incredibly verbose?

No. As you can see from the aforegiven snippet, which is fairly representative although it was the result of my going looking for a sentence with a lot of different elements in it, it isn't.

This seems a good approach. I just thought maybe we can use React to render this kind of stuff?

As this comment proved unexpectedly popular, here is a 15 second video of how it looks when paging through the man page:

http://oirase.annexia.org/tmp/virt-p2v-man.ogv

Now that is a proper man page!

Reply on news.ycombinator.com