man pages plus {with cached sample code}

[Bill Hernandez]

Over time I have written a bunch of shell scripts. Some I use  
frequently, some I never use.

One of the handy ones is called bh_man. It creates a small hierarchy  
of directories if they don't exist, checks the $PATH in ./ 
bash_profile, and sets it if necessary.

The gist of it, is that it would be nice to be able to add {comments,  
notes, sample code, urls, etc} to man pages, but I don't know of an  
easy way to do that, so with that in mind I wrote "bh_man".

When bh_man is called with an argument (unix_command_name) it first  
determines if I already have that command in my personal cache, if it  
exists then it pulls it up instead of the actual man page, if it does  
not exist in the cache, it copies the man page, strips out all the  
bizarre characters, and opens it in BBEdit.

The huge advantage is that the cached document pulls up instantly, is  
easily editable with BBEdit, or any other text editor, and the best  
thing is that I can add/modify {comments, notes, sample code, urls,  
etc} for each man page I choose to. Consequently most of the commands  
I have already cached have a lot of example code included. The example  
code is right at the top, so once I have added some snippets, I don't  
even have to scroll through the document. The examples are right  
there...

The hierarchy below shows that a dir is created that provides a  
starting place at "~/unix_scripts".

The "bh_man" script does the following :

( 1 ) checks the "~/unix_scripts" hierarchy, and creates it, if it  
does not exist.
( 2 ) checks "~/.bash_profile", and creates it, if it does not exist.
( 3 ) checks "~/.bash_profile" to make sure "~/unix_scripts/bin"  
exists in the path, and adds it to the $PATH, if it does not exist.
( 4 ) creates the "bh_open" shell script in "~/unix_scripts/bin"
( 5 ) when finished with steps ( 1 ) thru ( 4 ) above, it moves  
(itself) "bh_man" to  "~/unix_scripts/bin" as shown below.

Note : The hierarchy below shows, for example, when you do "bh_man  
open" it creates "open.txt" as shown below.

I put the hierarchy in my home directory instead of /usr/local or /opt/ 
local, because it gets backed up more often that way.

 > unix_scripts
	> admin
	> bbedit
	> bin
		bh_man
		bh_open
	> docs
		> manual
			open.txt
	> help
	> history
	> logs
	> macports
	> misc
	> modules
	> src

These are the commands I have already, many of them contain sample  
usage code, which for me, is what the man pages have always lacked,  
even some simple examples would be nice.

Anyway I figured out a way around the problem for myself.

If anyone is interested in trying the script please reply. If there is  
enough interest, I'll put it on my server.


	> docs
		> manual
			addgroup.txt
			adduser.txt
			alias.txt
			ascii.txt
			awk.txt
			bash.txt
			bz2.txt
			bzip2.txt
			case.txt
			cat.txt
			chmod.txt
			colrm.txt
			curl.txt
			cut.txt
			date.txt
			defaults.txt
			diff.txt
			DirectoryService.txt
			dscl.txt
			dseditgroup.txt
			dsexport.txt
			dsmemberutil.txt
			echo.txt
			egrep.txt
			export.txt
			file.txt
			for.txt
			format.txt
			FUNCNAME.txt
			functions.txt
			getcwd.txt
			getopts.txt
			grep.txt
			group.txt
			id.txt
			jot.txt
			kill.txt
			launchd.txt
			lookupd.txt
			loop.txt
			ls.txt
			mkdir.txt
			mysql.basic_info.txt
			mysql.GRANT.txt
			mysql.mysqladmin.txt
			nicl.txt
			nidump.txt
			niload.txt
			nireport.txt
			niutil.txt
			open.txt
			operator.txt
			parameters.txt
			passwd.txt
			pgsql.txt
			pidof.txt
			port.txt
			printf.txt
			PS1.txt
			psql.txt
			rand.txt
			read.txt
			reboot.txt
			redirection.txt
			repl.txt
			rm.txt
			rmdir.txt
			rpl.txt
			rs.txt
			security.txt
			sed.txt
			seq.txt
			sh.txt
			sort.txt
			ssh.txt
			str_repeat.txt
			stty.txt
			su.txt
			sudo.txt
			tar.txt
			tee.txt
			termcap.txt
			test.txt
			touch.txt
			tr.txt
			uname.txt
			wc.txt
			wget.txt
			xargs.txt

Best Regards,

Bill Hernandez
Plano, Texas