OPERATION OF CHEKLINX      (c) www.merlyn.demon.co.uk      >= 2006-01-22


Purpose:

CHEKLINX is used off-line to verify local, relative hyperlinks on a
local DOS or Windows master copy of a Web site.  By default, it recurses
through all local links found.  It does not guarantee to detect all
possible local links (e.g. each of href & name must be the first attribute
in their <a ...>, and so should not share one) but in practice detects
well over 99% for me.

It will also report explicit references to the local hard disc, and
can/will report some other types of error or probable error.

Web pages are assumed to be at least near enough valid HTML as judged
by, for example, W3's TIDY; the HTML, as such, is not checked.

It is a 16-bit Borland Pascal 7 (MSDOS/DPMI) and 32-bit Borland Delphi 3
(Win32 Console mode) program.


Fetching:

Those familiar with DOS and/or ZIP can modify the following.

Before fetching cheklinx, make sure that you can use DOS or can open a
DOS prompt in your version of Windows, and that in it you can change to
the directory containing your local copy of the index.htm or index.html
or another HTML file - in fact, it may help to do so.

Connect to the Net, and use your Web browser to save, in that directory,
Web <URL: http://www.merlyn.demon.co.uk/programs/cheklinx.zip>.  If you
don't know how to unzip, also fetch and save <URL: http://www.merlyn.dem
on.co.uk/zipfiles/xall.exe>.  If you may want to recompile, fetch also
Web <URL: http://www.merlyn.demon.co.uk/programs/version.pas>.  The
executable provided in the Zip file is a 16-bit BP7 MSDOS stand-alone
EXE, running in DOS or Windows.  There should also be a larger 32-bit D3
console EXE at <URL: http://www.merlyn.demon.co.uk/cheklinx.exe>, for
larger sites.

After the call, unzip cheklinx.zip (you can type, in that directory, at
the DOS prompt, "xall cheklinx.zip" without quotes) to extract the files
cheklinx.exe, cheklinx.pas, and this cheklinx.txt.

After reading this file at least twice, if all seems well, enter, at
that DOS prompt, "cheklinx /h", and read the result.


Usage - general:

At the prompt, "cheklinx [options] index.htm" (or .html, or other file).

By default, it will pause on anything that it thinks needs attention,
needing Enter to proceed; it no longer needs an Enter after its final
summary.  Enter is prompted by "<cr>".

Normally, before each Enter, I fix the problem with a Windows program
or using another DOS box.  I know nothing whatsoever about WYSIWYG HTML
editors, what errors they can generate, and how to fix them - I
hand-edit HTML, with software assistance, using PFE, DiDa, and Notepad.

