Add documentation for building with libsais

MANUAL

@@ -132,12 +132,45 @@ will issue a series of commands that will: 1. download zstd and zlib 2.
 compile them as static libraries 3. link the resulting libraries to the
 compiled Bowtie 2 binaries
 
+Building with SRA support
+
 As of version 2.3.5 bowtie2 now supports aligning SRA reads. Prepackaged
 builds will include a package that supports SRA. If you're building
 bowtie2 from source please make sure that the Java runtime is available
 on your system. You can then proceed with the build by running
 make sra-deps && make USE_SRA=1.
 
+Building with libsais support
+
+As of version 2.5.3 bowtie2 supports building indexes using the SAIS
+algorithm provided by libsais. SAIS is a state-of-the-art suffix array
+construction algorithm that will bring-forth a significant speed-up to
+the overall index building process. There is, however, the downside of a
+significant increase in memory usage compared to the persistent
+blockwise algorithm that bowtie2-build uses by default. When using SAIS
+small indexes can be built for inputs up to 2GB. The bowtie2-build
+wrapper will help determine the appropriate index type for uncompressed
+and gzipped inputs.
+
+To build bowtie2-build with libsais first make sure that the libsais
+submodule is available. This can be done in one of the following ways: *
+first time cloning bowtie2 --
+git clone --recursive https://github.com/BenLangmead/bowtie2.git *
+existing checkout of bowtie2 --
+git submodule init && git submodule update
+
+Issue the following command line to build libsais: * with OpenMP support
+-- [g]make libsais USE_SAIS_OPENMP=1 * without OpenMP support --
+[g]make libsais USE_SAIS=1
+
+The choice of using OpenMP will determine whether or not the algorithm
+runs multithreaded. The [-p/--threads] argument to bowtie2-build will be
+ignored when libsais is compiled without OpenMP support.
+
+Finally, building the build executable: * with OpenMP support --
+[g]make bowtie2-build-s USE_SAIS_OPENMP=1 * without OpenMP support --
+[g]make bowtie2-build-s USE_SAIS=1
+
 Adding to PATH
 
 By adding your new Bowtie 2 directory to your PATH environment variable,
@@ -775,7 +808,7 @@ alignment to be considered valid, and x is the read length.
 
 Usage
 
-    bowtie2 [options]* -x <bt2-idx> {-1 <m1> -2 <m2> | -U <r> | --interleaved <i> | --sra-acc <acc> | -b <bam>} -S [<sam>]
+    bowtie2 [options]* -x <bt2-idx> {-1 <m1> -2 <m2> | -U <r> | --interleaved <i> | --sra-acc <acc> | b <bam>} -S [<sam>]
 
 Main arguments
 
@@ -882,16 +915,15 @@ When -r is set, the result is as if --ignore-quals is also set.
 
     -F k:<int>,i:<int>
 
-Reads are substrings (k-mers) extracted from a FASTA file.
-Specifically, for every reference sequence in the FASTA file, Bowtie 2
-aligns the k-mers at offsets 1, 1+i, 1+2i, ... until reaching the end of
-the reference. Each k-mer is aligned as a separate read. Quality values
-are set to all Is (40 on Phred scale). Each k-mer (read) is given a name
+Reads are substrings (k-mers) extracted from a FASTA file. Specifically,
+for every reference sequence in the FASTA file, Bowtie 2 aligns the
+k-mers at offsets 1, 1+i, 1+2i, ... until reaching the end of the
+reference. Each k-mer is aligned as a separate read. Quality values are
+set to all Is (40 on Phred scale). Each k-mer (read) is given a name
 like <sequence>_<offset>, where <sequence> is the name of the FASTA
 sequence it was drawn from and <offset> is its 0-based offset of origin
 with respect to the sequence. Only single k-mers, i.e. unpaired reads,
 can be aligned in this way.
-
     -c
 
 The read sequences are given on command line. I.e. <m1>, <m2> and

MANUAL.markdown

