docs: mention that --fasta-ref is required for left-alignment and nor…

…malization as pointed out in samtools#315
overerd · Sep 15, 2015 · ae4c9b0 · ae4c9b0
1 parent 5940dc0
commit ae4c9b0
Show file tree

Hide file tree

Showing 3 changed files with 25 additions and 17 deletions.
diff --git a/doc/bcftools.1 b/doc/bcftools.1
@@ -2,12 +2,12 @@
 .\"     Title: bcftools
 .\"    Author: [see the "AUTHORS" section]
 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 2015-09-02 15:10 BST
+.\"      Date: 2015-09-15 11:42 BST
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "BCFTOOLS" "1" "2015\-09\-02 15:10 BST" "\ \&" "\ \&"
+.TH "BCFTOOLS" "1" "2015\-09\-15 11:42 BST" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -41,7 +41,7 @@ Most commands accept VCF, bgzipped VCF and BCF with filetype detected automatica
 BCFtools is designed to work on a stream\&. It regards an input file "\-" as the standard input (stdin) and outputs to the standard output (stdout)\&. Several commands can thus be combined with Unix pipes\&.
 .SS "VERSION"
 .sp
-This manual page was last updated \fB2015\-09\-02 15:10 BST\fR and refers to bcftools git version \fB1\&.2\-119\-g0dbe41e+\fR\&.
+This manual page was last updated \fB2015\-09\-15 11:42 BST\fR and refers to bcftools git version \fB1\&.2\-127\-g5940dc0+\fR\&.
 .SS "BCF1"
 .sp
 The BCF1 format output by versions of samtools <= 0\&.1\&.19 is \fBnot\fR compatible with this version of bcftools\&. To read BCF1 files one can use the view command from old versions of bcftools packaged with samtools versions <= 0\&.1\&.19 to convert to VCF, which can then be read by this version of bcftools\&.
@@ -1857,7 +1857,7 @@ see
 .RE
 .SS "bcftools norm [\fIOPTIONS\fR] \fIfile\&.vcf\&.gz\fR"
 .sp
-Left\-align and normalize indels, check if REF alleles match the reference, split multiallelic sites into multiple rows; recover multiallelics from multiple rows\&.
+Left\-align and normalize indels, check if REF alleles match the reference, split multiallelic sites into multiple rows; recover multiallelics from multiple rows\&. Left\-alignment and normalization will only be applied if the \fB\-\-fasta\-ref\fR option is supplied\&.
 .PP
 \fB\-c, \-\-check\-ref\fR \fIe\fR|\fIw\fR|\fIx\fR|\fIs\fR
 .RS 4
@@ -1878,7 +1878,9 @@ remove duplicate lines of the same type
 .PP
 \fB\-f, \-\-fasta\-ref\fR \fIFILE\fR
 .RS 4
-reference sequence
+reference sequence\&. Supplying this option will turn on left\-alignment and normalization, however, see also the
+\fB\-\-do\-not\-normalize\fR
+option below\&.
 .RE
 .PP
 \fB\-m, \-\-multiallelics\fR ←|+>[\fIsnps\fR|\fIindels\fR|\fIboth\fR|\fIany\fR]

diff --git a/doc/bcftools.html b/doc/bcftools.html
@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>bcftools</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="refentry" title="bcftools" lang="en"><a id="idp150032"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>bcftools — utilities for variant calling and manipulating VCFs and BCFs.</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p><span class="strong"><strong>bcftools</strong></span> [--version|--version-only] [--help] [<span class="emphasis"><em>COMMAND</em></span>] [<span class="emphasis"><em>OPTIONS</em></span>]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>BCFtools  is  a set of utilities that manipulate variant calls in the Variant
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>bcftools</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="refentry" title="bcftools" lang="en"><a id="idp213264"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>bcftools — utilities for variant calling and manipulating VCFs and BCFs.</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p><span class="strong"><strong>bcftools</strong></span> [--version|--version-only] [--help] [<span class="emphasis"><em>COMMAND</em></span>] [<span class="emphasis"><em>OPTIONS</em></span>]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>BCFtools  is  a set of utilities that manipulate variant calls in the Variant
 Call Format (VCF) and its binary counterpart BCF. All commands work
 transparently with both VCFs and BCFs, both uncompressed and BGZF-compressed.</p><p>Most commands accept VCF, bgzipped VCF and BCF with filetype detected
 automatically even when streaming from a pipe. Indexed VCF and BCF
 will work in all situations. Un-indexed VCF and BCF and streams will
 work in most, but not all situations.</p><p>BCFtools is designed to work on a stream. It regards an input file "-" as the
 standard input (stdin) and outputs to the standard output (stdout). Several
-commands can thus be  combined  with  Unix pipes.</p><div class="refsect2" title="VERSION"><a id="_version"></a><h3>VERSION</h3><p>This manual page was last updated <span class="strong"><strong>2015-09-02 15:10 BST</strong></span> and refers to bcftools git version <span class="strong"><strong>1.2-119-g0dbe41e+</strong></span>.</p></div><div class="refsect2" title="BCF1"><a id="_bcf1"></a><h3>BCF1</h3><p>The BCF1 format output by versions of samtools &lt;= 0.1.19 is <span class="strong"><strong>not</strong></span>
+commands can thus be  combined  with  Unix pipes.</p><div class="refsect2" title="VERSION"><a id="_version"></a><h3>VERSION</h3><p>This manual page was last updated <span class="strong"><strong>2015-09-15 11:42 BST</strong></span> and refers to bcftools git version <span class="strong"><strong>1.2-127-g5940dc0+</strong></span>.</p></div><div class="refsect2" title="BCF1"><a id="_bcf1"></a><h3>BCF1</h3><p>The BCF1 format output by versions of samtools &lt;= 0.1.19 is <span class="strong"><strong>not</strong></span>
 compatible with this version of bcftools. To read BCF1 files one can use
 the view command from old versions of bcftools packaged with samtools
 versions &lt;= 0.1.19 to convert to VCF, which can then be read by
