I wrote a software that needs to write man pages, but I don't know what tools to write. Is there a tool for conversion or editing?
Reaction score: 139
Reaction score: 308
It may be simple to write a manual page, but Troff isn't very simple, it's a horrible and very complicated thing. Even the nightmarish macro-based "TeX" system of Knuth looks bearable compared to Troff. It was originally written in assembly language by someone called Joe Ossanna, which explains some of the whacky decisions about the commands.Troff is actually very simple.
Well-known examples are the book "The C programming language" by Kernighan and Richie and all of W. Richard Stevens' books.Conceded. Using *roff as a full typesetting system must be insane; I've never tried it, but I know people who do.
They are languages based on macro expansion, which is more logical than Troff, but if you have experience of trying to debug a broken TeX or Latex macro, you might notice they are good examples of why macro expansion is a poor language design choice. See also C++ templates for a similar experience.TeX and LaTex have quite the learning curve.
I don't think they are astonishingly powerful, they are just the default which everyone ended up using because they were free of charge and slightly less batty than eqn and friends. I don't think anyone would design a new commercial system based on macro expansion.To do something interesting takes weeks or months of practice. Once you have that, they are astonishingly powerful for making the kind of things they were built for (technical documents, articles, reports).
Microsoft Word has inherent problems which are similar to Troff's, it's a poor design which had to be maintained for backwards compatibility. I used to write automation of Word using Win32::OLE, and there are some extraordinary behaviours lurking in Word.And if you use LaTex not as a document formatting language (make this bold, move this here), but as a document markup language (this is a heading, this is a footnote), then it becomes very productive. I've formatted quite a few documents that range from 100 to 500 pages with it, and at that scale, I don't think there is a realistic alternative. Word and its descendants clearly is not good enough, even though people use it (with great difficulty).
For the most part you can copy and paste, but there are lots of places where it's quite easy to slip up. For example .nf is supposed to give you preformatted text, but it doesn't work correctly so you have to use .Bd -literal instead. There are other examples of quite tricky behaviour for the various .Fn macros, for example one has to put quotes around the arguments to .Fa and so on. Generally I don't think it's a very logical system.But the statement that I think is true: Troff with the mdoc package is very simple *for making man pages*. In particular if you follow the example of existing man pages. Man pages are very different from complex documents.
Reaction score: 20