@@ -139,11 +139,40 @@ a series of commands that will:
   2. compile them as static libraries
   3. link the resulting libraries to the compiled Bowtie 2 binaries
 
+### Building with SRA support ###
+
 As of version 2.3.5 bowtie2 now supports aligning SRA reads. Prepackaged
 builds will include a package that supports SRA. If you're building bowtie2
 from source please make sure that the Java runtime is available on your system.
 You can then proceed with the build by running `make sra-deps && make USE_SRA=1`.
 
+### Building with libsais support ###
+
+As of version 2.5.3 `bowtie2` supports building indexes using the SAIS algorithm
+provided by [libsais]. SAIS is a state-of-the-art suffix array construction algorithm
+that will bring-forth a significant speed-up to the overall index building process.
+There is, however, the downside of a significant increase in memory usage compared
+to the persistent blockwise algorithm that `bowtie2-build` uses by default. When using
+SAIS small indexes can be built for inputs up to 2GB. The `bowtie2-build` wrapper
+will help determine the appropriate index type for uncompressed and gzipped inputs.
+
+To build `bowtie2-build` with [libsais] first make sure that the libsais submodule
+is available. This can be done in one of the following ways:
+* first time cloning bowtie2 -- `git clone --recursive https://github.com/BenLangmead/bowtie2.git`
+* existing checkout of bowtie2 -- `git submodule init && git submodule update`
+
+Issue the following command line to build libsais:
+* with OpenMP support -- `[g]make libsais USE_SAIS_OPENMP=1`
+* without OpenMP support -- `[g]make libsais USE_SAIS=1`
+
+The choice of using OpenMP will determine whether or not the algorithm
+runs multithreaded. The [`-p/--threads`] argument to `bowtie2-build` will
+be ignored when libsais is compiled without OpenMP support.
+
+Finally, building the build executable:
+* with OpenMP support -- `[g]make bowtie2-build-s USE_SAIS_OPENMP=1`
+* without OpenMP support -- `[g]make bowtie2-build-s USE_SAIS=1`
+
 Adding to PATH
 --------------
 
@@ -2965,3 +2994,4 @@ warnings due to the case insensitive nature of markdown URLs -->
 [using a pre-built index]:                            #using-a-pre-built-index
 [valid alignment]:                                    #valid-alignments-meet-or-exceed-the-minimum-score-threshold
 [yields a larger memory footprint]:                   #fm-index-memory-footprint
+[libsais]:                                            https://github.com/IlyaGrebnov/libsais

doc/manual.html

@@ -11,8 +11,11 @@
     div.columns{display: flex; gap: min(4vw, 1.5em);}
     div.column{flex: auto; overflow-x: auto;}
     div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
