restructured text sample unix page
This is first paragraph
Following is blockquote:
Text text Quoted text
Next up code blocks. You MUST leave a blank line after “code” (sphinx introduces “code-block”) directive.
ls
mkdir $(tmpfile)
int directory::main(std::string number)
{
extern struct phone ph;
return ph.lookup(number);
}
Typical programming language names are shell (aka sh, bash), c, c++, diff, ini (aka cfg), python, lisp, asm/nasm (GNU syntax / Intel syntax), etc.
If you don’t want to specify the programming language, just leave it empty like code-block:: or even simpler, just put 2 colons on an empty line by itself:
var y = min(x, y);
You can mark inline-code with double-backticks, like int x = 0 or def func(x): return
x**2
.
Inline code doesn’t have syntax highlighting, but you can define a new role, if you want.
In Python, def main(): return 0
is equal to 0
.
Next up maths, LaTeX syntax accepted, using .. math:: directive for block-display:
\begin{aligned} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{aligned}
Inline maths equations are supported by \frac{1}{2} + 2^2 = \frac{9}{2}.
There’re many formulas for computing \pi. Y-cruncher provides two of them:
\frac{1}{\pi} = \frac{\sqrt{8}}{9801} \sum_{n=0}^{\infty}\frac{(4n)! (26390n + 1103)}{(n!)^4\;396^{4n}}
Chudnovsky formula (1987)
\frac{1}{\pi} = 12 \sum_{n=0}^\infty (-1)^n \frac{(6n)! (545140134n + 13591409)}{(3n)(n!)^3 (640320)^{3n+3/2}}
Following is “aligned” math using & and \\.
\begin{aligned} x_1 &= \frac{1}{2}\left(2^{1/4} + \frac{1}{2^{1/4}}\right) \\ y_1 &= 2^{1/4} \\ \pi_0 &= 2 + 2^{1/2} \\ \\ x_{n+1} &= \frac{1}{2}\left(x_n^{1/2} + x_n^{-1/2}\right) \\ y_{n+1} &= \frac{y_n x_n^{1/2} + x_n^{-1/2}}{y_n + 1} \\ \pi_n &= \pi_{n-1} \left( \frac{x_n + 1}{y_n + 1} \right) \end{aligned}
Simple tables (ref) are easier to write, but limited: they must contain more than one row, and the first column cells cannot contain multiple lines. They look like this:
A |
B |
A and B |
---|---|---|
False |
False |
False |
True |
False |
False |
False |
True |
False |
True |
True |
True |
For grid tables (ref), you have to “paint” the cell grid yourself. They look like this:
Header row, column 1 (header rows optional) |
Header 2 |
Header 3 |
Header 4 |
---|---|---|---|
body row 1, column 1 |
left-aligned |
right-aligned |
centered |
body row 2 |
Cells may span columns. |
||
body row 3 |
cells may span multiple rows. |
|
|
body row 4 |
You can use Emacs’ builtin table-mode to simplify:
> M-x table-insert
You can cycle cells by TAB-ing.
Sometimes table header row (delimited by =) is not recognized. You can force any table-like structure by
> M-x table-recognize
and TAB-ing should work now.
Column width can be widened/narrowed respectively by C-c C-c > and C-c C-c < otherwise line-wrapping occurs automatically.
You can align text to lef/right/center by M-x table-justify
Column alignment can be made explicit by using the :align: option to a ..table directive: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table