tty2html - filter nroff output for HTML documents Version: 1.0 WHAT IF I'M TOO LAZY TO READ 'README'S? make make install man tty2html WHAT IS TTY2HTML? tty2html is a tiny program that filters backspaces from nroff(1) output, inserting HTML tags to reproduce bold and underlined text as faithfully as possible. WHY IS THIS SOMETHING I WOULD WANT? nroff(1) is the program that formats your manual pages for printing on a teletype (or terminal, emulating a teletype). The thing with teletypes is that they have paper. The thing about paper (unlike a crt, and most terminal emulators) is that you can print more than once in the same column of the same line (assuming your print head responds properly to backspace) without erasing anything that was already present in that column. Print the same character twice and you've got boldface. Print a bunch of underscores over the top of some other stuff and you've instantly underlined it. (Veterans of 1970s computer rooms -- or even some 1980s dot matrix printers -- will remember being able to tell when somebody was printing Very Important Words, because the 'clatterbox' in the corner would make an entirely different noise when the print head stopped dead in its tracks to overprint a single column on the paper, making the text at that point bold or underlined.) By now you've got the idea. One of the reasons why the output from the 'man(1)' program, which really comes from nroff(1), looks like it hasn't changed since the 1970s is that it really hasn't changed since the 1970s. It's still formatting manual pages to send to a teletype for printing (via mechanisms governed entirely by Newtonian mechanics) on a sheet of reconstituted tree. The output is riddled with backspaces, underscores and repeated characters. Converting that mess into HTML is what tty2html is all about. It removes backspaces while placing text overprinted with itself inside tags, and text overprinted with underscores inside tags. This looks lots prettier when viewed in a browser, believe me. (Don't believe me? Try this: echo '
' > echo.html
	man echo >> echo.html
	echo '
' > echo.html and then open 'echo.html' in your favorite browser. The only way it might look halfway presentable is if 'nroff' figured out that it wasn't writing to a terminal with backspacing capability, and decided to supress text attributes entirely.) BUT THERE'S 'MAN2HTML' AND 'GROFF -THTML', NO? Well, last time I looked, neither could cope with with BSD-style '-mdoc' macros. (These macros are more modern, easier to write, easier to read, easier to maintain, and just plain better all round than the old '-man' macros for writing manual pages. Don't let the iffy advice/opinion in the 'Linux Manpage HOWTO' put you off: '-man' is as dead as a headless chicken -- it just hasn't stopped running around yet. But of course, that's just my opinion. ;^p) WHERE IS THE LATEST SOURCE CODE? Source code is available from the author's home page at 'http://piumarta.com/software'. You can download the most recent release or use Subversion to get the very latest sources. WHERE IS THE DOCUMENTATION? A manual pages for tty2html should be available once it is installed. Use the 'man(1)' command to read it. HOW DO I INSTALL IT? It's not really big enough to warrant the whole 'configure' thing. Any system with an ANSI C compiler and librarues should be able to compile it out of the box. After unpacking the archive, just type: make to build it. If the compiler blows up immediately, edit the Makefile and play with the '-g' and '-O' flags and then try again. If you really can't make the compiler happy you've found a bug (read the next section but one). Otherwise, if you want it put it somewhere more permanent then type: make install (as root) to install it. It goes into /usr/local by default; if you want it elsewhere then set PREFIX in the make command. For example: make install PREFIX=/usr will put everything under '/usr'. When you get bored with it, go back to the source directory and type: make uninstall (with the same PREFIX you specified during the install, if necessary.) WHAT CAN I DO WITH IT? Clean up manual pages (and other nroff(1) output) for inclusion in HTML documents. The manual page will tell you about a few command-line options that aren't mentioned here. HOW DO I REPORT PROBLEMS? Send e-mail to the author at: firstName (at) lastName (dot) com (For suitable values of firstName and lastName, see the end of this file.) If you're still confused, contact him at: http://piumarta.com HOW CAN I HELP? Use it. Find bugs. Fix bugs. Make it more general, configurable, robust, whatever. Evangelism: find people who are complaining about the problems of putting '-mdoc' manual pages on the web, and tell them about it. WHO WROTE THIS STUFF, AND WHY? tty2html was written by Ian Piumarta. He was trying to publish one of his manual pages on the web at the time.