Is there a tool for editing man pages?

guoqiang

guoqiang

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?
 
Most converters can preserve the layout, up to an extent, but not the meaning (semantics); see mdoc(7). What I want to say is that the result will look like a man-page, but program names, command-line arguments and options, whether they are optional or mandatory, will not be marked with semantic markup, but with presentation markup, instead (i.e. bold, underlined, etc.)
 
Compared to all the other work and skill required to write a program, writing the troff code for the man page is simple. Grab the source to a random command, and just do "monkey see - monkey do" editing, and it will be quite obvious. A good starting point is /usr/share/man/man1/tee.1.gz, which is short (about 50 lines excluding the copyright at the top), and has all the important sections.

Troff is actually very simple. UPDATE: Yuripv is right; the mdoc flavor of troff is what everyone uses; so much so that I had forgotten the distinction between real mdoc and plain troff, since I've never actually written plain troff.
 
You can generally input plain text to troff, but it doesn't like blank lines. The commands go at the start of a line and begin with a "." For example, here are some handy ones:
.Pp produces a new paragraph, like <p> in HTML.
.Ss starts a new subsection, like <h3> in HTML. The heading goes on the same line after it.
.Sh starts a new section, like <h2> in HTML.
.Bd -literal starts a preformatted section, similar to <pre> in HTML. The text then continues on the next line after it.
.Ed ends the preformatted section, similar to </pre> in HTML.
 
ralphbsz said:
Troff is actually very simple.
Click to expand...
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.

Groff increased the problems of Troff by adding hundreds of extra features and extensions to an already bad idea. As far as I know, the only people who ever used the Groff features were the people who wrote the Groff manual pages.
 
Conceded. Using *roff as a full typesetting system must be insane; I've never tried it, but I know people who do.

TeX and LaTex have quite the learning curve. 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). 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).

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.
 
ralphbsz said:
Conceded. Using *roff as a full typesetting system must be insane; I've never tried it, but I know people who do.
Click to expand...
Well-known examples are the book "The C programming language" by Kernighan and Richie and all of W. Richard Stevens' books.
ralphbsz said:
TeX and LaTex have quite the learning curve.
Click to expand...
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.
ralphbsz said:
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).
Click to expand...
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.
ralphbsz said:
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).
Click to expand...
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.

Anyway, I don't know what software magazine and book publishers use at the moment, but I am sure it isn't Troff or Latex. I don't think JK Rowling's bestsellers are typeset using Latex.
ralphbsz said:
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.
Click to expand...
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.

However, FreeBSD's backward-compatible approach certainly beats Gnu's behaviour in first making the "expanded Troff" of Groff, and then switching over to their own info system, and then adding manual pages to their projects but with most of the information left out. It's also better than creating half-baked monstrosities like doxygen. That's why I would recommend sticking with the manual page system, but it would be great if there was a way to make a simple manual page without having to learn its ins and outs, like a Microsoft Word "Wizard" for manual pages.
 
It’s nice to see someone advocating for user-friendliness in free software. I had the misfortune to use Lyx once, and that was bad enough - never touched Latex. I have a rule that if I can’t figure out how an app works in less than an hour, it’s the developer’s fault, not mine. :D
One of my pet peeves is git. I have understood calculus textbooks yet I cannot understand git. :rolleyes:
 
You must log in or register to reply here.
Back
Top