LinkLib 1.0 package
===================

The LinkLib package is a set of libraries for creating symbolic links under FreeDOS
and other DOSes. The symbolic links created are compatible with the links of the Seal
GUI for DOS.

1.- Components, packages and versions
2.- Specifications
3.- Usage
4.- Limitations
5.- Future plans
6.- Error messages
7.- Contacting and reporting bugs
8.- Copyright


1.- COMPONENTS, PACKAGES AND VERSIONS
======================================

Each LinkLib package is distributed including the following files:

DOC                   Documentation folder
DOC\README.TXT        The Read Me document for LinkLib (description and copyright)
DOC\NEWS.TXT          News item posted to the FreeDOS mailing list
DOC\LGPL.TXT          A copy of the LGPL license, under which APMLib is released
DOC\LINKLIB.TXT       This file

INCLUDE               Header files for the C source
INCLUDE\LINKLIB.H     Header for the LinkLib library
INCLUDE\CEXT.H        Additional header used by LinkLib (C extensions)
INCLUDE\REGFS.H	      Additional library used by LinkLib (Refistry in File System)

BIN                   Precompiled Borland C modules
BIN\LINKLIB.OBJ       LinkLib compiled in the small memory model

LIB                   Borland C Libraries
LIB\LINKLIB.LIB       LinkLib.LIB made from the small memory model compiled APM

UNITS                 Pascal units
UNITS\APMLIB.TPU      TurboPascal unit
UNITS\APMLIB.PPU      FreePascal unit (GO32V2)

SOURCE                Source files
SOURCE\APMLIB.C       C source file
SOURCE\APMLIB.PAS     Pascal source file

This package is labeled as:
     LinkLib 1.00 English

This version is compatible with TC++3.0, TurboPascal 7.0 and FreePascal 0.99.14a

If you want to know about the latest update of the program, please contact
the authors as specified in (6).


2.- SPECIFICATIONS
==================

The specifications of this project are set in the definition of the format of a LINK
file, which is what follows.
These specifications have been obtained from the Seal specifications, as well as from
the collaboration of members of the FreeDOS' developers list (see http://www.freedos.org)

File naming:   <link name>.LNK
File structure: (text file)
-----
[definition]
link="string1"
workpath="string2"
icon32="string3"
----- (last two lines are OPTIONAL)

where:
string1: is a string that should describe the location of the object
which is pointed by the link
string2: is a string that should describe the working directory where
the target object should be started before invoking it
string3: is a string that should describe the location of an object that
will define a 32-bit sized icon (for Seal compatibility)


As an example, this could be a link to an editor in C:\BIN. Note that no special
workpath is needed.

---- EXAMPLE: EDIT.LNK
[definition]
link="C:\BIN\MYEDIT.EXE"
icon32="C:\ICONS\SET1.ICO:13"
---- END of EXAMPLE


3.- USAGE
=========
linklib uses the functions implemented by this library/unit are (pseudocode):

------------------------------------------------------------------
   func checkLink (POINTER TO fname: string)
	ret bool;

Checks if the file with name 'fname' is a symbolic link, by checking if the file
actually exists, or 'fname'.LNK exists. Returns TRUE if the checking was successful.
If 'fname' doesn't exist, but 'fname.lnk' exists, then fname is modified, and the
extension .lnk is added.

------------------------------------------------------------------
   func LinkGetDir (lname: string)
	ret string;

Returns the workpath of the link with name lname.

------------------------------------------------------------------
   func LinkGetTarget (lname: string)
	ret string;

Returns the file pointed by the link with name lname.

------------------------------------------------------------------
   func StartLink (lname: string)
	ret int;

Executes the link of name 'lname'. Returns the DOS program termination code.

------------------------------------------------------------------
   func CreateLink (lname, target, startdir, icon32: string)
	ret bool;

Creates a link with name 'lname', workpath 'startdir', with name 'lname', and having
a 32-bit icon descriptor 'icon32'. Returns TRUE when the file was successfuly created,
FALSE otherwise (the file couldn't be created for some reason).


4.- LIMITATIONS
================

LinkLib has been designed to work in DOS systems. Note the following:

- The default extension of the links is 'LNK', which is the extension used for the symbolic
links of Microsoft Windows. HOWEVER, both link formats are mutually incompatible.

- The link detection is based on names, and not contents. The only way to check if
the contents of a link is corrupt is to try and read the target of a link. If a NULL string
is returned, then there is a problem with that link.

- Link creation works upon existing good conditions for creating links: non-write protected disks,
free space, etc. The size of a sybolic link is usually under 100 bytes.

- Links are SYMBOLIC, not real. DOS apps that haven't been designed using LinkLib won't be
able to open links.


5.- FUTURE PLANS
================

Current release is final, and there are not known bugs.

Future releases will be tested under:
- TurboC 2.02
- TurboPascal 5.5
Any feedback reported for these or other compilers will be greatly appreciated.


6.- ERROR MESSAGES
==================

There are no error messages, the program is up to checking the appropiate results from the
library.

7.- CONTACTING AND REPORTING BUGS
=================================

You can contact the author via e-mail:
Aitor Santamaria <aitor.sm@terra.es>

please, place LinkLib somewhere in your subject line. Contacting the author will
help you:
- Know about latest release
- Try to solve your problems
- Get more information about LinkLib
- Get more information about other programs available

There are currently no known bugs. If you want to submit a bug, please check
that it is a real bug, and if it is, then submit a mail to the author
stating:
- The link where you came up with the problem, and its location
- A description of the problem as accurate as possible
- Other special circumstances


8.- COPYRIGHT
=============

LinkLib is a package to manage links under DOS
Copyright (C) 2000 - Aitor Santamaria


-------------------------------------------------------------
This package is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details (www.gnu.org)
-------------------------------------------------------------
