___________________________________
|      |  |  |     |  _  |     |  |
|  |___|  |  |  |  |    _|  |  |  |    GNU GLOBAL source code tag system
|  |   |  |  |  |  |     |     |  |
|  ~~  |   ~~|     |  ~  |  |  |   ~~|          for all hackers.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Copyright (c) 2005 Tama Communications Corporation

 This file is free software; as a special exception the author gives
 unlimited permission to copy and/or distribute it, with or without
 modifications, as long as this notice is preserved.

 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

                ----------------------------------

Htags Hyper-text Reference Kit.

[What is this?]

The hyper-text generated by htags(1) is available from external programs.
This kit helps you to convert the path of the source file into the URL
in the hyper-text.

[How does this kit do?]

Htags(1) generates the mapping file named 'FILEMAP' as part of the output.

$ htags -sanog
$ ls HTML
D        I  MAP  S  defines       files       help.html   mains.html
FILEMAP  J  R    Y  defines.html  files.html  index.html  rebuild.sh
$ _

This file includes a path->URL mapping table like follows:

	[HTML/FILEMAP]
	+-----------------------------------
	|AUTHORS S/134.html
	|COPYING S/135.html
	|ChangeLog       S/136.html
	|FAQ     S/137.html
	|INSTALL S/138.html
	|LICENSE S/139.html
	|Makefile.am     S/140.html
	|NEWS    S/141.html
	|README  S/142.html
	|THANKS  S/143.html
	|acinclude.m4    S/144.html
	|configure.ac    S/145.html
	|convert.pl      S/146.html
	|doc/Makefile.am S/148.html
	|doc/fdl.txi     S/149.html
	|doc/global.txi  S/150.html
	|doc/texinfo.tex S/151.html
	|global/Makefile.am      S/153.html
	|global/global.c S/1.html
	|global/manual.in        S/154.html
	|globash.rc      S/155.html
	|gnusort/Makefile.am     S/157.html
	|gnusort/README  S/158.html
	|gnusort/closeout.c      S/2.html
	|gnusort/closeout.h      S/3.html
	|gnusort/error.c S/4.html
	|gnusort/error.h S/5.html
	|...

This kit offers the API to convert the path name into the URL using
the mapping table. Of course, you can use the table directly, but it
might be annoyed.

[Application example]

To get the URL of i386/i386/identcpu.c at 120, you can write the
following code:

	char url[MAXPATHLEN+1];

	/* Load filemap from "HTML" directory. */
	ret = htags_load_filemap("HTML");
	if (ret != 0)
		ERROR;
	/* Get URL of the specified file name and line number. */
	ret = htags_path2url("i386/i386/identcpu.c", 120, url, sizeof(url));
	if (ret != 0)
		ERROR;

	url == 'HTML/S/1238.html#L120'

	/* release resource */
	htags_unload_filemap();

Function interface in detail is written at the head of each function
in htags_path2url.c.

[How to make back links?]

There are two htags's options for it.

       --insert-header file
              Insert custom header derived from file after <body> tag.

       --insert-footer file
              Insert custom footer derived from file before </body> tag.

$ htags --insert-header=anchor.txt --insert-footer=anchor.txt

	[anchor.txt]
	<a href="../index.html">main page of your system's output</a>

                ----------------------------------

Since the source code of this kit is placed into the public domain,
you can include the code into your copyrighted files. See the header
of each file.

DISCLAIMER - This kit supports only GLOBAL-4.8.6 or the later. It doesn't
work on the old hypertext generated by GLOBAL-4.8.5 or the former.

Good luck!
