#
# help.tcl --
#
# Tcl help command. (see TclX manual)
# 
#------------------------------------------------------------------------------
# Copyright 1992-1999 Karl Lehenbauer and Mark Diekhans.
#
# Permission to use, copy, modify, and distribute this software and its
# documentation for any purpose and without fee is hereby granted, provided
# that the above copyright notice appear in all copies.  Karl Lehenbauer and
# Mark Diekhans make no representations about the suitability of this
# software for any purpose.  It is provided "as is" without express or
# implied warranty.
#------------------------------------------------------------------------------
# The help facility is based on a hierarchical tree of subjects (directories)
# and help pages (files).  There is a virtual root to this tree. The root
# being the merger of all "help" directories found along the $auto_path
# variable.
#------------------------------------------------------------------------------
# $Id: help.tcl,v 1.2 2004/11/23 05:54:15 hobbs Exp $
#------------------------------------------------------------------------------
#

#@package: TclX-help help helpcd helppwd apropos

namespace eval ::tclx {
    namespace export help helpcd helppwd apropos
}

namespace eval ::tclx::help {
    variable curSubject "/"
}

#------------------------------------------------------------------------------
# Help command.

proc ::tclx::help {{what {}}} {
    variable ::tclx::help::lineCnt 0

    # Special case "help help", so we can get it at any level.

    if {($what == "help") || ($what == "?")} {
        tclx::help::HelpOnHelp
        return
    }

    set pathList [tclx::help::ConvertPath $what]
    if {[file isfile [lindex $pathList 0]]} {
        tclx::help::DisplayPage [lindex $pathList 0]
        return
    }

    tclx::help::ListSubject $what $pathList subjects pages
    set relativeDir [tclx::help::RelativePath [lindex $pathList 0]]

    if {[llength $subjects] != 0} {
        tclx::help::Display "\nSubjects available in $relativeDir:"
        tclx::help::DisplayColumns $subjects
    }
    if {[llength $pages] != 0} {
        tclx::help::Display "\nHelp pages available in $relativeDir:"
        tclx::help::DisplayColumns $pages
    }
}


#------------------------------------------------------------------------------
# helpcd command.  The name of the new current directory is assembled from the
# current directory and the argument.

proc ::tclx::helpcd {{dir /}} {
    variable ::tclx::help::curSubject

    set pathName [lindex [tclx::help::ConvertPath $dir] 0]

    if {![file isdirectory $pathName]} {
        error "\"$dir\" is not a subject" [list TCLXHELP NOTSUBJECT $dir]
    }

    set ::tclx::help::curSubject [tclx::help::RelativePath $pathName]
    return
}

#------------------------------------------------------------------------------
# Helpcd main.

proc ::tclx::helppwd {} {
    variable ::tclx::help::curSubject
    echo "Current help subject: $::tclx::help::curSubject"
}

#------------------------------------------------------------------------------
# apropos command.  This search the 

