:	"@(#)scriba.sh 0.0"
#
#	Created by:	marcog@ctonline.it
#	On:		Thu Oct 30 10:40:14 MET 1997
#	Contents:	scriba, a code documentation tool for Informix 4gl
#
#	This shell script will install several files (and possibly
#	directories) in your hard drive.
#	It is suggested that it be run from an empty subdir, since
#	failing to do so might result in partial file installation
#	and / or disk cluttering.
#	Be aware that its use and that of its contents may have
#	limitations as set forth in the welcome screen and the archive
#	contents itself.
#	Possible switches:
#
#	-n	doesn't check for file presence
#	-q	for (almost) quiet operation
#
#	Files in this archive:
#
#	scriba/build_index
#	scriba/create_man_entries
#	scriba/insert_index
#	scriba/merge_index
#	scriba/merge_man_entries
#	scriba/postprocess
#	scriba/preprocess
#	scriba/readme
#	scriba/rebuild_list
#
#	Here's all the shell utilities usage that might cause problems.
#	Edit appropriately if you are stuck.
#
AWK=${AWK:-awk}

filesize()
{
    ls -l $1 | $AWK '{print $5}'
}

PG=`find /bin /usr/bin /usr/lbin -name pg -print`
if [ -z "$PG" ]
then
    PG=more
fi
#
#	get parms
#
QUIET=false
NOCHECK=false
while [ $# -ne 0 ]
do
    case $1 in
	-n)
	    NOCHECK=true
	    ;;
	-q)
	    QUIET=true
	    ;;
	*)
	    echo Usage: $0 [-c] [-q]
	    exit 1
	    ;;
    esac
    shift
done
#
#  display welcome text - it may not fit on the screen, so we need a paginator
#
tput clear
$PG <<'EOF-entry'

	This shell script will install scriba, a code documentation tool for Informix 4gl
	If you are not running it from a suitable directory
	hit <DEL> now to abort installation

EOF-entry
#
# more does not wait for a key while displaying last screen
#
if [ $PG = more ]
then
    read a
    unset a
fi
#
# create directories as needed
#
mkdir -p scriba
#
#  begin build_index
#
if [ -f scriba/build_index -a $NOCHECK != true ]
then
    echo $0: scriba/build_index already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/build_index \(1520 characters\)
    fi
    cat >scriba/build_index <<'EOF-build_index'
#! /usr/bin/awk -f
#	build_index - scans 4gl doc. files, and builds a linked index
#
#	Marco Greco (marcog@ctonline.it), Catania, Italy
#
#	Initial release: Sep 97
#	Current release: Oct 97
#
#				NOTICE
# 	Permission to use, copy, modify and redistribute this software and
#	its documentation is hereby granted without fee provided that
#
#	- all copies of the software and related documentation contain this
#	  notice and authorship information, UNMODIFIED
#
#	- no fee is charged for the physical act of redistributing this
#	  software or modified copies thereof
# 
#	THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
#	EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
#	WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
#
#	IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
#	INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
#	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED
#	OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING
#	OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# 
#	ALL RISKS CONNECTED TO THE USE OF THIS SOFTWARE OR IMPOSSIBILITY 
#	THEREOF LIE SOLELY ON YOU.
#	USE OF THIS SOFTWARE CONSTITUES AGREEMENT WITH THE ABOVE TERMS 
#	AND CONDITIONS.
#

#set record separator
BEGIN		{ FS="\"" }

#scan for function names
/^<P><A NAME/	{
		    print "<LI><A HREF=\"" \
			substr(FILENAME, match(FILENAME, "[^/]+$")) \
			"#" $2 "\">" $2 "</A></LI>"
		}
EOF-build_index
    if [ `filesize scriba/build_index` -ne 1520 ]
    then
        echo $0: scriba/build_index extracted with wrong size
    fi
    chmod u+x scriba/build_index
