Ubuntu Wiki

One desired goal to achive for maybe the HoaryHedgehog release, is a fixed version of the already shipped man pages. Man pages are basically eh *nix's user best friend in being the most accessible, preliminary source of information for running, developing, and hacking the system.

Work flow for fixing the man pages

Basically, every package includes it's man pages sources within it's source package, if you want to work on a package's man page(s) first make sure you have the right sources.list entry for hoary and get the source deb:

    pooh@tigershark ~ $ apt-get source <pkg_name>

This would download the source .deb, unpack it and install the sources under the current directory. You may want to create a <username>/devel directory, and do this under it , just to keep things organized.

Let's use the hello package for example:

pooh@tigershark ~/devel $ apt-get source hello
Reading Package Lists... Done
Building Dependency Tree... Done
Need to get 405kB of source archives.
Get:1 http://archive.ubuntu.com hoary/universe hello 2.1.1-4 (dsc) [562B]
Get:2 http://archive.ubuntu.com hoary/universe hello 2.1.1-4 (tar) [389kB]
Get:3 http://archive.ubuntu.com hoary/universe hello 2.1.1-4 (diff) [15.4kB]
Fetched 3B in 0s (7B/s)
dpkg-source: extracting hello in hello-2.1.1

Let's get inside the package's source directory and see what's there:

pooh@tigershark ~/devel $ cd hello-2.1.1/
pooh@tigershark ~/devel/hello-2.1.1 $ ls
ABOUT-NLS    config.guess  contrib  install-sh   missing        tests
aclocal.m4   config.h.in   COPYING  intl         mkinstalldirs  THANKS
AUTHORS      config.rpath  debian   m4           NEWS           TODO
BUGS         config.sub    depcomp  Makefile.am  po
ChangeLog    configure     doc      Makefile.in  README
ChangeLog.O  configure.ac  INSTALL  man          src

The hello package is a sample package to explain certain packaging system aspects and workings, see this to learn more about it, it's quite in interesting read.

So now what's next? On the main tree listing, we can see a man directory. This directory stores the text files in the roff format , which is the file format for most man pages.

Let's enter that dir and see what we have there:

pooh@tigershark ~/devel/hello-2.1.1 $ cd man/
pooh@tigershark ~/devel/hello-2.1.1/man $ ls
ChangeLog  hello.1  help2man  Makefile.am  Makefile.in

The interesting file for us is basically the hello.1. This is the man page in it's source format - the roff format for manpages, I will not get into explaining the roff format for now, one can identify where to do changes according to the already available text.

Note: Not all packages adhere to the /man convention, some might have it under /data, /, /debian under the main tree of the source package. In that case, just browse around the source tree (the midnight commander is a very good util for that purpose) and fine files which look something like that:

  *.nro
  *.{N} N= a number corrosponding to the man section this page is used for.
  ... something like that.

I can see the problem here with a no standard way to find where are the man page sources that one would need to work on in order to get them installed. However , this is the best that I could find from googling and recieving the very kind help of seb128, thanks Sebastien!

Please feel free to add / comment / change if you find anything to be an error, a misconception or else.

CategoryDocteam