example: using otl to insert a new line into a batch of documents
====

In this exercise, we are interested in adding a new line containing a new link to all of the index.html pages in a "tree" of web pages. The link should be inserted at a specific location in each web page, directly after the </a> in a line that looks like:

<p class="top"><a href="../../index.html">home</a></p>

The additional text we want to insert is:
	
<a class="reallytop" href="./problems.xhtml">newlink</a>

But we want to insert it so that the path is adjusted depending on the depth of the index.html
	- if --descend is on for substitution using "substitute", then, if item being substituted in refers to a local path, descend automatically adjusts path prefix with "../" as needed


The solution
----

In this case, we are interested in recognizing a particular line and then substituting in the middle of the line. Using otlsub with a custom substitution pattern is probably easiest:
	
Looking for: <p class="top"><a href="../../index.html">home</a></p>

Replace with: <p class="top"><a href="../../index.html">home</a><br /><a href="../../problems.xhtml">problems?</a></p>
	

SOLUTION: 

1. use otlsub and define ~/.otlsub with substitution of interest:

<p class="top><a href="[\./]*index\.html">home</a>	||<p class="top"><a href="../../index.html">home</a><br /><a href="../../problems.xhtml">problems?</a></p>||

- note that 
	1. a TAB is used to separate the item being searched for from the replacement string
	2. || is used to delimit the replacement string

2. execute otlsub:
	otlsub --rb --descend --debug index.html
	
This command looks for index.html in the current directory and in every subdirectory of the current directory. Note that:
	1. the --descend flag tells otlsub to look in all subdirectories for index.*html
	2. index.*html is in single quotes to prevent bash globbing it for the directory we execute otlsub in
	3. the --rb flag tells otlsub to REPLACE and BACKUP: otlsub first creates a copy of the file it is processing (with suffix .otlbak) and then overwrites the file with the new processed version of the file
	4. since --nolinkadjust isn't specified, otlsub will try and adjust links to local files based on descent into the directory structure by adding additional "../" strings as needed to the start of filename

	
