!code_source [tos]

# language independent macros
!include macros.ui
# version numbers (generated)
!include version.ui
# switches
!include header.ui
# language macros
!include lang.ui
# hyphenation patterns
!include hyphen.ui

!raw [stg] @help "Help page"

# ---------------------------------------------
# The title of this documentation depends on
# the destination format
# ---------------------------------------------
!ifdest [stg,amg]
!docinfo [title] The hypertext of
!else
!ifdest [win,wh4,hh,hah]
!docinfo [title] The Windows help of
!else
!ifdest [rtf]
!docinfo [title] The book of
!else
!docinfo [title] The guide of
!endif
!endif
!endif
!docinfo [program] (!REFLINK)
!docinfo [author] H. Weets, C. Wempe
!docinfo [programimage] (!IMAGES)reflink

!macro PROGRAM (!REFLINK)

!table_alignment left

# ------------------------------------------------------
# Set the subject for the ST-Guide
# ------------------------------------------------------
!ifdest [stg,amg]
!begin_raw
@subject "Documentation/ST-Guide"
@options "+z -t4 +g +i"
@extern HypView "hypview.hyp/Main"
@extern HCP "hcp.hyp/Main"
@extern RefLink "reflink.hyp/Main"
@extern STool "stool.hyp/Main"
@extern STOOL "stool.hyp/Main"
@extern MAN2STG "man2stg.hyp/Main"
@extern Remarker "Remarker.hyp/Main"
@extern STG-FAQ "stg-faq.hyp/Main"
!end_raw
!endif
!docinfo [stgdatabase] RefLink Documentation

# ------------------------------------------------------------------------------
# the Document structure
# ------------------------------------------------------------------------------

!begin_document

!html_keywords HypView
!html_keywords ST-Guide
!html_keywords Atari
!html_keywords TOS
!html_keywords RefLink

!raw [tex] \sloppy

# create title page + table of contents
!maketitle
!tableofcontents !depth 2
!toc_title The reference-file linker RefLink

!raw [stg] @xref "ST-Guide.HYP/Main" "ST-Guide Documentation"
!raw [stg] @xref "HCP.HYP/Main" "HCP Documentation"
!raw [stg] @xref "stool.hyp/Main" "STool Documentation"

!begin_node General

This small program mainly serves for linking together several REF-files
generated by HCP into a kind of library.

This library helps ST-Guide find  catchwords that have been defined  in
hypertext files other than the one currently displayed.

As a default the file specified in the environment-variable 'REF'  will
be used as the library. If this variable does not exist, and no library
file was  specified in  the  command line  either,  then a  file  named
'(!file [ALL.REF])' in the current directory will be used.

!end_node # General

!include legal.ui

!begin_node RefLink calls
The calling syntax is as follows:

 (!REFLINK) [(!link [-a] [Command -a])] [library] module or (!nl)
 (!REFLINK) (!link [-m] [Command -m]) [library] module or (!nl)
 (!REFLINK) (!link [-d] [Command -d]) [library] module1 [module2 ...] or (!nl)
 (!REFLINK) (!link [-e] [Command -e]) [library] module1 [module2 ...] or (!nl)
 (!REFLINK) (!link [-f] [Command -f]) [library ...] or (!nl)
 (!REFLINK) (!link [-l] [Command -l]) [library ...]

The 'reflink' part  of the  call can  be omitted  from the  REFLINK.TTP
command line; it is only needed for calls from external shells etc.

(!B)Note:(!b) While working,  RefLink writes the  modified library file  before
deleting the original. You have to ensure that there is enough room  on
the drive or partition for  this (i.e. a little  more than the size  of
the existing  ALL.REF file),  otherwise it  will be  truncated  without
warning!

!begin_node Command -a: Add
!alias Command -a
!index -a
!index Add

(!REFLINK) [-a] [Library] module

The module will be added to  the library. If it already exists,  then
the old version will be deleted  and the new one adopted. The  module
can equally well be a library.

If the module is not a REF-file,  then an attempt will be made  first
to  find  the  REF-file  associated  with  the  specified  file:  For
parameter @{"HCP" LINK "HCP.HYP/Main"}.HYP a file named HCP.REF will be searched for and  used
if it exists. This way it  is possible to pass HYP-files directly  to
RefLink.

If the module is not a REF-file  and no associated file can be  found
for it, one will be generated from it in the following manner: TEST.C
will be turned into TEST.REF with
File-name test.c
Node-name test.c
Following this, the file generated in  this way will be added to  the
library.

As one can see from the syntax statement, this 'add' command will  be
used as  a  default  if  none has  been  specified.  That  means,  in
particular, that RefLink can be installed as an application for *.REF
and following this  REF files  can be added  to the  library just  by
double-clicking on them.

!end_node

!begin_node Command -m: Move
!alias Command -m
!index -m
!index Move

(!REFLINK) -m [library] module

As (!link [-a] [Command -a]), except that the module will be deleted after incorporation  in
the library, i.e. a 'move' operation.

!end_node

!begin_node Command -d: Delete
!alias Command -d
!index -d
!index Delete

(!REFLINK) -d [Library] module1 [module2 ...]

The specified modules will be deleted from the library.

!end_node

!begin_node Command -e: Extract
!alias Command -e
!index -e
!index Extract

(!REFLINK) -e [Library] module1 [module2 ...]

The specified  modules will  be extracted  from the  library, i.e.  a
REF-file will be produced  for each module.  The modules will  remain
preserved in the library.

!end_node

!begin_node Command -f: Files
!alias Command -f
!index -f
!index Files

(!REFLINK) -f [Library ...]

This shows the names  of all the modules  contained in the  specified
library/libraries.

!end_node

!begin_node Command -l: List
!alias Command -l
!index -l
!index List

(!REFLINK) -l [Library ...]

This lists the  contents of  all modules contained  in the  specified
library/libraries.

!end_node

!end_node # RefLink calls

!include ref.ui
!include thanks.ui

!begin_node* Help page

This text  describes  the operation  and  usage of  the  reference-file
linker utility 'RefLink'.

!begin_preformatted
Criticisms and suggestions to:
            Holger Weets
            Tangastr. 45
            D-26121 Oldenburg
            Germany
 
            E-mail: Holger Weets @ OL (Mausnet)

Donations:  Bank 24
            Kto.: 1776764
            BLZ.: 380 707 24
!end_preformatted

Alternatively UK users can get support locally:
Refer to the file (!file [SUPPORT.TXT]) in the distribution.

!end_node

!end_document
