-.TH DEAL 1 "September 27, 1996"
-.SH NAME
-deal \- compute and display deal probabilities
-.SH SYNOPSIS
-.B deal [-h] [-b base] [-t turns] [-c columns] [-g] [-w] specials total
-.SH DESCRIPTION
-This program prints out tables of non-replacement draw probabilities,
-rounded to the nearest percent.
-.PP
-Suppose I have M special cards in my deck and N total cards in my deck,
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<refentry id='deal.1'>
+<refmeta>
+<refentrytitle>deal</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='date'>September 27, 1996</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>deal</refname>
+<refpurpose>compute and display deal probabilities</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+
+<cmdsynopsis>
+ <!-- deal [ \-h ] [ \-b base ] [ \-t turns ] [ \-c columns ] [ \-g ] [ \-w ] specials total -->
+ <command>deal</command> <arg choice='opt'>-h </arg>
+ <arg choice='opt'>-b <replaceable>base</replaceable></arg>
+ <arg choice='opt'>-t <replaceable>turns</replaceable></arg>
+ <arg choice='opt'>-c <replaceable>columns</replaceable></arg>
+ <arg choice='opt'>-g </arg>
+ <arg choice='opt'>-w </arg>
+ <arg choice='plain'><replaceable>specialstotal</replaceable></arg>
+</cmdsynopsis>
+
+</refsynopsisdiv>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>This program prints out tables of non-replacement draw probabilities,
+rounded to the nearest percent.</para>
+
+<para>Suppose I have M special cards in my deck and N total cards in my deck,
and I draw k cards from that deck without replacement. Let X count
-the number of special cards contained in those k drawn cards.
-.PP
-Then X has a hypergeometric distribution, with the following formula
-for probabilities:
+the number of special cards contained in those k drawn cards.</para>
-.nf
+<para>Then X has a hypergeometric distribution, with the following formula
+for probabilities:</para>
+
+<literallayout remap='.nf'>
B(M, i) * B(N-M, k-i)
P(X = i) = ---------------------
B(N, k)
-.fi
+</literallayout> <!-- .fi -->
-where B(a,b) is the binomial coefficient (read "a choose b"), and is the
+<para>where B(a,b) is the binomial coefficient (read "a choose b"), and is the
number of ways to choose b objects out of a possible objects. The
-formula for the binomial coefficient is:
+formula for the binomial coefficient is:</para>
+
+<para> B(n,m) = n!/(m! * (n-m)!)</para>
- B(n,m) = n!/(m! * (n-m)!)
+<para>where n! is the factorial function n! = 1 * 2 * 3 * ... * n.</para>
-where n! is the factorial function n! = 1 * 2 * 3 * ... * n.
-.PP
-This program prints out tables of these probabilities. The `specials'
+<para>This program prints out tables of these probabilities. The `specials'
and `total' arguments specify M and N. The table displays values for
-ranges of k and i.
-.PP
-In the table output, a dot designates a probability less than .5% that
-rounds to zero. Impossible outcomes are blank.
-.PP
-The program accepts the following options to control its output:
-.TP 10
--b
-Number of cards to assume in the initial hand. Note: this defaults to
-7, \fBnot\fB to 0!
-.TP 10
--g
-Normally, the program displays the probability that you will have
-\fIexactly\fR a given number of specials. With this option, it
-displays the odds that you will have the given number of specials
-\fIor more\fR. This option also forces -w on, to accomodate 100%
-probabilities which will show up in column 0 if nowhere else.
-.TP 10
--w
-Force wide display (3 chars per percentage) to accommodate 100% probabilities.
-.TP 10
--c
-Number of table columns to generate in the report. Defaults to the
-number of specials plus one additional to accommodate the zero column.
-.TP 10
--h
-Suppress table headers and legends.
-.TP 10
--t
-Set number of draws to display probabilities for (default to 20 or the
-total number of cards, whichever is less)
-.TP 10
--v
-Verbose. Log the computation steps for each hypergeometric
-coefficient to standard error. Use this for debugging if you are
-a trained numerical analyst (kids, don't try this yourselves at home!).
-.TP 10
--B
-Binomial coefficient test. Compute and print the binomial coefficient
-B(n, k) or `n choose k'.
-.TP 10
--G
-Gamma function test. Compute and display the log of the gamma
-function of the argument. If -v tells you that the computation of
+ranges of k and i.</para>
+
+<para>In the table output, a dot designates a probability less than .5% that
+rounds to zero. Impossible outcomes are blank.</para>
+
+<para>The program accepts the following options to control its output:</para>
+<variablelist remap='TP'>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-b </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Number of cards to assume in the initial hand. Note: this defaults to
+7, <emphasis remap='B'>not to 0!</emphasis></para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-g </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Normally, the program displays the probability that you will
+have <emphasis>exactly</emphasis> a given number of specials. With
+this option, it displays the odds that you will have the given number
+of specials <emphasis>or more</emphasis>. This option also forces
+<option>-w</option> on, to accomodate 100% probabilities which will
+show up in column 0 if nowhere else.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-w </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Force wide display (3 chars per percentage) to accommodate 100% probabilities.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-c </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Number of table columns to generate in the report. Defaults to the
+number of specials plus one additional to accommodate the zero column.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-h </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Suppress table headers and legends.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-t </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Set number of draws to display probabilities for (default to 20 or the
+total number of cards, whichever is less)</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-v </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Verbose. Log the computation steps for each hypergeometricoefficient to standard error. Use this for debugging if you are
+a trained numerical analyst (kids, don't try this yourselves at home!).</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-B </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Binomial coefficient test. Compute and print the binomial coefficient
+B(n, k) or `n choose k'.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-G </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Gamma function test. Compute and display the log of the gamma
+function of the argument. If <option>-v</option> tells you that the computation of
B(n, k) is blowing up, this will enable you to probe the local lgamma
-function.
-.TP
--H
-Compute the hypergeometric probability H(i, k, M, N) with arguments
-supplied from the command line. For debugging.
-.PP
-.SH EXAMPLES
-To compute the probabilities for drawing your 3 Hurloon
+function.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<cmdsynopsis>
+ <arg choice='plain'>-H </arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>Compute the hypergeometric probability H(i, k, M, N) with arguments
+supplied from the command line. For debugging.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+
+</refsect1>
+
+<refsect1 id='examples'><title>EXAMPLES</title>
+<para>To compute the probabilities for drawing your 3 Hurloon
Minotaurs during the first 20 turns from a 62-card "Magic: The
-Gathering" deck (MtG starts you with 7 cards):
+Gathering" deck (MtG starts you with 7 cards):</para>
- deal 3 62
+<para> <command>deal</command> 3 62</para>
-To compute your chances of having the 4 aces on the nth draw in
-5-card draw poker:
+<para>To compute your chances of having the 4 aces on the nth draw in
+5-card draw poker:</para>
- deal -b 5 4 52
+<para> <command>deal</command> <option>-b</option> 5 4 52 </para>
-.SH BUGS
-The -w and -g options widen the column width of the tables to
+</refsect1>
+
+<refsect1 id='bugs'><title>BUGS</title>
+<para>The <option>-w</option> and <option>-g</option> options widen the column width of the tables to
accommodate 100% probabilities, at the cost of making the table too
wide to display on an 80-column terminal when the number of specials
is more than 17. When wide display is off, on the other hand, 23
specials will fit in 80 colums, but 100% probabilities can mess up the
-table formatting.
-.SH AUTHOR
-Eric S. Raymond <esr@snark.thyrsus.com>. Based on the `cardprobs'
-program by Jeremy York. See my home page at
-http://www.ccil.org/~esr/home.html for updates and other resources.
+table formatting.</para>
+</refsect1>
+
+<refsect1 id='author'><title>AUTHOR</title>
+<para>Eric S. Raymond <esr@snark.thyrsus.com>. Based on the
+`cardprobs' program by Jeremy York. See my home page at <ulink
+url='http://www.tuxedo.org/~esr'>http://www.tuxedo.org/~esr</ulink>
+for updates and other resources.</para>
+</refsect1>
+
+</refentry>
projects / deal.git / commitdiff