fi
#
#  end build_index
#
#  begin create_man_entries
#
if [ -f scriba/create_man_entries -a $NOCHECK != true ]
then
    echo $0: scriba/create_man_entries already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/create_man_entries \(6877 characters\)
    fi
    cat >scriba/create_man_entries <<'EOF-create_man_entries'
#! /usr/bin/awk -f
#	create_man_entries - an automated 4gl source code documenter
#
#	Marco Greco (marcog@ctonline.it), Catania, Italy
#
#	Initial release: Sep 97
#	Current release: Oct 97
#
#				NOTICE
# 	Permission to use, copy, modify and redistribute this software and
#	its documentation is hereby granted without fee provided that
#
#	- all copies of the software and related documentation contain this
#	  notice and authorship information, UNMODIFIED
#
#	- no fee is charged for the physical act of redistributing this
#	  software or modified copies thereof
# 
#	THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
#	EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
#	WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
#
#	IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
#	INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
#	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED
#	OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING
#	OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# 
#	ALL RISKS CONNECTED TO THE USE OF THIS SOFTWARE OR IMPOSSIBILITY 
#	THEREOF LIE SOLELY ON YOU.
#	USE OF THIS SOFTWARE CONSTITUES AGREEMENT WITH THE ABOVE TERMS 
#	AND CONDITIONS.
#

BEGIN		{

# token separator
		    FS="[ \t]+|[ \t]*[(),][ \t]*"

# get list of functions that have already been documented
		    if (already_documented!="")
			while ((getline < already_documented)>0)
			    function_list[$0]=""

# set some handy variables
		    in_function="no"
		    in_comment=0
		    commentcounter=0
		    restartcomment=0
		}

# if already within brace comment, don't want opening braces
in_comment	{ in_comment=($0 !~ "{") }

# if not within braces, we want a brace as first token, and no more
!in_comment	{ in_comment=($0 ~ "^[ \t]*{[^{]*$") }

# save comments just preceeding function definition
(in_function=="no") && (in_comment || $1 ~ "(#|--).*") \
		{

# drop comment tokens
	 	    sub("(#|--|{)[ \t]*", "")
		    in_comment=in_comment && ! sub("}[ \t]*$", "")

# drop decorative comments
		    sub("^[=_\\-+*# \t]+", "")
		    if (restartcomment)
			commentcounter=0
		    if (length($0) || commentcounter)
			comment[++commentcounter]=$0
		    restartcomment=0
		    next
		}

# outside useful comments, flag comment buffering should start anew
		{ restartcomment=1 }

# strip all other comments
/#.*/ || /--.*/ || /[{}]/ \
		{
		    sub("(#|--).*", "") 
		    gsub("{[^{}]*}", "")
		    sub("^.*}", "")
		    sub("{.*", "")
		    if (!length($0)) next
		}

# empty line, skip
!length($0)	{ next }

# downshift to simplify life
		{
		    oldrec=$0
		    $0=tolower($0)
		}

# here starts a function
(/^function/||/^report/)  && (already_documented=="" || ! ($2 in function_list)) \
		{
		    in_function="yes"

# save name in documented list
		    function_list[$2]=""

# save param list for later
		    delete currargs
		    for (i=3; i<NF; i++)
			currargs[$i]=i

# init counters & save string for later
		    retcount=0
		    defcount=1
		    definitions[1]=oldrec

# open paragraph, create local anchor, print function name as header, and draw a rule
		    print "<P><A NAME=\"" $2 "\"><H3>" $2 "</A><HR></H3>"

# subsequent entries as a two col table
		    print "<TABLE CELLSPACING=5>"

# source filename
		    print "<TR><TD VALIGN=\"TOP\"><B>file</B></TD>"
		    print "<TD WIDTH=100%>" substr(FILENAME, \
			match(FILENAME, "[^/]+$")) "</TD></TR>"

# start declaration section
		    print "<TR><TD VALIGN=\"TOP\"><B>declaration</B></TD>"
		    next
		}

# not within function - skip
(in_function=="no")	{ next }

# drop leading blanks
		{ gsub("^[ \t]+", "") }

# skip returning clauses
/returning/	{ next }

