#] 
#] *********************
#] "$d_Qtest"'7_HowellCoreLib arg[Order, Number] instructions.txt'  
# www.BillHowell.ca  10Jul2022 initial
# view this file in a text editor, with [constant width font, tab = 3 spaces], no line-wrap


#48************************************************48



08********08
Summary 

As a consequence of the complete revamp of [variable, optr] names of all the QNial programs that I have written since 1985(1), it is necessary to also revamp the [order, number] of optr arguments (args) in the optr [definition, usage]s.  

Although it is fairly easy to change symbol names, changes to their arg[Order, Number] are far more problematic.  This is complicated by the use of [infix notation, long expressions that generate the args, the very general nature of array args (ary), etc].  In comments below I frequently use the jargon : 
	pth			= full path of a file 
	pthNdf		= pth with extension .ndf, these are QNial definition files - my [library, program]s
	pthNdfL		= pth that lists all pthNdf of current interest, eg "$d_symArg"'7_HowellCoreLib list.txt' 
	pthOptr		= pth with fname "$dirOut$optrNam"' usage.txt', 
	pthOptrUseL = pth that lists all optrNames of interest, eg "$d_symArg"'8_optrUse list.txt'


Step-by-step instructions below explain the process, but it may help to explain why a "two-step" process is used to :
5.	pthOptr : generate files that list uses of each optrName across all files of interest 
	(called HowellCoreLibs for the initial fs of this work)
7.	pthNdf  : re-sort lines of all optrName lines contents according to each pthNdf where they occurred 

Obviously, it would be easy to go directly to files for each .ndf file containing optrNames of interest.  However, there are two advantages of the "two-step" :
-	pthOptr : these provide a [nice, quick] overview of whether there are any arg[Name, Order] problems 
	Many optrs have NOT been changed recently, so files for those optrNames can be deleted, greatly reducing [visual, planning] clutter and the amount of manual work required later.
-	pthNdf  : Manual changes to an .ndf file in step 8 below is greatly facilitated by [see, edit]ing all lines
	in the .ndf file, with lines for each pthOptrUseL grouped together.  That avoids hopping back & forth between .ndf files where changes to programming code must be made.     


(1)	actually, I can't find any of my old QNial programs - lost with [cassette tape, floppy disks] etc


08********08
Instructions

12Jul2022 My [approach, code] is not yet mature enough to automate many steps together.  Steps 2 and 8 are definitely manual, and too dangerous to automate fully even if you could?

1. build list of .ndf files :  
	list of ALL .ndf files : 
	$ find "$d_Qroot"  -type f  -name "*.ndf"  |  grep  --invert-match  "z_Old"  |  grep  --invert-match  "z_Archive"  |  tr  \\n  \\0  |  xargs -0  -IFILE  grep  "#\] " "FILE"  |  sed "s/#] /\t/"  >>"$d_Qndfs"'0_list of Howells QNial ndf, optr]s.txt"  

2.	list of "core ndf" files : simply take from "QNial setup.ndf" (these are loadded every qnial startup)
	"$d_symArg"'7_HowellCoreLib list.txt'

3. list of optr definitions in an ndf file (eg arrays.ndf) :  
	$ grep '  IS OP  '  "$d_Qndfs"'arrays.ndf'  |  grep  --invert-match  "^#] "  |  grep  --invert-match  "^   "  |  sed  's|^\t||'  |  sed  's|[{]\(.*\)||'  |  sort  >"$d_symArg"'arrays/arrays optrNamArgL.txt'  

4. list optrNames in an ndf file (eg arrays.ndf) excluding '  IS OP ' definitions, etc 
	this will be used for tracking usage of each optr defined in that ndf file
	$ grep '  IS OP  '  "$d_symArg"'arrays/arrays optrNamArgL.txt'  |  sed  's|  IS OP  \(.*\)||'  >"$d_symArg"'arrays/arrays optrNamL.txt'  

5. generate files for every optrName, which show usage in the "core ndf" files. 
	example, uncomment (but comment out all other function invocations) : 
	pthOptrNamL_pthNdfL_argOrderNum_?dout?  "$d_symArg"'arrays/arrays optrNamL.txt'  
			"$d_symArg"'7_HowellCoreLib list.txt'  "$d_symArg"'arrays/'
	$ bash  "$d_bin""fileops.sh"  
	
	"$d_symArg"'pthLibL optrArgOrderNum/arrays.ndf argOrderNum toCheck.txt'

6.	manually cull 'optr usage' files (eg "$d_symArg"'arrays/') to reduce amount of work : 
	a) eliminate files <200 bytes (probably no corrections to make,rule of thumb only)
	b) rapid look at files to see if arg[Order, Number] is a problem for the optr 
		if not a problem - delete file so as not to [distract, consume time]  
	c)	run bash line to screen output list of  'optr usage' files
		$ ls -l  "$d_symArg"'arrays/' 
		copy to file of manual notes of progress (eg "$d_Qtest"'arrays/arrays- develop.txt')
		edit - chop out all but file[size, name] to have record and mark off progress

7. aggregate all "optr usage" details for each  "core ndf file" (library) 
	



8. semi-manually correct each  "core ndf file" (library) in "$d_coreNdfUsage" as necessary 
		because of incorrect arg[Order, Number]
	12Jul2022 actually, I CAN semi-automate :
		mark non-changing lines : will be saved to "ignore line file" used by function
		mark [ambiguous, unknown] lines : will be saved to "ambiguous line file" for closer look 
			(eg spans several lines etc)
		mark lines-to-change : will be [save, duplicate]ed to "change line file" - first as-is, second to edit
		this could be MUCH faster-easier, and provides a record of change, 
			plus a record of lines to ignore, so I don't waste time looking at them!!
	



# $ bash  "$d_bin""fileops.sh"  


# enddoc