NAME

man2html.pl - convert a man page to HTML

SYNOPSIS

man2html.pl  [OPTIONS] 

DESCRIPTION

This script converts a man page to HTML format for web viewing. It was written because other man2html programs that I found did not support enough troff constructs.

It can be downloaded from "http://www.joelinoff.com/man2html/man2html.tar" . Just extract the tar file contents and run it. There is nothing to install, it runs right out of the box because it is based on perl.

To see how man works on a man page just type "man <man page>". Make sure that you have at least 1 forward slash '/' so man knows to use the file directly. Here is an example:

    man ./my.man

Here is how you would convert that man page to an HTML page using this tool:

    man2html.pl ./my.man > my.html

Man pages support all sorts of strange and wonderful constructs based on the roff family of tools. It is far beyond the scope of this tool to describe (or support) them all. If you are interested in more details here are some links that you might find useful.

The troff reference manual: "plan9.bell-labs.com/sys/doc/troff.pdf"

The GNU groff project: "http://www.gnu.org/software/groff/"

SUPPORTED CONSTRUCTS

This script does not handle all of the constructs supported for man pages or troff. It only handles the ones that are widely used. They are listed below. Constructs that start with a dot (.) must start at the beginning of a line. Constructs that start with a backslash (\) can appear anywhere on the line.

