diff options
Diffstat (limited to 'doc/markup')
| -rw-r--r-- | doc/markup/code.rst | 18 | ||||
| -rw-r--r-- | doc/markup/misc.rst | 91 | ||||
| -rw-r--r-- | doc/markup/toctree.rst | 2 |
3 files changed, 85 insertions, 26 deletions
diff --git a/doc/markup/code.rst b/doc/markup/code.rst index c7cb0f911..cb3e55bdc 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -184,9 +184,17 @@ Includes string option, only lines that precede the first lines containing that string are included. + With lines selected using ``start-after`` it is still possible to use + ``lines``, the first allowed line having by convention the line number ``1``. + + When lines have been selected in any of the ways described above, the + line numbers in ``emphasize-lines`` also refer to the selection, with the + first selected line having number ``1``. + When specifying particular parts of a file to display, it can be useful to - display exactly which lines are being presented. - This can be done using the ``lineno-match`` option. + display the original line numbers. This can be done using the + ``lineno-match`` option, which is however allowed only when the selection + consists of contiguous lines. You can prepend and/or append a line to the included code, using the ``prepend`` and ``append`` option, respectively. This is useful e.g. for @@ -212,7 +220,9 @@ Includes .. versionadded:: 1.3 The ``diff`` option. The ``lineno-match`` option. - + .. versionchanged:: 1.6 + With both ``start-after`` and ``lines`` in use, the first line as per + ``start-after`` is considered to be with line number ``1`` for ``lines``. Caption and name ^^^^^^^^^^^^^^^^ @@ -232,7 +242,7 @@ For example:: :rst:dir:`literalinclude` also supports the ``caption`` and ``name`` option. -``caption`` has a additional feature that if you leave the value empty, the shown +``caption`` has an additional feature that if you leave the value empty, the shown filename will be exactly the one given as an argument. diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 0e1d104d6..c4b64e39c 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -201,6 +201,11 @@ Including content based on tags .. versionchanged:: 1.2 Added the name of the builder and the prefixes. + .. warning:: + + This directive is designed to control only content of document. It could + not control sections, labels and so on. + Tables ------ @@ -237,32 +242,76 @@ following directive exists: in proportion to the observed shares in a first pass where the table cells are rendered at their natural "horizontal" widths. - By default, Sphinx uses a table layout with ``L`` for every column. - - .. hint:: - - For columns which are known to be much narrower than the others it is - recommended to use the lowercase specifiers. For more information, check - the ``tabulary`` manual. + By default, Sphinx uses a table layout with ``J`` for every column. .. versionadded:: 0.3 -.. warning:: - - Tables with more than 30 rows are rendered using ``longtable``, not - ``tabulary``, in order to allow pagebreaks. + .. versionchanged:: 1.6 + Merged cells may now contain multiple paragraphs and are much better + handled, thanks to custom Sphinx LaTeX macros. This novel situation + motivated the switch to ``J`` specifier and not ``L`` by default. - Tables that contain list-like elements such as object descriptions, - blockquotes or any kind of lists cannot be set out of the box with - ``tabulary``. They are therefore set with the standard LaTeX ``tabular`` - environment if you don't give a ``tabularcolumns`` directive. If you do, the - table will be set with ``tabulary``, but you must use the ``p{width}`` - construct for the columns that contain these elements. + .. hint:: - Literal blocks do not work with ``tabulary`` at all, so tables containing a - literal block are always set with ``tabular``. Also, the verbatim - environment used for literal blocks only works in ``p{width}`` columns, which - means that by default, Sphinx generates such column specs for such tables. + Sphinx actually uses ``T`` specifier having done ``\newcolumntype{T}{J}``. + To revert to previous default, insert ``\newcolumntype{T}{L}`` in the + LaTeX preamble (see :confval:`latex_elements`). + + A frequent issue with tabulary is that columns with little contents are + "squeezed". The minimal column width is a tabulary parameter called + ``\tymin``. You may set it globally in the LaTeX preamble via + ``\setlength{\tymin}{40pt}`` for example. + + Else, use the :rst:dir:`tabularcolumns` directive with an explicit + ``p{40pt}`` (for example) for that column. You may use also ``l`` + specifier but this makes the task of setting column widths more difficult + if some merged cell intersects that column. + + .. warning:: + + Tables with more than 30 rows are rendered using ``longtable``, not + ``tabulary``, in order to allow pagebreaks. The ``L``, ``R``, ... specifiers + do not work for these tables. + + Tables that contain list-like elements such as object descriptions, + blockquotes or any kind of lists cannot be set out of the box with + ``tabulary``. They are therefore set with the standard LaTeX ``tabular`` (or + ``longtable``) environment if you don't give a ``tabularcolumns`` directive. + If you do, the table will be set with ``tabulary`` but you must use the + ``p{width}`` construct (or Sphinx's ``\X`` and ``\Y`` specifiers described + below) for the columns containing these elements. + + Literal blocks do not work with ``tabulary`` at all, so tables containing + a literal block are always set with ``tabular``. The verbatim environment + used for literal blocks only works in ``p{width}`` (and ``\X`` or ``\Y``) + columns, hence Sphinx generates such column specs for tables containing + literal blocks. + + Since Sphinx 1.5, the ``\X{a}{b}`` specifier is used (there *is* a backslash + in the specifier letter). It is like ``p{width}`` with the width set to a + fraction ``a/b`` of the current line width. You can use it in the + :rst:dir:`tabularcolumns` (it is not a problem if some LaTeX macro is also + called ``\X``.) + + It is *not* needed for ``b`` to be the total number of columns, nor for the + sum of the fractions of the ``\X`` specifiers to add up to one. For example + ``|\X{2}{5}|\X{1}{5}|\X{1}{5}|`` is legitimate and the table will occupy + 80% of the line width, the first of its three columns having the same width + as the sum of the next two. + + This is used by the ``:widths:`` option of the :dudir:`table` directive. + + Since Sphinx 1.6, there is also the ``\Y{f}`` specifier which admits a + decimal argument, such has ``\Y{0.15}``: this would have the same effect as + ``\X{3}{20}``. + + .. versionchanged:: 1.6 + + Merged cells from complex grid tables (either multi-row, multi-column, or + both) now allow blockquotes, lists, literal blocks, ... as do regular cells. + + Sphinx's merged cells interact well with ``p{width}``, ``\X{a}{b}``, ``Y{f}`` + and tabulary's columns. .. rubric:: Footnotes diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst index a0161ee3c..78a72c1b4 100644 --- a/doc/markup/toctree.rst +++ b/doc/markup/toctree.rst @@ -41,7 +41,7 @@ tables of contents. The ``toctree`` directive is the central element. * Tables of contents from all those documents are inserted, with a maximum depth of two, that means one nested heading. ``toctree`` directives in those documents are also taken into account. - * Sphinx knows that the relative order of the documents ``intro``, + * Sphinx knows the relative order of the documents ``intro``, ``strings`` and so forth, and it knows that they are children of the shown document, the library index. From this information it generates "next chapter", "previous chapter" and "parent chapter" links. |