############################################################################
#  Simulate "include" tag functionality for ASCII (non-sgml) files.
#
# The following commands allow users to source ascii files and have their
# content placed within a publisher document. At the user's request,
# individual, or all included ascii files can be updated, replacing the
# version displayed in pubedit with the current content of the original ascii
# file.
#
# The implementation is based on a user defined tag (UDT) called
# <include-ascii>. The tag is based on the <link> tag. There are several
# commands for creating and updating the contents of an <include-ascii> tag.
#
# SETUP
	# 1. Place this command file in an appropriate place, accessable to
	     # everyone who will need it.
	# 2. Place the appropriate "source" command in the appropriate
	     # pubrc file(s):
			# source path/include-cmd-file-name
# 
		# To make this accessable to everyone for every document
		# place the source command in .../publisher/lib/Pubrc
# 
		# To make it accessible to everyone for specific document types
		# only, place the source command in each of the document
		# template pubrc files:
			# .../publisher/templates/book.tmpl/pubrc
# 
		# To make it accessible on a user by user basis for all
		# documents used by that user, place the source command in
		# the user's home .pubrc file:
			# .../$HOME/.pubrc
# 
		# To make it accessible on a usr by user basis for specific
		# document instances only, place the source command in the
		# document instance's pubrc file:
			# .../docname/pubrc
# 	
	# 3. All documents which use this command file MUST have a user
	     # defined tag called "include-ascii". This is best done in each
	     # document type template prior to sourcing this command file. The
	     # make_include_ascii_udt command attempts to do this automatically,
	     # but in some cases the user may have to do this himself. To create
	     # the udt in the command subwindow type:
# 	
		# dft include-ascii link
#
# USAGE:
	# The command insert_included_ascii is used to insert a new
	# <include-ascii> tag pair. The command can be given from the command
	# subwindow or from a menu option.
#
	# The update_included_ascii command replaces, in pubedit, the content
	# of the <include-ascii> tag with the content of the original ascii
	# file. No attempt is made to compare dates or to diff the contents.
	# This command can be executed from the command subwindow or by
	# executing the link (control-m1) command while the mouse in within the
	# <include-ascii> tag pair.
#
	# The update_all_included_ascii command will update all occurences of
	# <include-ascii> in the document with the update_included_ascii
	# command. This command can be given from the command subwindow or
	# from a menu option.
#
# Several other aliases are defined which should prove useful in other situations
# as well.
#
# Some rules apply which should be written into the menu help and which
# these commands should test for.
# 	
	# 1. include-ascii tags should not be nested.
	# 2. edits made in pubedit to an included ascii file will not be saved
	#    to the original ascii file, nor will the be saved in pubedit if
	#    an update_included_ascii command is given.
#
#
# TODO:
	# need to replace the print and preview commands on the menus with
	# one that will first do a update_all_included_ascii command before
	# it does the print or preview.
# 
	# need to make the update_included_ascii command smarter so that it
	# only does an update when the original ascii file is newer than the
	# version displayed in pubedit.
# 
	# possibly add a readonly option to included ascii text.
#
	# add command processing to the directory window so you can double
	# click on a file name and if it is ascii, its contents will be
	# inserted into a (automatically created) include-ascii tag pair.
#
############################################################################

############## VARIABLES ##################################################
#
# Initialize some variables
$dollar='$?'
$fname=""
$err="0"

############## ALIASES ##################################################
#
# MARK TAG CONTENTS
#
alias mark_tag_contents {
        clm all;
	# find begin tag
        find -p -b;
        #mark -noselect -noinvert;
	mark begin
	# find end tag
        find -noselect -p;
        mark end;
}


#
# DELETE TAG CONTENTS
#
alias delete_tag_contents {
	mark_tag_contents;
	if (substr($selection,1,length($tagname)) != "<$tagname>")
		{
        	delete_mark;
		}
	else
		{
		clm
		}
}

#
# POSITION THE CARET AFTER NAMED TAG
#
alias posn_after_tag {
	# go to top
	caret  first,last+1;
	# find given tag, positioning after the tag
	find -t /<$1>/;
	clm all;
}

#
# MAKE INCLUDE ASCII UDT, IF NECESSARY
#
alias make_include_ascii_udt {
	write -ok -styleonly -ascii $docname/$docname.udts
	$isdefined=`grep include-ascii $docname/$docname.udts;echo $dollar`
	if ($isdefined != 0)
		{
		dft include-ascii link
		ms -global include-ascii Underline="no" Print="yes"
		}
	}

#
# UPDATE INCLUDED ASCII
#
alias update_included_ascii {
	# find the beginning of this block
	find -b -t -q -noselect /<include-ascii>/
	caret current,+1

	# see if the named file still exists. If not, give an error message
	# and do nothing. Otherwise, delete the contents of the tag and
	# re-read the original ascii file into its place.
	$fname="$1"
	$err=`test -f $fname; echo $dollar`
	if (X$err != X0)
		{
		exec message "Unable to find $fname. Preserving current contents (if any)."
		}
	else
		{
		delete_tag_contents
		exec read -untaggedascii $fname
		}
	}
 
#
# UPDATE ALL INCLUDED ASCII FILES
#
alias update_all_included_ascii {
	# starting at the top of the file, scan for all <include-ascii>
	# tags and perform the update_included_ascii command on each.
	set wrapscan=off
	caret 1,1
	$done="no"
	while (x$done == xno)
		{
		find -t -q -noselect /<include-ascii>/
		if ($status == 0)
			{
			# the link command will execute the publisher
			# commands in the link tag, which happens to be an
			# update_included_ascii [filename] command.
			link caret
			}
		else
			{
			$done="yes"
			}
		}
	}

#
# INSERT A NEW INCLUDE-ASCII TAG
#
alias insert_included_ascii {
	# prompt for a file name. If it exists, locally modify the 
	# <include-ascii> tag to execute the proper update_included_ascii
	# command on the appropriate file, when the user issues the "link"
	# command. Then execute the link command for the first time to
	# initially load the ascii file.
	readvar -prompt "Enter ascii file name (and path, if necessary):" fname
	if ($status == 0 && x$fname != x)
		{
		it include-ascii
		if ($status == 0)
			{
			exec ms -local Command="exec update_included_ascii $fname"
			link caret
			}
		}
	}


############## MENUS ##################################################
#
# Set up some menus to give the user a better interface than the command
# line. The menu items need some help text written for them.
#
madd -menu . "Includes" -title "Include Files"
madd .Includes. "include an ascii file" -cmd {insert_included_ascii}
madd .Includes. "update all included ascii files" -cmd {update_all_included_ascii}

############## KEYMAPS ##################################################
#
# The following have been commented out and should be redefined for your
# site to avoid collisions with existing keymappings.
#
map edit control-i insert_included_ascii
map edit control-u {if ($tagname == "include-ascii") {link caret}}
map edit shift-control-u update_all_included_ascii

############## COMMANDS ##################################################
#
# Execute the following commands when the document is opened.
make_include_ascii_udt 		# define the include-ascii udt if necessary


