News for hackers. Stuff that matters.
Re:Practical Unix Manuals: mdoc by rwmj on Saturday November 25, 2017 @11:12AM (#15776518)
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.)

Re:Practical Unix Manuals: mdoc by JdeBP on Saturday November 25, 2017 @10:44PM (#15779321)
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.
Re:Practical Unix Manuals: mdoc by ianchen on Sunday November 26, 2017 @02:57AM (#15779915)
This seems a good approach. I just thought maybe we can use React to render this kind of stuff?
Re:Practical Unix Manuals: mdoc by rwmj on Sunday November 26, 2017 @02:17AM (#15779808)
DocBook XML isn't bad, but don't you find the markup incredibly verbose?
Re:Practical Unix Manuals: mdoc by JdeBP on Sunday November 26, 2017 @03:54AM (#15780066)
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.
Re:Practical Unix Manuals: mdoc by rwmj on Saturday November 25, 2017 @02:59PM (#15777670)
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

Re:Practical Unix Manuals: mdoc by unixhero on Sunday November 26, 2017 @05:14PM (#15783358)
Now that is a proper man page!