proc ::tclx::apropos {regexp} {
    variable ::tclx::help::lineCnt 0
    variable ::tclx::help::curSubject

    set ch [scancontext create]
    scanmatch -nocase $ch $regexp {
        set path [lindex $matchInfo(line) 0]
        set desc [lrange $matchInfo(line) 1 end]
        if {![tclx::help::Display [format "%s - %s" $path $desc]]} {
            set stop 1
            return
	}
    }
    set stop 0
    foreach dir [tclx::help::RootDirs] {
        foreach brief [glob -nocomplain $dir/*.brf] {
            set briefFH [open $brief]
            try_eval {
                scanfile $ch $briefFH
            } {} {
                close $briefFH
            }
            if {$stop} break
        }
        if {$stop} break
    }
    scancontext delete $ch
}

##
## Private Helper Routines
##

#----------------------------------------------------------------------
# Return a list of help root directories.

proc ::tclx::help::RootDirs {} {
    global auto_path
    set roots {}
    foreach dir $auto_path {
	if {[file isdirectory $dir/help]} {
	    lappend roots $dir/help
	}
    }
    return $roots
}

#--------------------------------------------------------------------------
# Take a path name which might have "." and ".." elements and flatten them
# out.  Also removes trailing and adjacent "/", unless its the only
# character.

proc ::tclx::help::FlattenPath pathName {
    set newPath {}
    foreach element [split $pathName /] {
	if {"$element" == "." || [lempty $element]} continue

	if {"$element" == ".."} {
	    if {[llength [join $newPath /]] == 0} {
		error "Help: name goes above subject directory root" {} \
		    [list TCLXHELP NAMEABOVEROOT $pathName]
	    }
	    lvarpop newPath [expr [llength $newPath]-1]
	    continue
	}
	lappend newPath $element
    }
    set newPath [join $newPath /]

    # Take care of the case where we started with something line "/" or "/."

    if {("$newPath" == "") && [string match "/*" $pathName]} {
	set newPath "/"
    }

    return $newPath
}

#--------------------------------------------------------------------------
# Given a pathName relative to the virtual help root, convert it to a list
# of real file paths.  A list is returned because the path could be "/",
# returning a list of all roots. The list is returned in the same order of
# the auto_path variable. If path does not start with a "/", it is take as
# relative to the current help subject.  Note: The root directory part of
# the name is not flattened.  This lets other commands pick out the part
# relative to the one of the root directories.

proc ::tclx::help::ConvertPath pathName {
    variable curSubject

    if {![string match "/*" $pathName]} {
	if {[cequal $curSubject "/"]} {
	    set pathName "/$pathName"
	} else {
	    set pathName "$curSubject/$pathName"
	}
    }
    set pathName [FlattenPath $pathName]

    # If the virtual root is specified, return a list of directories.

    if {$pathName == "/"} {
	return [RootDirs]
    }

    # Not the virtual root find the first match.

    foreach dir [RootDirs] {
	if {[file readable $dir/$pathName]} {
	    return [list $dir/$pathName]
	}
    }

    # Not found, try to find a file matching only the file tail,
    # for example if --> <helpDir>/tcl/control/if.

    set fileTail [file tail $pathName]
    foreach dir [RootDirs] {
	set fileName [exec find $dir -name $fileTail | head -1]
	if {$fileName != {}} {
	    return [list $fileName]
	}
    }

    error "\"$pathName\" does not exist" {} \
	[list TCLXHELP NOEXIST $pathName]
}

#--------------------------------------------------------------------------
# Return the virtual root relative name of the file given its absolute
# path.  The root part of the path should not have been flattened, as we
# would not be able to match it.

proc ::tclx::help::RelativePath pathName {
    foreach dir [RootDirs] {
	if {[csubstr $pathName 0 [clength $dir]] == $dir} {
	    set name [csubstr $pathName [clength $dir] end]
	    if {$name == ""} {set name /}
	    return $name
	}
    }
    if {![info exists found]} {
	error "problem translating \"$pathName\"" {} [list TCLXHELP INTERROR]
    }
}

#--------------------------------------------------------------------------
# Given a list of path names to subjects generated by ConvertPath, return
# the contents of the subjects.  Two lists are returned, subjects under
# that subject and a list of pages under the subject.  Both lists are
# returned sorted.  This merges all the roots into a virtual root.
# pathName is the string that was passed to ConvertPath and is used for
# error reporting.  *.brk files are not returned.

proc ::tclx::help::ListSubject {pathName pathList subjectsVar pagesVar} {
    upvar $subjectsVar subjects $pagesVar pages

    set subjects {}
    set pages {}
    set foundDir 0
    foreach dir $pathList {
	if {![file isdirectory $dir] || [cequal [file tail $dir] CVS]} continue
	set foundDir 1
	foreach file [glob -nocomplain $dir/*] {
	    if {[lsearch {.brf .orig .diff .rej} [file extension $file]] \
		    >= 0} continue
	    if [file isdirectory $file] {
		lappend subjects [file tail $file]/
	    } else {
		lappend pages [file tail $file]
	    }
	}
    }
    if {!$foundDir} {
	if {[cequal $pathName /]} {
	    global auto_path
	    error "no \"help\" directories found on auto_path ($auto_path)" {} \
		[list TCLXHELP NOHELPDIRS]
	} else {
	    error "\"$pathName\" is not a subject" {} \
		[list TCLXHELP NOTSUBJECT $pathName]
	}
    }
    set subjects [lsort $subjects]
    set pages [lsort $pages]
    return {}
}

#--------------------------------------------------------------------------
# Display a line of output, pausing waiting for input before displaying if
# the screen size has been reached.  Return 1 if output is to continue,
# return 0 if no more should be outputed, indicated by input other than
# return.
#

proc ::tclx::help::Display line {
    variable lineCnt
    if {$lineCnt >= 23} {
	set lineCnt 0
	puts -nonewline stdout ":"
	flush stdout
	gets stdin response
	if {![lempty $response]} {
	    return 0}
    }
    puts stdout $line
    incr lineCnt
}

#--------------------------------------------------------------------------
# Display a help page (file).

proc ::tclx::help::DisplayPage filePath {

    set inFH [open $filePath r]
    try_eval {
	while {[gets $inFH fileBuf] >= 0} {
	    if {![Display $fileBuf]} {
		break
	    }
	}
    } {} {
	close $inFH
    }
}

#--------------------------------------------------------------------------
# Display a list of file names in a column format. This use columns of 14 
# characters 3 blanks.

proc ::tclx::help::DisplayColumns {nameList} {
    set count 0
    set outLine ""
    foreach name $nameList {
	if {$count == 0} {
	    append outLine "   "
	}
	append outLine $name
	if {[incr count] < 4} {
	    set padLen [expr 17-[clength $name]]
	    if {$padLen < 3} {
		set padLen 3}
	    append outLine [replicate " " $padLen]
	} else {
	    if {![Display $outLine]} {
		return}
	    set outLine ""
	    set count 0
	}
    }
    if {$count != 0} {
	Display [string trimright $outLine]}
    return
}


#--------------------------------------------------------------------------
# Display help on help, the first occurance of a help page called "help" in
# the help root.

proc ::tclx::help::HelpOnHelp {} {
    set helpPage [lindex [ConvertPath /help] 0]
    if {[lempty $helpPage]} {
	error "No help page on help found" {} \
	    [list TCLXHELP NOHELPPAGE]
    }
    DisplayPage $helpPage
}