update docs

add navigation bar, fix application headers, a few text changes
tjparnell · Aug 22, 2024 · f1d7e47 · f1d7e47
1 parent 03e7653
commit f1d7e47
Show file tree

Hide file tree

Showing 28 changed files with 323 additions and 248 deletions.
diff --git a/docs/AdvancedInstallation.md b/docs/AdvancedInstallation.md
@@ -1,4 +1,8 @@
-# ADVANCED INSTALLATION
+# Bio::ToolBox
+
+|[Home](ReadMe.md)|[Install](AdvancedInstallation.md)|[Libraries](Libraries.md)|[Applications](Applications.md)|[Examples](Examples.md)|[FAQ](FAQ.md)|
+
+## Advanced Installation
 
 This is an advanced installation guide for getting a complete installation. 
 
@@ -20,9 +24,9 @@ accordingly for their system. If that doesn't describe you, skip ahead to the
     is officially recommended. It defaults to installing in `/usr/local` but doesn't 
     have to be; see below. 
 
-        curl -o htslib-1.9.tar.bz2 -L https://github.com/samtools/htslib/releases/download/1.9/htslib-1.9.tar.bz2 
-        tar -xf htslib-1.9.tar.bz2
-        cd htslib-1.9
+        curl -o htslib-1.19.tar.bz2 -L https://github.com/samtools/htslib/releases/download/1.19/htslib-1.19.tar.bz2 
+        tar -xf htslib-1.19.tar.bz2
+        cd htslib-1.19
         make && make install
         cd ..
 