# save return statements
/return/ 	{
		    sub(".*return", "")
		    if (length($0))
		    {
			retcount++
			returns[retcount]=$0
		    }
		}

# end function - output all the saved data
/end function/||/end report/ \
		{
		    in_function="no"

# drop lone defines & empty strings
		    while (defcount &&
			   (tolower(definitions[defcount]) ~ "define[ \t]*$" \
			    || !length(definitions[defcount])))
			defcount--

# drop a possible comma from last definition statement
		    sub(",$", "", definitions[defcount])

# print all define statements
		    print "<TD WIDTH=100%><PRE>"
		    for (i=1; i<=defcount; i++)
			print definitions[i]
	  	    print "</PRE></TD></TR>"

# and the returns statements if any
		    print "<TR><TD VALIGN=\"TOP\"><B>returns</B></TD>"
		    print "<TD WIDTH=100%>"
		    if (!retcount) print "nothing"
		    else
			for (i=1; i<=retcount; i++)
			    print returns[i] "<BR>"
		    print "</TD></TR>"

# create purpose, ...
		    print "<TR><TD VALIGN=\"TOP\"><B>purpose</B></TD>"
		    print "<TD WIDTH=100%>"
		    while (commentcounter && !length(comment[commentcounter]))
			commentcounter--
		    for (i=1; i<=commentcounter; i++)
			print comment[i]
		    print "</TD></TR>"

# ...example, ...
		    print "<TR><TD VALIGN=\"TOP\"><B>example</B></TD>"
		    print "<TD WIDTH=100%>none</TD></TR>"

# ...and notes rows
		    print "<TR><TD VALIGN=\"TOP\"><B>notes</B></TD>"
		    print "<TD WIDTH=100%>none</TD></TR>"

# close table - we're done
		    print "</TABLE></P>"

# leave an empty line for clarity
		    print ""

# reinit comment variables & restart over
		    commentcounter=0
		    restartcomment=0
		    next
		}

# here starts a definition section 
/define/	{
		    in_function="define"
		    sub("define", "")
		    varfound=0
		}

# not within definition - skip
in_function=="yes" \
		{ next }

# see if we end with a comma
		{
		    terminate_define=!/,[ \t]*$/

# remove trailing comma & leading & trailing blanks (simplifies life)
		    sub("^[ \t]*", "")
		    sub(",?[ \t]*$", "")
		}

# see if record starts or ends
/record/	{
		    if (in_function=="define")
			in_function="record"
		    else
			in_function="define"
		    sub("(end)?[ \t]*record", "")
		}

# if empty line or all reserved words or within record, save for later
(in_function=="record" && parameterfound) || !length($0) \
		{ definitions[++defcount]=oldrec }

# scan to see if we spot a parameter - if yes, save line
in_function=="define" \
		{
		    parameterfound=0
		    varfound+=split($0, items, "[ \t]*,[ \t]*|[ \t]+")
		    for (i in items)
			if (items[i]!="" && items[i] in currargs)
			{
			    parameterfound=1
			    definitions[++defcount]=oldrec
			    break
			}
		}

# definition section ends if line ends with no comma, outside record, 
# the line is not empty and we have actually defined something
in_function=="define" && length(oldrec) && varfound && terminate_define \
		{ in_function="yes" }

# on exit output updated documented function list
END		{
		    if (already_documented!="")
			for (i in function_list)
			    print i > already_documented
		}
EOF-create_man_entries
    if [ `filesize scriba/create_man_entries` -ne 6877 ]
    then
        echo $0: scriba/create_man_entries extracted with wrong size
    fi
    chmod u+x scriba/create_man_entries
fi
#
#  end create_man_entries
#
#  begin insert_index
#
if [ -f scriba/insert_index -a $NOCHECK != true ]
then
    echo $0: scriba/insert_index already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/insert_index \(2141 characters\)
    fi
    cat >scriba/insert_index <<'EOF-insert_index'
