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.
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>.
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 tkfu on Saturday November 25, 2017 @10:32AM
(#15776317)
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.
Re:Practical Unix Manuals: mdoc
by gnuvince on Saturday November 25, 2017 @10:39AM
(#15776345)
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.
Re:Practical Unix Manuals: mdoc
by tkfu on Saturday November 25, 2017 @11:00AM
(#15776456)
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.
Re:Practical Unix Manuals: mdoc
by opk on Saturday November 25, 2017 @12:33PM
(#15776841)
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.
Re:Practical Unix Manuals: mdoc
by JdeBP on Saturday November 25, 2017 @09:45PM
(#15779194)
Using mandoc instead of groff is a bit of a step backwards, note.
grotty is capable of ECMA-48:1976 and ISO 8613-6:1994 control sequences, and can actually do proper italicization, boldface, underline, and colour in manual pages; which many terminals nowadays have supported for decades.
mandoc still only knows the old 1960s TTY-37 control sequences that use overstrike for boldface and underline and that have no notion of italicization or colour.
When FreeBSD switched from groff to mandoc, I went looking for any way to have mandoc support ECMA-48:1976 and ISO 8613-6:1994 control sequences. It turned out to be a large amount of work to bring it up to parity with something that the GNU toolchain has had since the 1990s (and is in fact the GNU toolchain's native mode of operation).
Re:Practical Unix Manuals: mdoc
by yepguy on Saturday November 25, 2017 @03:16PM
(#15777753)
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.
Re:Practical Unix Manuals: mdoc
by beefhash on Saturday November 25, 2017 @10:12AM
(#15776238)
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.
Re:Practical Unix Manuals: mdoc
by jwilk on Saturday November 25, 2017 @11:57AM
(#15776697)
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.
Re:Practical Unix Manuals: mdoc
by clort on Sunday November 26, 2017 @01:36PM
(#15782273)
> 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.
Re:Practical Unix Manuals: mdoc
by emj on Tuesday November 28, 2017 @08:40PM
(#15803731)
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.
Re:Practical Unix Manuals: mdoc
by DC-3 on Sunday November 26, 2017 @07:00AM
(#15780534)
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.
Re:Practical Unix Manuals: mdoc
by nerdponx on Sunday November 26, 2017 @10:38AM
(#15781316)
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.
Re:Practical Unix Manuals: mdoc
by cat199 on Saturday November 25, 2017 @03:07PM
(#15777715)
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.
Re:Practical Unix Manuals: mdoc
by luckydude on Saturday November 25, 2017 @09:59PM
(#15779228)
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.
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.)
Instead of explicit italicization and boldface
I write semantic markup which I find preferable.http://oirase.annexia.org/tmp/virt-p2v-man.ogv
[1] http://asciidoctor.org/docs/user-manual/#man-pages
[2] https://raw.githubusercontent.com/asciidoctor/asciidoctor/ma...
grotty is capable of ECMA-48:1976 and ISO 8613-6:1994 control sequences, and can actually do proper italicization, boldface, underline, and colour in manual pages; which many terminals nowadays have supported for decades.
* https://jdebp.eu/Softwares/nosh/italics-in-manuals.html
mandoc still only knows the old 1960s TTY-37 control sequences that use overstrike for boldface and underline and that have no notion of italicization or colour.
When FreeBSD switched from groff to mandoc, I went looking for any way to have mandoc support ECMA-48:1976 and ISO 8613-6:1994 control sequences. It turned out to be a large amount of work to bring it up to parity with something that the GNU toolchain has had since the 1990s (and is in fact the GNU toolchain's native mode of operation).
This didn't work for me (Debian unstable), because man called nroff, which doesn't understand the -P option.
So I put
in /etc/manpath.config . This did the trick, but I'm not sure it didn't break something else.> 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
[1] https://man.openbsd.org/?query=Ev%3DLANG&apropos=1&sec=0&arc...
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.
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.
See also: USL vs. BSDi: https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc.....
(But I set up a redirect, so now the dotless URL works, too.)