11 ms·

Practical Unix Manuals: mdoc

161 points by beefhash 9y ago

emj 9y ago
I love man pages they are often easy to read, but roff is not that easy to author. So it nice to see good documentation being posted. .Sh SYNOPSIS .Nm .Op Fl C .Op Fl o Ar output .Op Ar prefix becomes this: SYNOPSIS hello [-C] [-o output] [prefix] Semantic formating is nice, but atm I'm not sure there is much value to write the above vs using markdown and just convert it to roff.
- beefhash 9y ago
  Semantic markup has a use, at least on OpenBSD. You can use the semantic markup for searching manual pages, like this[1]: > Search for manuals in the library section mentioning both the “optind” and the “optarg” variables: > $ apropos -s 3 Va=optind -a Va=optarg [1] https://man.openbsd.org/whatis.1 https://man.openbsd.org/whatis.1
  - humanrebar 9y ago
    When does someone need to search for that sort of thing?
    - beefhash 9y ago
      A more realistic example might be that you're changing $LANG and now something broke. You can thus search for everything that uses LANG[1] and see what's most likely to have broken in what way. [1] https://man.openbsd.org/?query=Ev%3DLANG&apropos=1&sec=0&arch=default&manpath=OpenBSD-current https://man.openbsd.org/?query=Ev%3DLANG&apropos=1&sec=0&arc...
      - jwilk 9y ago
        There are some many things that are affected by locale environment variables (most of the time without documenting it explicitly), that this particular query is mostly useless.
  - nerdponx 9y ago
    I wish I could use semantic markup to jump to a definition, either of an option or a subcommand.
    - yepguy 9y ago
      You can actually. If you use mandoc instead of mandb, it automatically generates and passes tag files to less. Then you can just type ":t e" to jump to the docs for the -e option, for example.
      - nerdponx 9y ago
        Interesting, so theoretically that is something that every distro could and should be doing?
- nerdponx 9y ago
  I'm not sure Markdown->Roff makes sense. I know Pandoc can do it, but how do you convey semantic information with Markdown? I'd sooner write YAML.
  - DC-3 9y ago
    It might not be trendy like Markdown or YAML (both of which I like, and have their uses), but to markup text with higher-level semantics (i.e. not relating to formatting) the best option is XML.
    - nerdponx 9y ago
      Sure, but do you really want to hand write XML? It's nice for computers but makes for really ugly source when humans are involved, and humans are still very heavily involved when it comes to writing documentation.
  - emj 9y ago
    It works, not as good as a good template for LibreOffice though, my point was that the sematics is lost with markdown and you only get formating.
- goialoq 9y ago
  Most of the problem with that is the cryptic abbreviations. A symbol lexical filter would let you have this: .SectionHeader .Name .Optional Flag C .Optional Flag o Argument output .Optional Argument prefix or with some punctuation: .SectionHeader .Name .Optional Flag: C .Optional Flag: o Argument: output .Optional Argument: prefix which is quite readable.
- clort 9y ago
  > I love man pages they are often easy to read, but roff is not that easy to author To be fair, writing the programs or functions that the manual page is purporting to document isn't easy either. I have written manpages (and plenty of code) and in my experience, the hardest part is not the markup but getting the actual content right.
  - emj 9y ago
    There are badly written documentation out there, and they will not be better just because they are formated as a man page instead of Microsoft Word, but the worst kind are the ones which are never written and that syntax is quite a blocker. Your comment highlights my bias for man pages, I forgive a lot more when it's read in prefered format rather than .docs.
tkfu 9y ago
roff is quite horrible to read and write. There's a much better solution than banging your head against an archaic and unforgiving file format: AsciiDoctor's manpage backend [1]. You write in asciidoc, with some required structure that's quite easy to follow, and it spits out a proper roff document for you. Asciidoctor's own manpage [2] is, of course, generated in this way, and it's a pretty good example of the form. [1] http://asciidoctor.org/docs/user-manual/#man-pages http://asciidoctor.org/docs/user-manual/#man-pages [2] https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/man/asciidoctor.adoc https://raw.githubusercontent.com/asciidoctor/asciidoctor/ma...
- gnuvince 9y ago
  The main issue with this is that AsciiDoc cannot express semantics. When writing manpages, you can specify that something is a flag or a function parameter, etc.
  - tkfu 9y ago
    I'd argue that (1) manpages are for humans to read, and (2) there is effectively only one presentation style for the conveying the semantic contents. So as long as the author of the manpage follows the standard conventions for manpage presentation style, they are in fact expressing the semantics. And it's a lot easier to learn the conventions (flags in bold, arguments in italics, etc.) and write them in lightweight markup than it is to learn roff.
    - opk 9y ago
      Semantic markup has more uses than just consistent presentation. For example, most of the BSD's use mandoc rather than groff for rendering which allows you to do more detailed searches with apropos. Note that the linked article refers to the mdoc macros. These aren't especially new and are very well supported but the man macros are still more common. If you dig into the details, the mdoc macros have many advantages.
      - deleted 9y ago
        [deleted]
