how-to-generate-hyperlinked-source.md

How to generate hyperlinked HTML pages for C source code

Step 0: install 'global'

You can do this either by using your package manager, or by compiling from source. Caveat: Ubuntu/Debian carries an old version; see the appendix if you have to use this version.

Step 1: run gtags

Go to your project's top directory and run:

$ gtags -v

This creates the tags database (the files: GTAGS, GRTAGS, GPATH).

Step 2: run htags

Next, we generate the HTML pages. Run:

$ rm -rf HTML/       # delete the old HTML tree, if exists.

$ htags --suggest

This creates the HTML/ folder with gazillion of files.

Step 3: run htagsfix

The HTML pages 'global' generates have numeric names like 1234.html etc. This is unfortunate. We fix this by running the script htagsfix (click the "Raw" button, or "Download ZIP", on that page to download it):

$ htagsfix

This script changes the filenames from 1234.html, for example, to lib--widget--menu.c.html (Note: "--" is used instead of "/"). It also adds CSS that highlights the #anchor line (it adds yellow background to it).

That's all! You can now open HTML/index.html in a browser.

Appendix

For users of old versions of 'global' only!

As noted earlier, Ubuntu carries an old version of 'global'. If you're adamant on using it, here are a few tips:

• It doesn't ship with the icons used in the HTML pages. Your browser will show the "alt" text instead. Here's how to install the icons:

$ cd HTML/icons
$ wget http://tamacom.com/global/global-6.5.1.tar.gz
$ tar zxvf global-6.5.1.tar.gz --wildcards --no-anchored --strip-components=2 'icons/*.png'
$ rm global*.tar.gz

• The CSS htagsfix adds isn't effective for this old version. So, if you wish, add instead the following to HTML/style.css:

/* Highlight the #anchor line. */
a:target { background: yellow }

/* Make the filename box fixed. */
.header:nth-child(2) {
  position: fixed; background: white; padding: 0.6em;
  border: 1px solid black; right: 6em; top: 4.5em;
}