#! /usr/bin/awk -f
#	insert_index - inserts TOC file into 4gl documentation
#
#	Marco Greco (marcog@ctonline.it), Catania, Italy
#
#	Initial release: Sep 97
#	Current release: Oct 97
#
#				NOTICE
# 	Permission to use, copy, modify and redistribute this software and
#	its documentation is hereby granted without fee provided that
#
#	- all copies of the software and related documentation contain this
#	  notice and authorship information, UNMODIFIED
#
#	- no fee is charged for the physical act of redistributing this
#	  software or modified copies thereof
# 
#	THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
#	EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
#	WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
#
#	IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
#	INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
#	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED
#	OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING
#	OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# 
#	ALL RISKS CONNECTED TO THE USE OF THIS SOFTWARE OR IMPOSSIBILITY 
#	THEREOF LIE SOLELY ON YOU.
#	USE OF THIS SOFTWARE CONSTITUES AGREEMENT WITH THE ABOVE TERMS 
#	AND CONDITIONS.
#
#check parms & get TOC file name
BEGIN		{
		    if (ARGC!=3)
		    {
			print "bad # of arguments"
			exit
		    }
		    indexfile=ARGV[2]
		    ARGV[2]=""
		    in_index=0
		}

#just printed the index - do a plain copy
(indexfile=="")	{
		    print
		    next
		}

#skip all index entries
/^<LI><A HREF/ || /^<UL>/ || /^<\/UL>/ \
		{
		    in_index=1
		    next
		}

#skip blank lines within and after index
(in_index && !length($0)) \
		{ next }

#got first entry - merge index in
/^<P><A NAME/	{

#get source file basename
		    n=substr(FILENAME, match(FILENAME, "[^/]+$"))

#print index
		    print "<UL>"
		    while ((getline a<indexfile)>0)
		    {

#making local handles actually local
			sub(n, "", a)
			print a
		    }
		    print "</UL>"
		    print ""
		    indexfile=""
		}

		{
		    print
		    in_index=0
		}
EOF-insert_index
    if [ `filesize scriba/insert_index` -ne 2141 ]
    then
        echo $0: scriba/insert_index extracted with wrong size
    fi
    chmod u+x scriba/insert_index
fi
#
#  end insert_index
#
#  begin merge_index
#
if [ -f scriba/merge_index -a $NOCHECK != true ]
then
    echo $0: scriba/merge_index already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/merge_index \(2554 characters\)
    fi
    cat >scriba/merge_index <<'EOF-merge_index'
#! /usr/bin/awk -f
#	merge_index - merges index file into main TOC file
#
#	Marco Greco (marcog@ctonline.it), Catania, Italy
#
#	Initial release: Sep 97
#	Current release: Oct 97
#
#				NOTICE
# 	Permission to use, copy, modify and redistribute this software and
#	its documentation is hereby granted without fee provided that
#
#	- all copies of the software and related documentation contain this
#	  notice and authorship information, UNMODIFIED
#
#	- no fee is charged for the physical act of redistributing this
#	  software or modified copies thereof
# 
#	THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
#	EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
#	WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
#
#	IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
#	INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
#	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED
#	OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING
#	OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# 
#	ALL RISKS CONNECTED TO THE USE OF THIS SOFTWARE OR IMPOSSIBILITY 
#	THEREOF LIE SOLELY ON YOU.
#	USE OF THIS SOFTWARE CONSTITUES AGREEMENT WITH THE ABOVE TERMS 
#	AND CONDITIONS.
#

BEGIN		{

# verify args
		    if (ARGC!=3)
		    {
			print "bad # of arguments"
			exit
		    }

# set record separator
		    FS="\"#"

# get TOC file name
		    indexfile=ARGV[2]
		    ARGV[2]=""

# get HTML file name
		    if ((getline firstTOCrow< indexfile)<0)
		    {
			exit
		    }
		    htmlfile=firstTOCrow
		    sub("[^\"]*\"", "", htmlfile)
		    sub("#.*", "", htmlfile)
		    in_index=0
		}

#index already printed - do a plain copy
(indexfile=="") {
		    print
		    next
		}