@@ -141,14 +145,18 @@ installed.
 
 - [HTSlib](https://github.com/samtools/htslib)
 
-    Follow the directions within for installation.
-    [Version 1.9](https://github.com/samtools/htslib/releases/download/1.9/htslib-1.9.tar.bz2)
-    is officially recommended by its authors; however, later versions appear to
-    work too and may be preferred. Versions of `htslib` up to 1.20 have been used
-    by this author. By default, it installs into `/usr/local`, or
-    it may be set to another directory (`$HOME` for example) by adding
-    `--prefix=$HOME` option to the `configure` step. This may also be available
-    via OS or other package managers. 
+    Follow the directions within for installation. Version 1.9 is officially
+    recommended by the `Bio::DB::HTS` authors; however, later versions appear to work
+    just fine and should probably be preferred. 
+    [Version 1.19](https://github.com/samtools/htslib/releases/download/1.19/htslib-1.19.tar.bz2)
+    have been used successfully by this author. By default, it installs into
+    `/usr/local`, or it may be set to another directory (`$HOME` for example) by
+    adding `--prefix=$HOME` option to the `configure` step. This may also be
+    available via OS or other package managers. 
+
+    Note that the `htslib` package is also included with the `samtools` and `bcftools`
+    packages and is compiled therein, but is not installed by default (although it
+    could be).
 
 - [libBigWig](https://github.com/dpryan79/libBigWig)
 
@@ -158,7 +166,9 @@ installed.
 
     Note that the Perl module
     [Alien::LibBigWig](https://metacpan.org/pod/Alien::LibBigWig) is available
-    to install this library dependency for you automatically for Bio::DB::Big.
+    to install this library dependency for you automatically for `Bio::DB::Big`.
+    although by default it installs an older version and brings along a lot of
+    extra `Alien` Perl modules, if that concerns you.
 
 
 ## Perl modules

diff --git a/docs/Applications.md b/docs/Applications.md
@@ -1,4 +1,8 @@
-# Included Applications
+# Bio::ToolBox
+
+|[Home](ReadMe.md)|[Install](AdvancedInstallation.md)|[Libraries](Libraries.md)|[Applications](Applications.md)|[Examples](Examples.md)|[FAQ](FAQ.md)|
+
+## Included Applications
 
 There are 22 production-quality script applications included in the package. These
 are listed below, grouped by general function. Also see the 

diff --git a/docs/Examples.md b/docs/Examples.md
@@ -1,4 +1,8 @@
-# Application Examples
+# Bio::ToolBox
+
+|[Home](ReadMe.md)|[Install](AdvancedInstallation.md)|[Libraries](Libraries.md)|[Applications](Applications.md)|[Examples](Examples.md)|[FAQ](FAQ.md)|
+
+## Application Examples
 
 The BioToolBox package comes complete with a suite of high-quality, production-ready 
 applications (Perl scripts) ready for a variety of analyses. A sampling of what 

diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -1,4 +1,8 @@
-# Frequently Asked Questions
+# Bio::ToolBox
+
+|[Home](ReadMe.md)|[Install](AdvancedInstallation.md)|[Libraries](Libraries.md)|[Applications](Applications.md)|[Examples](Examples.md)|[FAQ](FAQ.md)|
+
+## Frequently Asked Questions
 
 These may or may not have actually been asked, but it's a collection of hints that the 
 programmer understands but a casual user might not, as well as rationale.

diff --git a/docs/Libraries.md b/docs/Libraries.md
@@ -1,4 +1,8 @@
-# LIBRARIES
+# Bio::ToolBox
+
+|[Home](ReadMe.md)|[Install](AdvancedInstallation.md)|[Libraries](Libraries.md)|[Applications](Applications.md)|[Examples](Examples.md)|[FAQ](FAQ.md)|
+
+## Libraries
 
 Several library modules are included in this distribution. The following is a brief
 description of the primary user-oriented libraries that are available. Links will 

diff --git a/docs/MacOSNotes.md b/docs/MacOSNotes.md
@@ -1,4 +1,8 @@
-# MacOS Notes
+# Bio::ToolBox
+
+|[Home](ReadMe.md)|[Install](AdvancedInstallation.md)|[Libraries](Libraries.md)|[Applications](Applications.md)|[Examples](Examples.md)|[FAQ](FAQ.md)|
+
+## MacOS Notes
 
 While Macs have a Unix-compatible command-line environment (Darwin), there are a few 
 issues and solutions that I have encountered that may be useful to someone. Some of 
@@ -97,7 +101,8 @@ dependencies, it attempts to compile a small test program and runs the command
 `mktemp --suffix=.c`. While that `--suffix` option is available to versions on Linux
 platforms, it is not available to the version on macOS, thus breaking the detection
 of libCurl. To work around this, we just have to tell it that, yes, we have libCurl.
-Comment out the five lines after `# Create a simple test-program...` and add a new line
+Edit the `Makefile` and comment out the five lines after 
+`# Create a simple test-program...` and add a new line
 
 	HAVE_CURL=YES
 

diff --git a/docs/apps/bam2wig.md b/docs/apps/bam2wig.md
@@ -1,10 +1,12 @@
-# NAME
+# Bio::ToolBox
 
-bam2wig.pl
+|[Home](ReadMe.md)|[Install](AdvancedInstallation.md)|[Libraries](Libraries.md)|[Applications](Applications.md)|[Examples](Examples.md)|[FAQ](FAQ.md)|
+
+## bam2wig.pl
 
 A program to convert Bam alignments into a wig representation file.
 
-# SYNOPSIS
+## SYNOPSIS
 
 bam2wig.pl \[--options...\] &lt;file.bam>
 
@@ -85,11 +87,11 @@ bam2wig.pl --extend --rpm --mean --out file --bw file1.bam file2.bam
      -v --version                  print version information
      -h --help                     show full documentation
 
-# OPTIONS
+## OPTIONS
 
 The command line flags and descriptions:
 
-## Input
+### Input
 
 - --in &lt;filename>
 
@@ -98,7 +100,7 @@ The command line flags and descriptions:
     or simply appended to the command. Bam files will be automatically 
     indexed if necessary.
 
-## Reporting Options
+### Reporting Options
 
 - --start
 
@@ -152,7 +154,7 @@ The command line flags and descriptions:
 
     Legacy option for supporting previous versions of bam2wig. 
 
-## Alignment reporting options
+### Alignment reporting options
 
 - --splice
 
@@ -175,7 +177,7 @@ The command line flags and descriptions:
     Do this when RNA-Seq alignments map to the opposite strand of the 
     coding sequence, depending on the library preparation method. 
 
-## Paired-end alignments
+### Paired-end alignments
 
 - --pe
 
@@ -215,7 +217,7 @@ The command line flags and descriptions:
     a single-end alignment. No test of insert size or proper pair status is 
     made.
 
-## Alignment filtering options:
+### Alignment filtering options:
 
 - --qual &lt;integer>
 
@@ -269,7 +271,7 @@ The command line flags and descriptions:
     when splitting on splices. If an N operation in the CIGAR string exceeds this 
     limit, the alignment is skipped. Default is 0 (no filtering).
 
-## Shift options
+### Shift options
 
 - --shift
 
@@ -331,7 +333,7 @@ The command line flags and descriptions:
     using the output base name. The default is to not write the model 
     shift data.
 
-## Score Options
+### Score Options
 
 - --rpm
 
@@ -389,7 +391,7 @@ The command line flags and descriptions:
     apply the specific normalization factor. For example, 'chrX$' to specify 
     the X chromosome only.
 
-## Wig format
+### Wig format
 
 - --bin &lt;integer>
 
@@ -418,7 +420,7 @@ The command line flags and descriptions:
     When writing bedGraph format, skip (do not write) intervals with a value of 
     zero. Does not apply to fixedStep or variableStep formats.
 
-## Output Options
+### Output Options
 
 - --out &lt;filename>
 
@@ -443,7 +445,7 @@ The command line flags and descriptions:
     Specify whether (or not) the output text file should be compressed with 
     gzip. Disable with `--nogz`. Does not apply to bigWig format.
 
-## General options
+### General options
 
 - --cpu &lt;integer>
 
@@ -470,7 +472,7 @@ The command line flags and descriptions:
 
     Display this POD documentation.
 
-# DESCRIPTION
+## DESCRIPTION
 
 This program will enumerate aligned sequence tags and generate a wig, 
 or optionally BigWig, file. Alignments may be counted and recorded 
@@ -502,7 +504,7 @@ bedGraph format. The wig file may be further converted into a
 compressed, indexed, binary bigWig format, dependent on the 
 availability of the appropriate conversion utilities. 
 
-# RECOMMENDED SETTINGS
+## RECOMMENDED SETTINGS
 
 The type of wig file to generate for your Bam sequencing file can vary 
 depending on your particular experimental application. Here are a few 
@@ -605,7 +607,7 @@ the wig or bigWig file.
         bam2wig --smartcov --strand --rpm --in <bamfile>
         
 
-# TEXT REPRESENTATION OF RECORDING ALIGNMENTS
+## TEXT REPRESENTATION OF RECORDING ALIGNMENTS
 
 To help users visualize how this program records alignments in a wig 
 file, drawn below are 10 alignments, five forward and five reverse. 
@@ -672,7 +674,7 @@ are drawn for visualization purposes only. Values of X represent 10.
 
         ....12224455555555555555555555555555555555555555555443333332211111
 
-# AUTHOR
+## AUTHOR
 
     Timothy J. Parnell, PhD
     Huntsman Cancer Institute

diff --git a/docs/apps/correlate_position_data.md b/docs/apps/correlate_position_data.md
@@ -1,10 +1,12 @@
-# NAME
+# Bio::ToolBox
 
-correlate\_position\_data.pl
+|[Home](ReadMe.md)|[Install](AdvancedInstallation.md)|[Libraries](Libraries.md)|[Applications](Applications.md)|[Examples](Examples.md)|[FAQ](FAQ.md)|
+
+## correlate\_position\_data.pl
 
 A script to calculate correlations between two datasets along the length of a feature.
 
-# SYNOPSIS
+## SYNOPSIS
 
 correlate\_position\_data.pl \[--options\] &lt;filename>
 
@@ -32,11 +34,11 @@ correlate\_position\_data.pl \[--options\] &lt;filename>
     -v --version                     print version and exit
     -h --help                        show extended documentation
 
-# OPTIONS
+## OPTIONS
 
 The command line flags and descriptions:
 
-## Options for data files
+### Options for data files
 
 - --in &lt;filename>
 
@@ -59,7 +61,7 @@ The command line flags and descriptions:
     file), or when using an existing input file with the database indicated 
     in the metadata. 
 
-## Options for data sources
+### Options for data sources
 
 - --ddb &lt;name | filename>
 
@@ -76,7 +78,7 @@ The command line flags and descriptions:
     they may be a BigWig or even Bam file. Both options are required. If 
     not provided, they may be interactively chosen from the database.
 
-## Options for correlating data
+### Options for correlating data
 
 - --pval
 
@@ -130,7 +132,7 @@ The command line flags and descriptions:
     data column in the input file with strand information. The default is 
     no enforcement of strand.
 
-## General options
+### General options
 
 - --gz
 
@@ -144,7 +146,7 @@ The command line flags and descriptions:
 
     Display this POD documentation.
 
-# DESCRIPTION
+## DESCRIPTION
 
 This program will calculate statistics between the positioned scores of
 two different datasets over a window from an annotated feature or
@@ -184,7 +186,7 @@ test data look like the reference data? The window is shifted from -2
 radius to +2 radius relative to the reference point, and the highest 
 correlation is reported along with the shift value that generated it. 
 
-# AUTHOR
+## AUTHOR
 
     Timothy J. Parnell, PhD
     Dept of Oncological Sciences