___________________________________
|      |  |  |     |  _  |     |  |
|  |___|  |  |  |  |    _|  |  |  |    GNU GLOBAL source code tag system
|  |   |  |  |  |  |     |     |  |
|  ~~  |   ~~|     |  ~  |  |  |   ~~|          for all hackers.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Copyright (c) 2005, 2006 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 Hypertext Reference Kit.

[What is this?]

The hypertext 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 hypertext.

[How does this kit do?]

Htags(1) generates a 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 APIs to convert path name into URL using the mapping table.
Of course, you can use it 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 generated by htags(1). */
	ret = htags_load_filemap("HTML/FILEMAP");
	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 == 'S/1238.html#L120'

	/* release resource */
	htags_unload_filemap();

Since obtained URL is a relative path from the HTML directory, you should
modify it so that your application program works well.

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 program. 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!
