+-----+
#  This file is created by : 
- edit "$d_bin""Lucas - formulae & augment.sh" to select one of the "skeleton" documents to process
- this file, plus the scripts that it calls, sets the environmental variables
- run $ bash "$d_bin""Lucas - formulae & augment.sh"
- this creates the "augmented" txtDoc, with [Table of Contents, List of Equations, file insertions, etc]

+--+
Normally, you should NOT directly edit txtDocs that have been built from "skeletons".  Instead, edit the files that are inserted.  Otherwise , files can become inconsistent, and work may be lost.

+--+
"/*$" and "/*/*$"

The character sequence "/*$" at the start of a line denotes a [Linux, bash, other] command to be executed at that point when the txtDoc is being processed.  Common examples are :
- insert the date :
			/*$ echo "version= $date_ymdhm, cos - 1 inclusion : $cos_inclusion"  >>"$p_augmented"
- insert the name of the txtDoc that is beiong produced :
			/*$ echo "$p_augmented"   >>"$p_augmented"
- insert text from a file : 
			/*$ cat  >>"$p_augmented"  "$d_Lucas""context/text editor - how to set up.txt" 

Because general commands and special scripts can easily be used, this allows a great deal of [capabilities, flexibilty] to txtDoc processing.  Intermediate variables and processsing, that is not immediately output to the resulting document, may also possible, but as of 24Oct2019 I have not yet implemented that.

double "/*", eg in "/*/*$", denotes de-activated commands.  
	This is done automatically for each pass

As of 23Oct2019, you must manually re-run "$d_bin""Lucas - formulae & augment.sh" on the created file to do iterative file insertions, for example when processing brings in files that also have commands. (... this should be automated at some time...)
This should be automated in the future.

+--+
"/*_endCmd"

The character sequence "/*_endCmd" at the start of a line simply marks the endpoint of the command initiated by "/*$".  It is put in as a convenience to clearly show the inserted portion in the generated txtDoc.

Sometimes commands give a simple one line output (such as timestamps, filenames), or perhaps don't write anything into $p_augmented, in which case "/*_endCmd" is omitted.

To append the "/*_endCmd" line to many new "/*$" lines, use a kwrite regular expression search-replace, such as :
search :		/\*\$(.*)\n
replace : 	/\*\$\1\n/*_endCmd\n
Hopefully, if you are not using kwrite, you will have equivalent regular expression searh-replace (if not change text processors!!).  Emacs would have it, probably vi as well, although I don't use them.

+--+
Table of Contents, list of equations

The script "$d_bin""txtDoc insert indexes.sh" inserts the  : 
			/*_Insert_Table_of_Contents
			/*_Insert_equations
at the point where these appear.  It is automatically run by "$d_bin""Lucas txtDoc augment.sh".

To generate a FULL "Table of Contents" (TOC) [comment, uncomment] the lines below in "$d_bin""txtDoc insert indexes.sh" :
# Default - extract the first 3 levels of headings only
 grep -n  "^\(>>>\)\{1,3\} " "$p_augmented"  |  sed  's/>>>/   /g'  >>"$p_headings_init"
# All headings : "
#grep -n  "^>>>" "$p_augmented"  |  sed  's/>>>/   /g'   >>"$p_headings_init"

You can also edit those lines for variants of the TOC.

+--+
Viewing files while reading

Not all files are inserted in txtDox by the "/*$" command approach.  Instead, one might want to view a file during the process of reading, or the file is an [image, spreadsheet] which cannot be directly incorporated in a txtDoc.  Therefore, a bash line is provided, which can be copy-pasted into a terminal window to show the file.  I have yet to provide default window [size, position] coding, which will be application-specific.

Note that a simple "comment" symbol "/*" is used in these cases.

- view a text file, in this case using my preferred text editor :
			/* kwrite "<filepath>"
- more general form, where readers can pre-define an environmental variable in lieu of using a specific program : 
			/*$  eval '$txtEditor "<filepath>"'

- view an image file, again using a specific image viewer :
			/* eog "<filepath>"
- more general form, where readers can pre-define an environmental variable in lieu of using a specific program : 
			/*$  eval '$imageViewer "<filepath>"'

+--+
More information and practice

24Oct2019 ... for later inclusion here using links rather than inserted text, plus creation of the bash script file ...