rwmj 9y ago
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/master/p2v/virt-p2v.pod https://raw.githubusercontent.com/libguestfs/libguestfs/mast... and the output as HTML: http://libguestfs.org/virt-p2v.1.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.)
- rwmj 9y ago
  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 http://oirase.annexia.org/tmp/virt-p2v-man.ogv
  - unixhero 9y ago
    Now that is a proper man page!
- JdeBP 9y ago
  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.
  - rwmj 9y ago
    DocBook XML isn't bad, but don't you find the markup incredibly verbose?
    - JdeBP 9y ago
cat199 9y ago
quick plug for someone to do the legwork get heirloom troff in some real (read BSD) unix so that the whole roff toolchain is reintegrated after USL, that would be great.
- jwilk 9y ago
  What's USL?
  - mwest 9y ago
    Unix System Laboratories - https://en.wikipedia.org/wiki/Unix_System_Laboratories https://en.wikipedia.org/wiki/Unix_System_Laboratories See also: USL vs. BSDi: https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc._v._Berkeley_Software_Design,_Inc https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc.....
    - jwilk 9y ago
      HN doesn't consider trailing dot part of the URL, so you need to URL-escape the dot (%2e) to make it work. (But I set up a redirect, so now the dotless URL works, too.)
- luckydude 9y ago
  As a long time roff user, I really prefer groff. It's better. It does colors, the pic implementation is programmable, it's just better. So here is a vote against heirloom and for groff. And I get it, the BSD crowd hates GNU and I have my own issues with the GNU folks, but come on, use better when it is better.

161 points by beefhash 9y ago

emj 9y ago

I love man pages they are often easy to read, but roff is not that easy to author. So it nice to see good documentation being posted. .Sh SYNOPSIS .Nm .Op Fl C .Op Fl o Ar output .Op Ar prefix becomes this: SYNOPSIS hello [-C] [-o output] [prefix] Semantic formating is nice, but atm I'm not sure there is much value to write the above vs using markdown and just convert it to roff.

beefhash 9y ago
Semantic markup has a use, at least on OpenBSD. You can use the semantic markup for searching manual pages, like this[1]: > Search for manuals in the library section mentioning both the “optind” and the “optarg” variables: > $ apropos -s 3 Va=optind -a Va=optarg [1] https://man.openbsd.org/whatis.1 https://man.openbsd.org/whatis.1
- humanrebar 9y ago
  When does someone need to search for that sort of thing?
  - beefhash 9y ago
    A more realistic example might be that you're changing $LANG and now something broke. You can thus search for everything that uses LANG[1] and see what's most likely to have broken in what way. [1] https://man.openbsd.org/?query=Ev%3DLANG&apropos=1&sec=0&arch=default&manpath=OpenBSD-current https://man.openbsd.org/?query=Ev%3DLANG&apropos=1&sec=0&arc...
    - jwilk 9y ago
      There are some many things that are affected by locale environment variables (most of the time without documenting it explicitly), that this particular query is mostly useless.
- nerdponx 9y ago
  I wish I could use semantic markup to jump to a definition, either of an option or a subcommand.
  - yepguy 9y ago
    You can actually. If you use mandoc instead of mandb, it automatically generates and passes tag files to less. Then you can just type ":t e" to jump to the docs for the -e option, for example.
    - nerdponx 9y ago
      Interesting, so theoretically that is something that every distro could and should be doing?
nerdponx 9y ago
I'm not sure Markdown->Roff makes sense. I know Pandoc can do it, but how do you convey semantic information with Markdown? I'd sooner write YAML.
- DC-3 9y ago
  It might not be trendy like Markdown or YAML (both of which I like, and have their uses), but to markup text with higher-level semantics (i.e. not relating to formatting) the best option is XML.
  - nerdponx 9y ago
    Sure, but do you really want to hand write XML? It's nice for computers but makes for really ugly source when humans are involved, and humans are still very heavily involved when it comes to writing documentation.
