id	summary	reporter	owner	description	type	status	priority	milestone	component	version	resolution	keywords	cc
315	add_search_paths.info is unclear and needs updating	Gary Dixon	Eric Swenson	"The info seg for the add_search_paths command is unclear.  

1) It fails to distinguish between -control_args that position a new SEARCH_PATH within rules of an existing SEARCH_LIST  from -control_args for handling expected error situations.

2) It provide no information about the meaning of keywords given in its ""List of keywords"" section.

3) It does not explain meaning of the -referencing_dir keyword.

I propose the following replacement for this info segment.


{{{
                    add_search_paths.info         09/09/23  1558.3 pdt Sat


:Info: add_search_paths: asp:
2023-09-09  add_search_paths, asp

Syntax as a command:
  asp SEARCH_LIST SEARCH_PATH1 {-position_control_arg} ...
       SEARCH_PATHn {-position_control_arg} {-control_args}


Function:  adds one or more search paths to the specified search list.


Arguments:
SEARCH_LIST
   is the name of the search list to which the new search paths are
   added.
SEARCH_PATH
   specifies a new search path, where SEARCH_PATH is a relative or
   absolute pathname of a directory to be search, or a keyword
   designating such directory.  See ""List of keywords"" and
   ""Notes on search paths"" below for more details.


Control arguments (positioning a search path):
   One of the following may be given after each new SEARCH_PATH
   argument to specify a position within the existing search list for
   the new SEARCH_PATH.  The STR operand is a pathname or keyword as
   given in the existing search list.
-first, -ft
   positions the new search path first in the search list.
-last, -lt
   positions the new search path last in the search list.  (Default)
-after STR, -af STR
   positions the new search path after the search path denoted by STR.
-before STR, -be STR
   positions the new search path before the search path denoted by STR.


Control arguments:
-force, -fc
   causes duplicate pathnames to be replaced in the search list at the
   specified position.
-no_force, -nfc
   causes duplicate pathnames to be ignored.  (Default)
-inhibit_error, -ihe
   suppresses warning messages printed when a pathname is nonexistent
   or is already in the search list.
-no_inhibit_error, -nihe
   causes warning messages to be printed.  (Default)


List of keywords:
   The following keywords are accepted as search paths
   in place of absolute or relative pathnames.
-home_dir, -hd
   The user's home directory.
-process_dir, -pd
   The user's process directory.
-working_dir, -wd
   The users current working directory.


-initiated_segments, -is
   Represents the list of segments already known to the process by
   their reference name(s).  This keyword may only be used for the
   linker search list.
-referencing_dir, -rd
   Represents a directory designated by the program using the
   SEARCH_LIST to locate segments.  See ""Notes on -referencing_dir""
   below.


List of related search facility commands:
   delete_search_paths, dsp
   print_search_path, psp
   set_search_paths, ssp
   where_search_paths, wsp


Notes on search paths:
A SEARCH_PATH can be specified as a quoted string which includes the
[user project] and/or [user name] active function.  Use of such quoted
string delays expansion of the active string until searching actually
begins.  This feature allows creation of search paths that select
segments in or below the project directory or home directory of the
current user.  If the quoted string identifies a directory that does
not exist, the missing directory is skipped; searching for a matching
segment continues with the next rule is the SEARCH_LIST.


For example, a project administrator could specify use of a
project_start_up.ec by users logged in on her project; for details,
type: help process_overseer.gi

This project_start_up.ec could setup various search lists that include
segments tailored for use by that project.  These search lists include
a quoted SEARCH_PATH with "">udd>[user project]>..."" to specify a
directory containing project-related tools, info segments, or
exec_coms.  The [user project] active string would be evaluated only
when a search was actually made for a tool, info segment, or exec_com.


Notes on -referencing_dir:
Each subroutine that wants to locate segments using a search list may
tell search_paths_$get what directory pathname to use if the search
list includes a -referencing_dir search path.  If this directory
pathname is an empty string, the -referencing_dir rule is skipped.


For example, when the linker is called to dynamically link a program to
another subroutine, it uses pathname of the program containing the
unsnapped link as its -referencing_dir.  This allows a modified
program to to call a new (not yet installed) subroutine if the
programmer places that new subroutine (or a symbolic link to that
subroutine) in the directory containing the modified program.

To use the -referencing_dir rule in the linker search list:
   asp linker -referencing_dir -after -initiated_segments

To use the -referencing_dir rule in the info_segments search list:
   asp info_segments -referencing_dir -after -working_dir
}}}
"	defect	closed	major	MR12.9	Documentation	MR12.8	fixed