#skip all index entries up to the </UL>
(in_index)	{
		    in_index=($0!="</UL>")
		    if (!in_index) indexfile=""
		    next
		}

# found the entry!
($2==htmlfile) && (indexfile!="")
		{
		    in_index=1

# if a link with no local anchor, print it anyway
		    if (!match($0, "#"))
		    {
			print
			print "<UL>"
		    }

#print index
		    print firstTOCrow
		    while ((getline a<indexfile)>0)
			print a
		    print "</UL>"
		    firstTOCrow=""
		    next
		}

#print everithing else as usual
		{
		    print
		}

#if in the end we haven't output anything, now's a good time to do it
END		{
		    if (firstTOCrow!="")
		    {
			print "<UL>"
			print firstTOCrow
			while ((getline a<indexfile)>0)
			    print a
			print "</UL>"
		    }
		}
EOF-merge_index
    if [ `filesize scriba/merge_index` -ne 2554 ]
    then
        echo $0: scriba/merge_index extracted with wrong size
    fi
    chmod u+x scriba/merge_index
fi
#
#  end merge_index
#
#  begin merge_man_entries
#
if [ -f scriba/merge_man_entries -a $NOCHECK != true ]
then
    echo $0: scriba/merge_man_entries already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/merge_man_entries \(2161 characters\)
    fi
    cat >scriba/merge_man_entries <<'EOF-merge_man_entries'
#! /bin/sh
#	merge_man_entries - merges 4gl doc. files, sorting by function name
#
#	Marco Greco (marcog@ctonline.it), Catania, Italy
#
#	Initial release: Sep 97
#	Current release: Oct 97
#
#				NOTICE
# 	Permission to use, copy, modify and redistribute this software and
#	its documentation is hereby granted without fee provided that
#
#	- all copies of the software and related documentation contain this
#	  notice and authorship information, UNMODIFIED
#
#	- no fee is charged for the physical act of redistributing this
#	  software or modified copies thereof
# 
#	THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
#	EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
#	WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
#
#	IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
#	INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
#	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED
#	OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING
#	OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# 
#	ALL RISKS CONNECTED TO THE USE OF THIS SOFTWARE OR IMPOSSIBILITY 
#	THEREOF LIE SOLELY ON YOU.
#	USE OF THIS SOFTWARE CONSTITUES AGREEMENT WITH THE ABOVE TERMS 
#	AND CONDITIONS.
#

awk '
#set record separator
BEGIN		{
		    FS="\""
		    linecount=0
		    preamble=0
		    infunction=0
		}

#scan for function names
/^<P><A NAME/	{
		    currfunct=$2;
		    if (preamble==1) preamble=2
		    linecount=0
		    infunction=1
		}

#print line with sort key
(infunction)	{
		    print "11" currfunct sprintf("%07d", linecount) " " $0
		    linecount++
		    infunction=length($0)
		    next
		}

# print the file header
(preamble!=2)	{
		    print "00" sprintf("%07d", linecount) " " $0
		    preamble=1
		    linecount++
		    next
		}

# print the trailer
		{
		    print "zz" sprintf("%07d", linecount) " " $0
		    linecount++
		}
' $* |
#
# it is assumend that you are smart enough not to feed repeatedly the same
# functions to this script. the -u it's there just in case :-)
#
sort -u -t " " +0 |
sed -e 's/^[^ ]\+ //'
EOF-merge_man_entries
    if [ `filesize scriba/merge_man_entries` -ne 2161 ]
    then
        echo $0: scriba/merge_man_entries extracted with wrong size
    fi
    chmod u+x scriba/merge_man_entries
fi
#
#  end merge_man_entries
#
#  begin postprocess
#
if [ -f scriba/postprocess -a $NOCHECK != true ]
then
    echo $0: scriba/postprocess already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/postprocess \(2075 characters\)
    fi
    cat >scriba/postprocess <<'EOF-postprocess'