@@ -1027,9 +1027,10 @@
 <span class="strong"><strong>-R, --regions-file</strong></span> <span class="emphasis"><em>file</em></span>
 </span></dt><dd>
     see <span class="strong"><strong><a class="link" href="#common_options" title="Common Options">Common Options</a></strong></span>
-</dd></dl></div></div><div class="refsect2" title="bcftools norm [OPTIONS] file.vcf.gz"><a id="norm"></a><h3>bcftools norm [<span class="emphasis"><em>OPTIONS</em></span>] <span class="emphasis"><em>file.vcf.gz</em></span></h3><p>Left-align and normalize indels,  check if REF alleles match the reference,
+</dd></dl></div></div><div class="refsect2" title="bcftools norm [OPTIONS] file.vcf.gz"><a id="norm"></a><h3>bcftools norm [<span class="emphasis"><em>OPTIONS</em></span>] <span class="emphasis"><em>file.vcf.gz</em></span></h3><p>Left-align and normalize indels, check if REF alleles match the reference,
 split multiallelic sites into multiple rows; recover multiallelics from
-multiple rows.</p><div class="variablelist"><dl><dt><span class="term">
+multiple rows. Left-alignment and normalization will only be applied if
+the <span class="strong"><strong><a class="link" href="#fasta_ref">--fasta-ref</a></strong></span> option is supplied.</p><div class="variablelist"><dl><dt><span class="term">
 <span class="strong"><strong>-c, --check-ref</strong></span> <span class="emphasis"><em>e</em></span>|<span class="emphasis"><em>w</em></span>|<span class="emphasis"><em>x</em></span>|<span class="emphasis"><em>s</em></span>
 </span></dt><dd>
     what to do when incorrect or missing REF allele is encountered:
@@ -1042,9 +1043,11 @@
 </span></dt><dd>
     remove duplicate lines of the same type
 </dd><dt><span class="term">
-<span class="strong"><strong>-f, --fasta-ref</strong></span> <span class="emphasis"><em>FILE</em></span>
+<span class="strong"><strong>-f, --fasta-ref</strong></span> <span class="emphasis"><em>FILE</em></span><a id="fasta_ref"></a>
 </span></dt><dd>
-    reference sequence
+    reference sequence. Supplying this option will turn on left-alignment
+    and normalization, however, see also the <span class="strong"><strong><a class="link" href="#do_not_normalize">--do-not-normalize</a></strong></span>
+    option below.
 </dd><dt><span class="term">
 <span class="strong"><strong>-m, --multiallelics</strong></span> ←|+&gt;[<span class="emphasis"><em>snps</em></span>|<span class="emphasis"><em>indels</em></span>|<span class="emphasis"><em>both</em></span>|<span class="emphasis"><em>any</em></span>]
 </span></dt><dd>
@@ -1056,7 +1059,7 @@
     <span class="emphasis"><em>both</em></span>; if SNPs and indels should be merged into a single record, specify
     <span class="emphasis"><em>any</em></span>.
 </dd><dt><span class="term">
-<span class="strong"><strong>-N, --do-not-normalize</strong></span>
+<span class="strong"><strong>-N, --do-not-normalize</strong></span><a id="do_not_normalize"></a>
 </span></dt><dd>
     the <span class="emphasis"><em>-c s</em></span> option can be used to fix or set the REF allele from the
     reference <span class="emphasis"><em>-f</em></span>. The <span class="emphasis"><em>-N</em></span> option will not turn on indel normalisation

diff --git a/doc/bcftools.txt b/doc/bcftools.txt
@@ -1085,9 +1085,10 @@ For "vertical" merge take a look at *<<norm,bcftools norm>>* instead.
 
 [[norm]]
 === bcftools norm ['OPTIONS'] 'file.vcf.gz'
-Left-align and normalize indels,  check if REF alleles match the reference,
+Left-align and normalize indels, check if REF alleles match the reference,
 split multiallelic sites into multiple rows; recover multiallelics from
-multiple rows.
+multiple rows. Left-alignment and normalization will only be applied if
+the *<<fasta_ref,--fasta-ref>>* option is supplied.
 
 *-c, --check-ref* 'e'|'w'|'x'|'s':: 
     what to do when incorrect or missing REF allele is encountered: 
@@ -1099,8 +1100,10 @@ multiple rows.
 *-D, --remove-duplicates*::
     remove duplicate lines of the same type
 
-*-f, --fasta-ref* 'FILE'::
-    reference sequence
+*-f, --fasta-ref* 'FILE'[[fasta_ref]]::
+    reference sequence. Supplying this option will turn on left-alignment
+    and normalization, however, see also the *<<do_not_normalize,--do-not-normalize>>*
+    option below.
 
 *-m, --multiallelics* <-|+>['snps'|'indels'|'both'|'any']::
     split multiallelic sites into biallelic records ('-') or join
@@ -1111,7 +1114,7 @@ multiple rows.
     'both'; if SNPs and indels should be merged into a single record, specify
     'any'.
 
-*-N, --do-not-normalize*::
+*-N, --do-not-normalize*[[do_not_normalize]]::
     the '-c s' option can be used to fix or set the REF allele from the 
     reference '-f'. The '-N' option will not turn on indel normalisation
     as the '-f' option normally implies