-    ul.task-list{list-style: none;}
+    /* The extra [class] is a hack that increases specificity enough to
+       override a similar rule in reveal.js */
+    ul.task-list[class]{list-style: none;}
     ul.task-list li input[type="checkbox"] {
+      font-size: inherit;
       width: 0.8em;
       margin: 0 0.8em 0.2em -1.6em;
       vertical-align: middle;
@@ -43,7 +46,14 @@ <h1 class="title">Bowtie 2 Manual</h1>
 Bowtie 2</a>
 <ul>
 <li><a href="#building-from-source"
-id="toc-building-from-source">Building from source</a></li>
+id="toc-building-from-source">Building from source</a>
+<ul>
+<li><a href="#building-with-sra-support"
+id="toc-building-with-sra-support">Building with SRA support</a></li>
+<li><a href="#building-with-libsais-support"
+id="toc-building-with-libsais-support">Building with libsais
+support</a></li>
+</ul></li>
 <li><a href="#adding-to-path" id="toc-adding-to-path">Adding to
 PATH</a></li>
 </ul></li>
@@ -338,11 +348,42 @@ <h2 id="building-from-source">Building from source</h2>
 a series of commands that will: 1. download zstd and zlib 2. compile
 them as static libraries 3. link the resulting libraries to the compiled
 Bowtie 2 binaries</p>
+<h3 id="building-with-sra-support">Building with SRA support</h3>
 <p>As of version 2.3.5 bowtie2 now supports aligning SRA reads.
 Prepackaged builds will include a package that supports SRA. If you're
 building bowtie2 from source please make sure that the Java runtime is
 available on your system. You can then proceed with the build by running
 <code>make sra-deps &amp;&amp; make USE_SRA=1</code>.</p>
+<h3 id="building-with-libsais-support">Building with libsais
+support</h3>
+<p>As of version 2.5.3 <code>bowtie2</code> supports building indexes
+using the SAIS algorithm provided by <a
+href="https://github.com/IlyaGrebnov/libsais">libsais</a>. SAIS is a
+state-of-the-art suffix array construction algorithm that will
+bring-forth a significant speed-up to the overall index building
+process. There is, however, the downside of a significant increase in
+memory usage compared to the persistent blockwise algorithm that
+<code>bowtie2-build</code> uses by default. When using SAIS small
+indexes can be built for inputs up to 2GB. The
+<code>bowtie2-build</code> wrapper will help determine the appropriate
+index type for uncompressed and gzipped inputs.</p>
+<p>To build <code>bowtie2-build</code> with <a
+href="https://github.com/IlyaGrebnov/libsais">libsais</a> first make
+sure that the libsais submodule is available. This can be done in one of
+the following ways: * first time cloning bowtie2 --
+<code>git clone --recursive https://github.com/BenLangmead/bowtie2.git</code>
+* existing checkout of bowtie2 --
+<code>git submodule init &amp;&amp; git submodule update</code></p>
+<p>Issue the following command line to build libsais: * with OpenMP
+support -- <code>[g]make libsais USE_SAIS_OPENMP=1</code> * without
+OpenMP support -- <code>[g]make libsais USE_SAIS=1</code></p>
+<p>The choice of using OpenMP will determine whether or not the
+algorithm runs multithreaded. The [<code>-p/--threads</code>] argument
+to <code>bowtie2-build</code> will be ignored when libsais is compiled
+without OpenMP support.</p>
+<p>Finally, building the build executable: * with OpenMP support --
+<code>[g]make bowtie2-build-s USE_SAIS_OPENMP=1</code> * without OpenMP
+support -- <code>[g]make bowtie2-build-s USE_SAIS=1</code></p>
 <h2 id="adding-to-path">Adding to PATH</h2>
 <p>By adding your new Bowtie 2 directory to your <a
 href="http://en.wikipedia.org/wiki/PATH_(variable)">PATH environment
@@ -1167,13 +1208,12 @@ <h4 id="input-options">Input options</h4>
 <pre><code>-F k:&lt;int&gt;,i:&lt;int&gt;</code></pre>
 </td>
 <td>
-Reads are substrings (k-mers) extracted from a FASTA file
-<code>&lt;s&gt;</code>. Specifically, for every reference sequence in
-FASTA file <code>&lt;s&gt;</code>, Bowtie 2 aligns the k-mers at offsets
-1, 1+i, 1+2i, ... until reaching the end of the reference. Each k-mer is
-aligned as a separate read. Quality values are set to all Is (40 on
-Phred scale). Each k-mer (read) is given a name like
-<code>&lt;sequence&gt;_&lt;offset&gt;</code>, where
+Reads are substrings (k-mers) extracted from a FASTA file. Specifically,
+for every reference sequence in the FASTA file, Bowtie 2 aligns the
+k-mers at offsets 1, 1+i, 1+2i, ... until reaching the end of the
+reference. Each k-mer is aligned as a separate read. Quality values are
+set to all Is (40 on Phred scale). Each k-mer (read) is given a name
+like <code>&lt;sequence&gt;_&lt;offset&gt;</code>, where
 <code>&lt;sequence&gt;</code> is the name of the FASTA sequence it was
 drawn from and <code>&lt;offset&gt;</code> is its 0-based offset of
 origin with respect to the sequence. Only single k-mers, i.e. unpaired