#! /bin/sh
#	postprocess - script that automates function entries insertion in docs.
#
#	Marco Greco (marcog@ctonline.it), Catania, Italy
#
#	Initial release: Sep 97
#	Current release: Oct 97
#
#				NOTICE
# 	Permission to use, copy, modify and redistribute this software and
#	its documentation is hereby granted without fee provided that
#
#	- all copies of the software and related documentation contain this
#	  notice and authorship information, UNMODIFIED
#
#	- no fee is charged for the physical act of redistributing this
#	  software or modified copies thereof
# 
#	THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
#	EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
#	WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
#
#	IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
#	INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
#	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED
#	OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING
#	OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# 
#	ALL RISKS CONNECTED TO THE USE OF THIS SOFTWARE OR IMPOSSIBILITY 
#	THEREOF LIE SOLELY ON YOU.
#	USE OF THIS SOFTWARE CONSTITUES AGREEMENT WITH THE ABOVE TERMS 
#	AND CONDITIONS.
#

# a couple of temp files
tmp=/tmp/4gld$$
tmp_toc=/tmp/4glt$$

# identify html TOC file to update, if any
case $1 in
-i)
    main_toc=$2
    shift
    shift
    ;;
esac

# identify documentation file
source=$1
shift

# need at least one file to insert!
if [ $# -eq 0 ]
then
    echo $0: needs at least a file to be included
    exit
fi

# merge man entries in main docs file, plus sort entries
merge_man_entries $source $* > $tmp
mv $tmp $source

# rebuild contents index
build_index $source > $tmp_toc

# insert index on top of main docs file
insert_index $source $tmp_toc > $tmp
mv $tmp $source

# if we have a master TOC file, update that too
if [ -n "$main_toc" ]
then
    merge_index $main_toc $tmp_toc > $tmp
    mv $tmp $main_toc
fi
rm $tmp_toc
EOF-postprocess
    if [ `filesize scriba/postprocess` -ne 2075 ]
    then
        echo $0: scriba/postprocess extracted with wrong size
    fi
    chmod u+x scriba/postprocess
fi
#
#  end postprocess
#
#  begin preprocess
#
if [ -f scriba/preprocess -a $NOCHECK != true ]
then
    echo $0: scriba/preprocess already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/preprocess \(1800 characters\)
    fi
    cat >scriba/preprocess <<'EOF-preprocess'
#! /bin/sh
#	preprocess - a sample create_man_entries front-end
#
#	Marco Greco (marcog@ctonline.it), Catania, Italy
#
#	Initial release: Sep 97
#	Current release: Oct 97
#
#				NOTICE
# 	Permission to use, copy, modify and redistribute this software and
#	its documentation is hereby granted without fee provided that
#
#	- all copies of the software and related documentation contain this
#	  notice and authorship information, UNMODIFIED
#
#	- no fee is charged for the physical act of redistributing this
#	  software or modified copies thereof
# 
#	THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
#	EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
#	WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
#
#	IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
#	INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
#	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED
#	OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING
#	OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# 
#	ALL RISKS CONNECTED TO THE USE OF THIS SOFTWARE OR IMPOSSIBILITY 
#	THEREOF LIE SOLELY ON YOU.
#	USE OF THIS SOFTWARE CONSTITUES AGREEMENT WITH THE ABOVE TERMS 
#	AND CONDITIONS.
#

# a couple of useful vars
od=
dfl=

# identify documented file list and output directory, if any
while [ $# -gt 0 ]
do
    case $1 in
    -o)
	shift
   	od=$1/
	shift
	;;
    -l)
	shift
	dfl="-v already_documented=$1"
	shift
	;;
    *)
	break
	;;
    esac
done