."	Denotes a comment. Here is an example. ." This is a comment
.\"	Denotes a comment using an explicit escape. Here is an example. .\" This is a comment
\(co	Denotes an embedded copyright symbol. Here is an example: .SH "COPYRIGHT" This program has been copyrighted (\(co) in 2009 by Spam, Inc. Here is what it looks like: \(co == ©
.B	The first token following this is made bold. It can handle quoted tokens with embedded spaces. Here is an example: .B FOO .B "FOO BAR SPAM" The .B, .I and .U can be combined onro a single line. The is very useful for table row entries. Here is an example. .BI "bold stuff" "italicized stuff" .BU "bold stuff" "underlined stuff" Man processing appears to limit this to two characters.
.br	Insert a line break. It like <br> in HTML. Here is an example: Break at after this line. .br This starts on a new line.
\"html	This is an extra keyword that looks like an embedded comment to man but is recognized by this program for inserting arbitrary HTML code. Here is an example: HTML code: .\"html <p>This is HTML code, copyright &copy; 1823. This is extremely useful for controlling HTML attributes like background color. It is also useful for embedding images. Here is an example that shows how to embed an image: Example Image
.\"html	This is an extra keyword that looks like an embedded comment to man but is recognized by this program for inserting arbitrary HTML code. It is very similar to ."html  except that it must start at the beginning of a line. Here is an example: .\"html <p>This is HTML code, copyright &copy; 1823. I use it to embed links as follows: .TH "SEE ALSO" .\"html <a href="www.google.com"> link1 .\"html </a> , .\"html <a href="www.yahoo.com"> link2 .\"html </a> , .\"html <a href="www.microsoft.com"> link3 .\"html </a> Note that there is space after the commas to make the output more readable.
.I	The first token following this is italicized. It handles quoted tokens with embedded spaces. Here is an example: .I FOO .I "FOO BAR SPAM" The .B, .I and .U can be combined onro a single line. The is very useful for table row entries. Here is an example. .BI "bold stuff" "italicized stuff" .BU "bold stuff" "underlined stuff" Man processing appears to limit this to two characters.
\N'<num>'	Allows you to insert an arbitrary ASCII character in the sequence. For example, I used it to embed double quotes in this man page. Here is an example of how it is used: I want to show the user what the dot+double_quote+html looks like. Here is what it looks like on the man page. .\"html Here is how it is described in the man page. ."html Note that " is the double quote (").
.nf and .fi	Preformat some text. It is like using <pre></pre> in HTML. Nf means "no fill", fi means "fill". Here is an example: .nf Do not format this line .fi It will output exactly as described above.
.P	Insert a paragraph break. It like <p> in HTML. Here is an example: paragraph 1 .P paragraph 2 Note that simply putting a space between paragraphs does the same thing: paragraph 1 paragraph 2
.PP	Appears to be exactly the same as .P. I have seen both in man files.
.SH  <hdr>	A section header. Here is an example: .SH DESCRIPTION This program does great stuff. And there is a lot more to tell you. .P It is so awesome! .SH ANOTHER SECTION Here are some details.
.SS  <hdr>	A subsection header. It is like a section header but slighly indented. Here is an example: .SH DESCRIPTION This program does great stuff. And there is a lot more to tell you. .P It is so awesome! .SS SOME DETAIAL Here are some details in a subsection.
.TH <program> <section> <center-footer> <left-footer> <center-header>
	The man page header. This should be the first non-comment entry in the file. It has five fields. All but the first are optional. I usually fill in the first two. program The program name (like ls or who). section The man page section. It can be a number like 3 or a name like MRTT. center-footer The contents of the center footer. left-footer The contents of the left footer. center-header The contents of the center header. The left and right headers on the man page are always the program and the section combined as <program>(<section>). Here is an example: .TH man2html JOE
.TP  <margin>
	Indicates the start of a table with two columns. The margin describes where the second column starts. If the contents of the first column are two large, the second column data moves down a row. The .TP statement has two entries. The first line is the contents of the first column. All subsequent lines are the second column. The second column terminates when one of the follows commands is encountered: .SH .SS .TP <margin> Here is an example of a simple table. .TP 16 ROW1 This is the column 2 data for the first row. .TP ROW2 This is the column 2 data for the second row. ." This is a new table (the old table ends). .TP 8 ROW1 This is the column data for new table. .SH "The second table ends"
.TP	A new row in an existing table. The .TP statement has two entries. The first line is the contents of the first column. All subsequent lines are the second column.
.U	The first token following this is underlined. It handles quoted tokens with embedded spaces. Here is an example: .U foo .U "foo bar spam" The .B, .I and .U can be combined onro a single line. The is very useful for table row entries. Here is an example. .BI "bold stuff" "italicized stuff" .BU "bold stuff" "underlined stuff" Man processing appears to limit this to two characters.
<leading spaces>
	If leading spaces are found on a line, it will be treated as preformatted text. This is very useful for inserting ASCII tables. Here is an example. .SH "TELL ALL" The table below tells all: Item Description ==== ================================= 39 Life, the universe and everything 72 Other more mundane stuff. Note the same thing could be accomplished using .nr and .fi.

EXAMPLE MAN PAGE

Here is a simple example of a man page:

MAN PAGE EXAMPLE

.'34'This is a man page example. .TH foo bar .SH NAME .B foo - is the bar'est program around. .SH SYNOPSIS .BIU foo OPTIONS program .SH DESCRIPTION Foo does really great stuff. .SS BAR SUBTOPIC It is really totally bar. .SH OPTIONS These are the program options. .TP 16 .B --help Real programmers don't need help. They look at the binary. .TP .BI --spam alot Spam alot. .SH WARRANTY NONE .SH COPYRIGHT Copyright (\(co) 2009 by spam, inc. .SH "SEE ALSO" ."html <a href="http://www.google.com"> google(1) ."html </a> , ."html <a href="http://www.yahoo.com"> yahoo(1) ."html </a> , ."html <a href="http://www.microsoft.com"> microsoft(1) ."html </a>

OPTIONS

-h	On line help.
-o  <file>
	Write the HTML output to a file instead of stdout.
-v	Generate verbose output. This is only useful for debugging. It will corrupt the HTML output if -o is not specified.
-V	Print out the program version and exit. .B

EXAMPLES

This section shows how to use the program.

> man2html.pl ./foo.man > foo.html
	Convert a man page by capturing stdout.
> man2html.pl ./foo.man -o foo.html
	Convert a man page using the -o switch.

AUTHOR

Joe Linoff

VERSION

$Id: man2html.man,v 1.3 2009/01/16 22:50:34 jdl Exp $

WARRANTY

Copyright (©) 2009 by Joe Linoff, Inc. All rights reserved. THE SOFTWARE AND INFORMATION ARE PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND.

This program is freely copyable and distributable in accordance with the GPL license.