help2man

[Bob Rossi]

Hi all,

This is my first attempt at modifying the Makefile.am, to have some
extra work done for me automatically.

I've been working on my documentation for CGDB lately, and found a nifty
program called help2man which generates a simple man page. It looks at the
output of both 'cgdb --version' and 'cgdb --help'. Parses the output,
and generates a man page.

I have moved the 'usage ()' function in my application to it's own file
called usage.c.  I would like to set it up so that whenever that file is
modified, a new man page is generated with help2man. That way, the man
page never get's out of sync with the actual usage of CGDB.

One problem is, if the file usage.c is modified, then I have to set a
flag somewhere to tell me that I need to run help2man. However, I can't
run help2man until after the entire build is done. (CGDB needs to be
linked in order to run it.)

My doc directory is built after all others. I was thinking I could have
a rule in the doc directory that would run help2man if usage.c has
changed. However, if usage.c was changed, by this point, the usage.o has
already been built, so I don't know how I would be able to determine I
need to run this command.

Also, I did read this:
  http://www.gnu.org/software/automake/manual/html_mono/automake.html
  section: "Files left in build directory after distclean"

It talks about how to use help2man in several different ways. I was
hoping I could get some advice by someone who has actually done this to
figure out the best way. (Running help2man manually is an option if it's
just to complicated to put into the Makefile).

And finally, at the bottom of that section I may have found an error in
the documentation. There are 3 bulletted points. The first I understand,
the second I can't understand, and the third is worded funny.

  # Distributed files should never depend upon non-distributed built files.
  # Distributed files should be distributed will all their dependencies.
  # If a file is intended be rebuilt by users, there is no point in 
distributing it.

I suggest for the second the word 'will' was supposed to be 'with'
  # Distributed files should be distributed with all their dependencies.

I suggest the below
  # If a file is intended to be rebuilt by users, then there is no point 
    in distributing it.

Thanks,
Bob Rossi