# need at least one file to process!
if [ $# -eq 0 ]
then
    echo $0: needs at least a file to process
    exit
fi

# process each file
for f in $*
do
    h=`basename $f .4gl`
    awk -f create_man_entries $dfl $f > ${od}$h.html
done
EOF-preprocess
    if [ `filesize scriba/preprocess` -ne 1800 ]
    then
        echo $0: scriba/preprocess extracted with wrong size
    fi
    chmod u+x scriba/preprocess
fi
#
#  end preprocess
#
#  begin readme
#
if [ -f scriba/readme -a $NOCHECK != true ]
then
    echo $0: scriba/readme already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/readme \(6568 characters\)
    fi
    cat >scriba/readme <<'EOF-readme'
Scriba documentation						29 Oct 1997

This tool was written on a September wednesday morning while ill & at home.
Being completely incapable of staying away from my notebook, I decided that
if I wasn't going to get any work done, at least I could write some of the
4glworks reference manual I should have put in my little web site long ago.

After having documented the third function, I realized that that was going
to be a hell of a job, and that I needed a small tool to extract and format
info straight from the source code, much like the javadoc tool for java.

Once written, it gathered and formatted info from all of the 4glworks source
files in a handful of seconds. It was then that I realized that the ability
to spot descriptive code out of everybody's coding style habits coupled with
a few collateral tools catering for automated documentation update would have
made my documentation extractor interesting to a wider audience.

The contents of this archive are the results of my efforts - I tried to put
the accent on the ability to automatically update documentation whenever the
code changes. The documentation extractor can keep track of the functions that
have already been documented, and extracts only info from those that haven't.
Other tools can subsequently be used to merge HTML documentation files,
preserving possible headers and footers, and sorting the resulting file by
function name; generate a TOC from this sorted HTML file, and insert (or update)
the TOC itself back in the documentation or in a main TOC file.

The core of the tool, create_man_entries, scans 4gl source files extracting
FUNCTION and REPORT declarations, complete with parameter DEFINEs, as well as
comments (purged from decorative lines - those full of #,=,-_+,*) found right
before the declarations themselves and all the RETURNed values, the idea
behind this being that such comments will give a description of the function
purposes, while the RETURNed values will prove useful when manually polishing
the documentation.
The tool output is, of course, already formatted and provides a pointer to the
source file, the already mentioned "declaration", "purpose" and "returns"
sections, as well as a "notes" and "example" section, which will have to be
filled in by hand.
I have tested it against a variety of coding habits, using code mostly coming
from the IIUG software archives, and except for one author (who simply doesn't
put comments on top of functions or reports) it has always extracted the correct
code and comments.

Creating or updating documentation is a three step process, which requires
collecting functions data out of the source files, hand polishing the resulting
text (no HTML formatting necessary), and finally integrating the polished
documentation in place. Sample shell scripts have been provided for both the
first and the last step.

Enough hype. Here's the scripts reference. Have fun.

Marco Greco <marcog@ctonline.it>


NAME
	create_man_entries

SYNOPSIS
	awk -f create_man_entries [-v already_documented=doclist] src.4gl >
		dest.html

ARGUMENTS
	doclist		is the name of the file containing the list of the
			functions that have already been documented
	src.4gl		is a list of 4gl source files
	dest.html	is the name of the html output file

DESCRIPTION
	Creates documentation from 4gl source code, excluding all functions
	contained in doclist, if specified. doclist is updated on exit.
	Currently, the documentation of all the files specified in the command
	line is grouped in one output file. Needs a shell wrapper (see later)
	for a one to one output, which in turn is not exactly efficient when
	it comes to updating the doclist file.
	


NAME
	merge_man_entries

SYNOPSIS
	merge_man_entries src.html > dest.hmtl

ARGUMENTS
	src.html	is a list of html files that should be merged
	dest.html	is the name of the html output file

DESCRIPTION
	Merges documenation coming from different files, ordering the text by
	function name. One of the source files can have a header and a footer
	(this is to allow the update of an existing, complete documentation
	file) - these are used as header and footer of the output file.


NAME
	create_index

SYNOPSIS
	awk -f create_index source.html > dest.idx

ARGUMENTS
	source.html	is the documentation file from which the TOC is to be
			created
	dest.idx	is the output TOC file

DESCRIPTION
	creates a TOC out of a documentation file.


NAME
	insert_index

SYNOPSIS
	awk -f insert_index source.html source.idx > dest.html

ARGUMENTS
	source.html	is the html file containing the documentation
	source.idx	is the file containig the TOC
	dest.html	is the output documentation file

DESCRIPTION
	Inserts or updates a TOC within the documentation file used to generate
	it. TOC is inserted in front of the first function documentation.


NAME
	merge_index

SYNOPSIS
	awk -f merge_index idx.html source.idx > dest.html

ARGUMENTS
	idx.html	is the html file containg the master TOC
	source.idx	is the file containig the TOC
	dest.html	is the output master TOC file

DESCRIPTION
	Inserts or updates a TOC file generated with create_index in a master
	TOC file. Update takes place where the previous version of the TOC
	is found, while new TOCs need a little hint: if merge_index spots a
	link to the documentation file the TOC refers to, the TOC is inserted
	following that link, otherwise at the end of the main TOC file.


NAME
	rebuild_list

SYNOPSIS
	awk -f rebuild_list src.html > doclist

ARGUMENTS
	src.html	is a list of html files containing the documentation
	doclist		is the output file contained the list of the documented
			functions

DESCRIPTION
	Rebuilds the list of already documented functions out of the
	documentation.


NAME
	preprocess

SYNOPSIS
	preprocess [-l doclist][-o outputdir] src.4gl

ARGUMENTS
	doclist		is the name of the file containing the list of the
			functions that have already been documented
	outputdir	is the name of a directory that will contain the output
			html files
	src.4gl		is a list of 4gl source files

DESCRIPTION
	A sample frontend for create_man_entries, that creates a src.html
	file for each src.4gl file it processes.


NAME
	postprocess

SYNOPSIS
	postprocess [-i idx.html] main.html src.html

ARGUMENTS
	idx.html	is the main html TOC file
	main.html	is the documentation file to be updated
	src.html	is a list of html containing function documentation

DESCRIPTION
	A sample shell script that can be used to update function documentation
	within a preexisting file. A front_end to merge_man_entries, 
	create_index, insert_index, merge_index.
EOF-readme
    if [ `filesize scriba/readme` -ne 6568 ]
    then
        echo $0: scriba/readme extracted with wrong size
    fi
fi
#
#  end readme
#
#  begin rebuild_list
#
if [ -f scriba/rebuild_list -a $NOCHECK != true ]
then
    echo $0: scriba/rebuild_list already exists
else
    if [ $QUIET != true ]
    then
        echo scriba/rebuild_list \(1425 characters\)
    fi
    cat >scriba/rebuild_list <<'EOF-rebuild_list'
#! /usr/bin/awk -f
#	rebuild_list - builds a list of documented files from the documentation
#
#	Marco Greco (marcog@ctonline.it), Catania, Italy
#
#	Initial release: Sep 97
#	Current release: Oct 97
#
#				NOTICE
# 	Permission to use, copy, modify and redistribute this software and
#	its documentation is hereby granted without fee provided that
#
#	- all copies of the software and related documentation contain this
#	  notice and authorship information, UNMODIFIED
#
#	- no fee is charged for the physical act of redistributing this
#	  software or modified copies thereof
# 
#	THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
#	EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
#	WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
#
#	IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
#	INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
#	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED
#	OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING
#	OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# 
#	ALL RISKS CONNECTED TO THE USE OF THIS SOFTWARE OR IMPOSSIBILITY 
#	THEREOF LIE SOLELY ON YOU.
#	USE OF THIS SOFTWARE CONSTITUES AGREEMENT WITH THE ABOVE TERMS 
#	AND CONDITIONS.
#
#set record separator
BEGIN		{ FS="\"" }

#scan for function names
/^<P><A NAME/	{ print $2 }
EOF-rebuild_list
    if [ `filesize scriba/rebuild_list` -ne 1425 ]
    then
        echo $0: scriba/rebuild_list extracted with wrong size
    fi
    chmod u+x scriba/rebuild_list
fi
#
#  end rebuild_list
#
$PG  scriba/readme