# /media/bill/PROJECTS/bin/txtDoc instructions.txt
# www.BillHowell.ca  16Dec2019 collect notes on how to use txtDoc [system, programs]




#**********************************
Table of Contents 

10:    basic text files
15:       Example "basic text files" listing :
49:       Special "text [formats, commands]" are used in the basic files :
74:       Old manner of generating Table of Contents :
95:    skeleton files
97:       Skeleton files define :
105:       #  Example  "$d_bin""Lucas txtDoc augment.sh" :
115:       Special "text [formats, commands]" for the skeleton files :
128:    # $ bash "/media/bill/PROJECTS/bin/standard header.sh"


$ p_work="$d_bin""txtDoc notes.txt"
All headings : 
$ grep -n  "^>>>"  "$p_work"  |  sed  's/>>>/   /g'
Only Heading 1 :  
$ grep -n  "^>>> " "$p_work"  |  sed  's/>>>/   /g'
Only Headings [1,2] :  
$ grep -n  "^\(>>>\)\{1,2\} "  "$p_work"  |  sed  's/>>>/   /g'


#**********************************
>>> basic text files

Basic text files are "alternative chunks" of coherent text that will substitute into an overall txtDoc.

Note the sub-directories for alternative derivations. The text files directly in "math Lucas/" have no [variants, alternates], whereas text files in the subdirectories do have different content.

How to decide which text is spun off into a "basic text file", and which are kept in the "skeleton file" (see the next section) is a bit fuzzy.  Often it turns out that text can be re-used throughout a set of documents, so there is a HUGE advantage from saving repeating text as a "basic text file", and coding for it's insertion everywhere it is used.  That way, routine updates to all skeleton files will all have [consistent, corrected] text.

The use of basic text files also makes it much easier to incorporate it into totally [new, different] txtDocs which were not even anticipated at the time of the "basic text files" creation.


>>>>>> Example "basic text files" listing :
"/media/bill/PROJECTS/Lucas - Universal Force/math Lucas/" : 
$ find  "$d_Lucas""math Lucas/"  -maxdepth 1  -name "*"  |  sed 's#/media/bill/PROJECTS/Lucas - Universal Force/math Lucas/##' 
04_13 work.txt
04_14 work.txt
04_15 work.txt
04_16 work.txt
04_19 work.txt
04_21 work.txt
04_23 work.txt
04_24 work.txt
04_27 work.txt
04_28a work.txt
04_29a work.txt
04_30 work.txt
04_38 work.txt
04_39 work.txt
04_41 work.txt
04_42 work.txt
04_44 work.txt
cos - 1 noo, iterative, non-feedback
cos - 1 yes, iterative, non-feedback
d-dt Rpcs_b*sin_a work.txt
dimension checks
Lucas math, verifications full listing 160613.txt
Lucas math, verifications summary listing 07Jan2016 11h59m11s.txt
Lucas math, WorkDoc.txt
relativistic factor, intermediate symbols.txt
relativistic factor, restrictive conditions.txt
verifications by class of results.txt
z_Archive
z_Old


>>>>>> Special "text [formats, commands]" are used in the basic files :
+-----+
   # symTrans_lineType : special characters at beginning of lines :
   # NOTE : these symbols are "persistent" until changed by a different symTrans_lineType (applies to next use of operators!!)
   '/*'	comment only - no translation or extraction of symbols
   '/$'	applies 'tranList Lucas.txt'		to a string 
   '/%'	applies 'tranList HFLN.txt'      to a string 