Alternatively, one can use option /V1 (that's a one) and redirect or
pipe the output for subsequent viewing.

If you use Long File Names much (I don't), then use "cheklinx /L0 ..."
(that's a zero) to make them fully acceptable.

The program is not javascript-aware - it will not look within "<!--"
... "-->", even after "<script ...>".  Unless script uses those marks,
it may be necessary to put a space after the "<" operator, and to
double comment symbols in VBscript.


Usage - detail:

DosPrompt> CHEKLINX Parameters

Parameters are used in sequence; options begin with / and others are
non-wild files.  The program writes only to Standard Output (except for
Option J).  File parameters must not start '\'; but c:f, d:\f, e:d\f,
e:\d\f are OK.

If there are no file parameters, a final index.htm is assumed.

The effect of giving more than one file parameter is currently unsettled.

If conditional LFN is set, then Long File Names are enabled, which requires
Andreas Killer's LFN unit; with that, or Delphi, spaces and %dd are supported.
Relative link components are reported if containing "\" or if not within
DOS 8.3 format.  Duplicate NAMEs within a file are detected.  Anchors are
case-dependent; file-names are not tested for case.

/: sets to pause (if Viz>1) on reporting apparent direct local reference.
/A<number> controls stopping on "already not found", default 2, 0 is n/a.
/B - BASE - see below.
/C<digit> controls testing local link filenames for Upper Case, default 2.
/D<number> limits the depth of file recursion.
/F<number> limits the number of files whose HREFs, SRCs, &c., are tested.
/J<string> write "command filename" to file "string", lists files seen.
/K<string> command for /K file - default is "test"
/L<digit> controls testing local link filenames for not 8.3 (LFN), default 2.
/P enables seeking cites within <PARAM ... >.
/Q<digit> controls testing for unquoted HREF/NAME/&c., default 1.
/V<number> sets Viz output volubility control, 0..5, default 2.
/U<digit> controls testing for unused NAMEs, default 0.

Where applicable, <digit> is:
  0 for do not check this
  1 for check, and report if found, but do not pause
  2 for check, and report if found, and if so pause

<BASE HREF=(Web directory)> : with /B<...> option
/B needs http://.../, else Web directory = DOS current directory.
if no /B is given, it assumes that BASE gives the current Web directory.

Options /J & /K support generation of a batch file to process files found
in the set; for example, with W3's TIDY - /Ktidy /Jrunme.bat.

If there's too much or too little output, use the Viz option /V<number>;
by default, Viz=2, and so the program pauses on finding an error.  Viz=0
is intended for automated testing, outputting only errors.


Program Versions:

This is a BP7/TP7 program, for MSDOS/DPMI modes; DPMI gives more Heap.
With Delphi 3 "DCC32 -cc" console mode, it works (3 compile warnings)
and handles much larger sites.

The name Viz is used rather than Debug, which was to allow TMT's Debug unit.

The program is tested in DOS6.20 and in a Win98 DOS box.

Expected Runtime Errors : 202 = Stack overflow, 203 = Heap overflow.  If
these occur in the Borland Pascal version, try (if possible) the Delphi
one.

The program will terminate if < ... > is too wide (>|BufMin|) and
unfortunately positioned; the probable causes are using < instead of &lt;,
or a large script unit.

The Pascal 16-bit EXE, testing my WWW site master copy, is insufficient
for stack; the Delphi 32-bit EXE is adequate.  Option "//" may one day
remove this problem.


Compile-time Conditionals

For BP7, setting LFN enables Long File Names; see above.

The standard version seeks depth-first (easier; but costly in stack).  If
compile conditional SLASH is set, width-first code is included (as yet
very far from complete, and not making progress), and can be enabled by a
parameter '//'.


What it does:

It reads pragmatically; it does not do a formal parse.

Relative A HREF=, IMG SRC=, &c., are checked to see whether the file
exists, and for each relative A HREF=xxx#yyy, A NAME=yyy is sought in
file xxx; only the first AncLen=20 characters of yyy are significant.
Direct references (as C:, file:) to local drives should give a warning.
Line numbers refer to the opening '<' of the relevant construct.
If a reference contains a "?", it is truncated from that position.  Thus
my reference to the Demon counter can be satisfied by file cgi-bin\count.
N.B. HREF= & NAME= must follow <A to be seen, with only whitespace between.
N.B. There must be no space before =.

For other file references sought, see "if SeekFileRef" lines in cheklinx.pas.

Some constructions which *may* be valid HTML but are "never" seen may not
be recognised; e.g. "-- >" as a comment terminator (only "<!-- ... -->" is
recognised as comment).

Only relatively-addressed files with name ending '.HTM' or 'HTML' are read
for link-checking; the presence of <HTML> in the file is not considered.
Relatively-addressed URLs should be in consistent case.
Relatively-addressed directories should end in /.
A WebName starting '!' is ignored.
Comment <!-- ... --> is honoured.
Only the first 255 characters of the contents of <...> are fully examined.

If one file is referred to in more than one way, e.g. ix.htm & ../ix.htm,
it might be read more than once and checked more than once.  Otherwise,
each file is read when first cited, and its detals listed in memory.

In <PARAM ...> (optionally tested), which NAMEs have VALUE=<file> depends
on the APPLET; this tests some likely ones.

Links and anchors within javascript will not be found, if comment is used
to hide them from old (non-<SCRIPT>) browsers.

DosPrompt>cheklinx /d1 filename.htm   does not check link existence, but
does spot certain problems which may be contained within the file.


Error Messages:

(For CHEKLINX, finding an error in a Web page is a success, not an error.)

CHEKLINX can quit with '< ... > too wide for buffer slide?'; that may occur
within a long <SCRIPT> section if unfortunately placed.  Fixes : move the
section; split it; use <!-- ... --> (& try adding > in script comment?).
BufMin has been increased.


Perhaps To Be Done:

* Recognise <script>..</script> ?
* Better cgi-bin ?
* Detect more Java / JavaScript file references ?
* Recognise SRC=, &c, even if not first? OK? - upgrade parsing more?
* Check absolute links to own site - needs /B - done ?
* Future HTML : <h2 id=...> is an anchor.
* Width-first scanning.

2001-12-29 - Comment previously in cheklinx.pas is now merged herein.
2002-08-21 - BufMin now -512, was -256 (date?)
2003-08-05 - BufMin now -8192, was -512; final Enter removed.
2004-08-12 - index.htm used if no other file supplied.
2006-01-22 - New /v0 - gives NO progress reports, just errors (for TRY-AUX).
JRS.