- emj 9y ago
  It works, not as good as a good template for LibreOffice though, my point was that the sematics is lost with markdown and you only get formating.
goialoq 9y ago
Most of the problem with that is the cryptic abbreviations. A symbol lexical filter would let you have this: .SectionHeader .Name .Optional Flag C .Optional Flag o Argument output .Optional Argument prefix or with some punctuation: .SectionHeader .Name .Optional Flag: C .Optional Flag: o Argument: output .Optional Argument: prefix which is quite readable.
clort 9y ago
> I love man pages they are often easy to read, but roff is not that easy to author To be fair, writing the programs or functions that the manual page is purporting to document isn't easy either. I have written manpages (and plenty of code) and in my experience, the hardest part is not the markup but getting the actual content right.
- emj 9y ago
  There are badly written documentation out there, and they will not be better just because they are formated as a man page instead of Microsoft Word, but the worst kind are the ones which are never written and that syntax is quite a blocker. Your comment highlights my bias for man pages, I forgive a lot more when it's read in prefered format rather than .docs.

tkfu 9y ago

roff is quite horrible to read and write. There's a much better solution than banging your head against an archaic and unforgiving file format: AsciiDoctor's manpage backend [1]. You write in asciidoc, with some required structure that's quite easy to follow, and it spits out a proper roff document for you. Asciidoctor's own manpage [2] is, of course, generated in this way, and it's a pretty good example of the form. [1] http://asciidoctor.org/docs/user-manual/#man-pages http://asciidoctor.org/docs/user-manual/#man-pages [2] https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/man/asciidoctor.adoc https://raw.githubusercontent.com/asciidoctor/asciidoctor/ma...

gnuvince 9y ago
The main issue with this is that AsciiDoc cannot express semantics. When writing manpages, you can specify that something is a flag or a function parameter, etc.
- tkfu 9y ago
  I'd argue that (1) manpages are for humans to read, and (2) there is effectively only one presentation style for the conveying the semantic contents. So as long as the author of the manpage follows the standard conventions for manpage presentation style, they are in fact expressing the semantics. And it's a lot easier to learn the conventions (flags in bold, arguments in italics, etc.) and write them in lightweight markup than it is to learn roff.
  - opk 9y ago
    Semantic markup has more uses than just consistent presentation. For example, most of the BSD's use mandoc rather than groff for rendering which allows you to do more detailed searches with apropos. Note that the linked article refers to the mdoc macros. These aren't especially new and are very well supported but the man macros are still more common. If you dig into the details, the mdoc macros have many advantages.
    - deleted 9y ago
      [deleted]

rwmj 9y ago

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/master/p2v/virt-p2v.pod https://raw.githubusercontent.com/libguestfs/libguestfs/mast... and the output as HTML: http://libguestfs.org/virt-p2v.1.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.)

rwmj 9y ago
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 http://oirase.annexia.org/tmp/virt-p2v-man.ogv
- unixhero 9y ago
  Now that is a proper man page!
JdeBP 9y ago
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.
- rwmj 9y ago
  DocBook XML isn't bad, but don't you find the markup incredibly verbose?
  - JdeBP 9y ago

cat199 9y ago

quick plug for someone to do the legwork get heirloom troff in some real (read BSD) unix so that the whole roff toolchain is reintegrated after USL, that would be great.

jwilk 9y ago
What's USL?
- mwest 9y ago
  Unix System Laboratories - https://en.wikipedia.org/wiki/Unix_System_Laboratories https://en.wikipedia.org/wiki/Unix_System_Laboratories See also: USL vs. BSDi: https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc._v._Berkeley_Software_Design,_Inc https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc.....
  - jwilk 9y ago
    HN doesn't consider trailing dot part of the URL, so you need to URL-escape the dot (%2e) to make it work. (But I set up a redirect, so now the dotless URL works, too.)
luckydude 9y ago
As a long time roff user, I really prefer groff. It's better. It does colors, the pic implementation is programmable, it's just better. So here is a vote against heirloom and for groff. And I get it, the BSD crowd hates GNU and I have my own issues with the GNU folks, but come on, use better when it is better.