+-----+
Table of Contents - number of ">>>" defines nesting level :
   /*********************
   >>>[>>>[>>>[>>>]]] 
+-----+
/*_Insert_Table_of_Contents
/*_Insert_equations
+-----+
mark an equation for later extraction :
   (mathH)  ∫[∂(Aθpc),0.to.Aθpc(POIo(t),t=0): sin(Aθpc(POIo(t),t))]  								= {1 -    cos(Aθpc(POIo(t),t=0)}
   (endMath)
+-----+
/*$ echo "version= $date_ymdhm"  >>"$p_augmented"
This file is : 
/*$ echo "$p_augmented"   >>"$p_augmented"



>>>>>> Old manner of generating Table of Contents :
Table of Contents generated by : 
$ d_work="/media/bill/SWAPPER/Lucas - Universal Force/"
$ d_work="/media/bill/RaspPi_ext4_32Gb/Lucas - Universal Force/"
$ d_work="/home/bill/Lucas - Universal Force/"
$ f_work="Howell - Background math for Lucas Universal Force, Chapter 4.txt"
All headings : 
$ grep -n  "^>>>" "$d_work""$f_work"  |  sed  's/>>>/   /g'
Only Heading 1 :  
$ grep -n  "^>>> " "$d_work""$f_work"  |  sed  's/>>>/   /g'
Only Headings [1,2] :  
$ grep -n  "^\(>>>\)\{1,2\} "  "$d_work""$f_work"  |  sed  's/>>>/   /g'


To retrieve the result for a [symbol, expression] : 
>> doesn't work for multi-line expressions - but at least it gives the line #
>> must escape some characters - notably "[,]" below in the example
$ grep -n  "^(math" "$d_work""$f_work"  |  grep '∂\[∂(t): sin(Aθpc(POIo(t),t))\]'


#**********************************
>>> skeleton files

Skeleton files have their own "native text", plus they will be augmented by "alternative chunks" of coherent text from basic text files (defined in previous section).

>>>>>> Skeleton files define :
- the overall structure of the txtDoc being generated
- text commands to be executed at specific points in the text, eg for : 
   - text insertions from a file
   - date insertions
   - 1st four characters of line "\*$ " followed by a [bash, linux] command or other executable program

>>>>>> #  Example  "$d_bin""Lucas txtDoc augment.sh" :
$ find  "$d_Lucas"  -maxdepth 1  -type f  -name "*skeleton*"  |  sed 's#/media/bill/PROJECTS/Lucas - Universal Force/##' 
math skeleton nomenclature.txt
math skeleton Lucas 4-32-37 yes-no cos - 1.txt
math skeleton Howell.txt
math skeleton Lucas.txt
questions skeleton.txt
math skeleton Barnes 4-32-37.txt


>>>>>> Special "text [formats, commands]" for the skeleton files :
+-----+
/*$ cat  >>"$p_augmented"  "$d_Lucas""context/text editor - how to set up.txt" 
/*_endCmd
+-----+
/*++++++++++++++++++++++++++++++++++++++
/*add_eqn  Problem_or_challenge  
   04_02
   Faradays_Law 
+-----+


#**********************************
>>> # $ bash "/media/bill/PROJECTS/bin/standard header.sh"
# Until I properly setup bash with default directories, manually setup as below

# MUST DO! :  see "$d_bin""standard header.sh" for command-line exports of variables : 
#		d_meda, d_bin, d_images, d_Lucas
source  "$d_bin""standard header.sh"


#**********************************
>>> 
#  Example  "$d_bin""Lucas txtDoc augment.sh" :

setup ...
# txtDoc scripts : not just for the Lucas project, these are generally useful ...

source  "$d_bin""txtDoc cmd.sh"
# This includes augmenting a text file with text file inclusions, but can go far beyond that.
# originally for "formulae extract.sh" and the Lucas project

# do NOT run this script directly - set up a calling script that sets the environmental variables
# example - Lucas project, see "$d_bin""Lucas - formulae & augment.sh"


source  "$d_bin""txtDoc insert indexes.sh"


source  "$d_bin""txtDoc extract formulae.sh"
# do NOT run this script directly - set up a calling file
extract_formulae() - pull a list of formulae from a txtDoc into a new file


# $ bash "$d_bin""Lucas txtDoc augment.sh"
# for project "Lucas - Universal Force, chapter 4"
define bash variables [f_inn, d_augment, cos_inclusion, f_augmented] for each case below
this produces various versions of txtDocs, adjusting content insertions as required :
  txtDoc_augment()
  mathL_[with, no]_cos_minus_one()
  4_32_to_37_[with, no]_cos_minus_one()
  mathH()
  nomenclature()
"txtDoc extract formulae.sh" can do all of the above at once, or only selected functions

















# enddoc