On Mon, 31 Oct 2011 15:25:48 +0000
Connor Lane Smith wrote:
>
> Roff is actually one of the ugliest markup languages I have ever seen.
> HTML is actually pretty decent if you think about it. It's
> (more-or-less) XML, which isn't nice, but I'd take that over roff any
> day. Anyway, the main problem with the web is the obsession with CSS
> and JavaScript.
>
I'm not aware of any documentation directly written in roff. I would
say that is nothing wrong with man pages, just tools are bad. Groff
(most popular troff formater) is very slow, to the point that
preformated man pages (so called cat pages) were quite popular.
Grep-ing them isn't fun. If you wonder why, just dive in into man(1)
command code (4-5 pipes or even more before piping to pager).
Because cat pages were used, searching was pretty bad. Apropos is
using data mostly from description and synopsis section of manuals.
Others problems arised after dot-com boom. Generating HTML from roff
wasn't quiete easy.
So people from GNU came up with texinfo format, but man pages refused
to die. Then we have seen DocBook rise, still man pages are around.
Now EPUB is next man-page-killer I heard. Do you see any pattern here?
Most common are man(7) macros, but there are also mdoc(7) macros.
Below you can find simple comparison between those two, I wrote this
some time ago (example shows common SYNOPSIS section of manuals).
How it should look after formating:
foo [-bar] [-c config-file ] file ...
.\" First man(7) format:
.
.B foo [-bar] [-c
.I config-file
.B ]
.I file
.I ...
.
.\" B macro stands for bold text, I for italic text.
.\" Now mdoc(7) format:
.
.Nm foo
.Op Fl bar
.Op Fl c Ar config-file
.Ar file
.Ar
.
.\" Nm stands for manual name, Op for command-line option,
.\" Fl for command-line flag, Ar for command-line argument.
It's easy to recognize that man(7) is all about presentation
formatting, where mdoc(7) is structural format. What this means?
Structural formats are easier to convert and they give information that
can be reused for searching (searching library man pages for specific C
function and so on).
Still in Groff case it doesn't matter - both formats are translated to
roff and structural data from mdoc(7) is lost. Some time ago project
named mdocml [1] was created mostly by OpenBSD folks. mdocml turns
whole paradigm upside down: end format is mdoc/man, and roff macros (if
there're any) are just additions.
This way structural data from mdoc(7) isn't lost and can be used for
html/pdf/ps output (nice looking docs without additional steps).
Works on better apropos have also started.
There is also great guide about writing man pages (mdoc macros
specific) [2].
On Mon, 31 Oct 2011 14:57:08 -0000
"Bjartur Thorlacius" wrote:
>
> Just pipe the markup through htmlfmt(1) or html2text(1) if you like
> reading documentation on terminal emulators.
>
$ mandoc -Thtml some_man_page.1 | lynx -stdin
If you like reading documentation in web browser.
[1] http://mdocml.bsd.lv/
[2] http://manpages.bsd.lv/
--
Paul Onyschuk <bl...@bojary.koba.pl>
