What do you use for creating man pages?
 

Hey guys,

For any of you who create man pages, do you have any tool you'd like to recommend?

Thanks,
Rand

Well, um, "vi mymangage.3.src" for instance, with a little knowledge of how a man page is formatted. This is actually not complex, and you can take an existing man page source as example.

Then, "groff -man -Tascii mymanpage.3.src > mymanpage.3" or similar to generate the final man page.

Eric

I should have known that I would get some low-tech answers from fellow Slackers :p

I stumbled across some fancy GUI-based tool on the net a couple of months ago but I can't seem to find it now. I just downloaded and compiled ManEdit but I couldn't get the preview feature to work.

In the good ole days I used to build .ps documents by hand in Emacs but I guess I'm just getting too old or lazy or both and starting to like a little automation in certain tasks. :p

Try ManEdit which also has a nice viewer from the folks who wrote the Endeavour2 filer:
http://distro.ibiblio.org/pub/linux/...6.1-i486-1.tgz
Or if 'you roll your own' you can get the sources here:
http://distro.ibiblio.org/pub/linux/...manedit-0.6.1/

Or, even easier, I have this as a self-compiling ROX-Filer AppDir:
http://distro.ibiblio.org/pub/linux/...-0.6.1.tar.bz2
Just unpack anywhere you have priviledges and click to compile. You can still use it easy without ROX-Filer, too. Just cd into the ManEdit directory and run ./AppRun. Actually there are two binaries manedit and manview.

For a less low-tech answer, from a lazy man, try txt2tags, which allows you to create man pages, (X)HTML pages and a few other formats from a simple markup language. I use it for my website, but it does man pages just as easily.

Thanks guys. Gnashley I mentioned in my post prior to yours that I tried ManEdit (built it from sources) but that the preview feature (which must be the manviewpart- actually displaying a man page) doesn't work! I don't know what's broken but when I click help it says to make sure I have read permissions. All the permissions are fine- I can do a "man" on the page from the same terminal window and see the man page.

uselpa I am looking for a wysiwyg tool rather than learning another markup language, but thanks for the suggestion :p

Thanks,
Rand

I built a manedit package to see why it would not run the viewer... but the viewer works!
I just think the program is a little old and it crashes when you click the wrong buttons, and it does not fully support all possible man page tags.
Apart from that, it is useable enough. http://www.slackware.com/~alien/slackbuilds/manedit/

Eric

AlienBob, I was really surprised that the viewer didn't work- it's an essential part and I'm sure they must have tested it. I actually built it twice to make sure.

I may go back and grab another version of the source and try again. It looked like it would be a nice app if I could only actually use it! :p But it seems to me that I saw another really nice one somewhere. Now I must find it...

I think I have the mystery solved. I went back and got the binary package (yeah, I know) and installed it just to check. I think it was 0.5.12. The SOB worked fine.

Then I uninstalled that and pulled the source code back down (0.6.1) I compiled it and tested it and it worked. Then I built symlinks in /usr/bin so I didn't have to key the long path, and it broke when I reinitialized it.

I think there are probably some non-standard things going on in the config (I wanted to install it to /opt so I used the --prefix option) and I think what it does is when it initializes for a new user for the first time is to jump to the conclusion that the man command is also in /opt (in the manedit config it builds in the user directory the path is specified as a fullpath). Once I straightened that out, it started working.

Like AlienBob mentioned it is a little rough, so I'm still looking, but I'll keep it until I find something better.

If you have ROX, the AppDir I distribute lets you right-click on the icon to choose view-mode or edit-mode. plus you can just drag man-pages on to it to open them, whether they are compressed or not.
ManEdit uses a non-standard tarball structure and config commands. You can easily gather the info from My PkgBuild script for the regular application:

#!/bin/sh
## Advanced.PkgBuild script for: manedit
## Amigo PkgBuild-0.3 - Gilbert Ashley <amigo@ibiblio.org>
##### ------------Standard Package Variables-------------------
# Most source code only needs these 4 variables set.
# Set SRC_SUFFIX to ".tar.gz" ".tgz" ".tar.bz2" or ".tbz"

BUILD="1"
NAME="manedit"
VERSION="0.6.1"
SRC_SUFFIX=".tar.bz2"

#####--------Common Overrides and Options----------------------
# PRE_FIX=""
# EXTRA_CONFIGS=""
DOCLIST="AUTHORS LICENSE README manedit.CHANGELOG"
# GROUP_NAME=""
#######----------------Processing------------------------------
# Get functions and read in configuration files
source /usr/share/Amigo/PkgBuild/FUNCTIONS ;
# This template calls each process individually so you can add
# extra instructions between processes, or even leave out steps.

pre_process ;
find_source ;
make_dirs ;
unpack_source ;
fix_source_perms ;

# since manedit configures weird we cancel configure_source and manually configure
# configure_source ;
cd $SRC_DIR ;
./configure Linux --prefix=$PRE_FIX

compile_source ;
fake_install ;
fix_pkg_perms ;
strip_bins ;
create_docs ;
compress_man_pages ;
make_description ;
make_doinst ;
make_package ;
post_process ;
exit 0
# end of script

If you want to use the viewer you have to call 'manview'.

That's a good point. I already set up ROX to pop open the manedit GUI when I click on a man page...

If you wanna see a weird, non-standard build that's seriously tweaked, look at Scintilla/Scite. There's no configure- but it allows you to specify an installation path on make, instead. And when you make install, it ignores whatever path you set.

Out, out, damn SciTE!