You can create custom roles based on the existing ones. This is how you create and then use custom roles. .. role:: small-caps :class: small-caps This text is in :small-caps:`Small Caps`. This text is in Small Caps. You can attach more than one class to a role: .. role:: big-and-bold :class: x-large bold This text is :big-and-bold:`big and bold`. This text is big and bold. StylesYou can redefine the rendering of elements: .. style:: emphasis :class: gesperrt Now *emphasis* will be rendered as gesperrt. Now emphasis will be rendered as gesperrt. .. style:: strong :class: small-caps And **Strong Emphasis** will be rendered as small-caps. And Strong Emphasis will be rendered as small-caps. .. style:: strong :class: small-caps x-large bold And **Strong Emphasis** will be rendered as big bold small-caps. And Strong Emphasis will be rendered as big bold small-caps. .. style:: literal :class: red ``literally red`` .. style:: superscript :class: green :superscript:`sup`\ er .. style:: title_reference :class: blue :title-reference:`Hamlet` and `Othello`. literally red super Hamlet and Othello. You can semantically markup foreign text: .. role:: french :class: language-fr italics :french:`Pas de double` is the French for "father of twins". Pas de double is the French for "father of twins". PaginationPagination is important if you generate PDFs. See the Directives For Pagination Table.
Table of ContentsUse the RST contents directive to automatically generate a table of contents. N.B. You may also provide a table of contents manually. In PG-RST the contents directive requires you to specify an argument or the local option. The local option displays a local table of contents, containing only the sub-sections of the section in which it is declared. The page-numbers option displays the original page number in the TOC. .. contents:: A TOC With Page Numbers :depth: 2 :page-numbers: A TOC With Page Numbers
List of FiguresUse the lof directive to generate a list of figures automatically. N.B. You may also provide a list of figures manually. .. lof:: A List of Figures :page-numbers: :backlinks: none A List of Figures
List of TablesUse the lot directive to generate a list of tables. N.B. You may also provide a list of tables manually. .. lot:: A List of Tables :page-numbers: :backlinks: none A List of Tables
Toc-EntryUse the toc-entry directive to:
A toc-entry with argument sets the argument as toc entry for the next section, figure or table. A toc-entry without argument suppresses the toc entry for the next section, figure or table. Use the depth option to set the depth up to which section titles are gathered for the toc. A depth of 0 switches toc gathering off. .. toc-entry:: An Alternative Caption FootnotesAlways define footnotes right after the paragraph they are referenced.
To collect the footnotes use the footnotes directive. This directive will output a section with title and all footnotes in the document will be moved inside the section. In PDF and TXT formats the footnotes directive will do nothing. Test .. footnotes:: Footnotes :class: smaller Page NumbersThe sequence [pg n] will convert into a page number marker of n. n can be any arabic or roman numeral. The sequence itself will be removed from the text flow leaving a page anchor. There must be spaces around the sequence. If the page break is in the middle of a word, join the word and put the sequence at the end of the word. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt [pg 42] ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores [pg xviii] et ea rebum. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt [pg 42] ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores [pg xviii] et ea rebum. A reference to a page number can be inserted with the sequence [pg n]_. This will generate a link to the page anchor. See page [pg 42]_. See page [pg 42]_. An invisible page number can be inserted with the sequence [pg!n]. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt [pg!43] ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. See page [pg 43]_. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt [pg!43] ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. See page [pg 43]_. See page [pg iii]_. DropcapsYou can insert dropcaps with the dropcap directive. You can use either an enlarged character or an image as dropcap. You can also specify a span of character that should be set in small-caps after the dropcap initial.
The first argument (mandatory) states the character(s) to replace with caps. It must match the beginning of the next paragraph. The second (optional) argument states the characters to replace with small-caps. It must also match the beginning of the next paragraph. .. clearpage:: .. dropcap:: L Lorem ipsum :lines: 4 :indents: -1.25em 0.5em Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. The lines option (PDF only) specifies how many lines the dropcap should span. Default is 2. The indents option (PDF only) can specifiy up to 2 length values. The first one is the indent of the first line, the second one the indent of the following lines. The indent is calculated from the right border of the dropcap letter. Defaults are 0em and 0.5em. The image option specifies the image url. In plain text and EPUB the image will not be used. .. clearpage:: .. dropcap:: G :image: images/G.png :lines: 4 Gorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. [image] TablesBe careful with tables because the table support of many ereaders is weak or nil. Tables also support these options:
These are the extra classes supported by PG-RST:
.. table:: Demo Table :width: 100% :align: center :widths: 3 1 1 1 :aligns: justify justify center right :vertical-aligns: top middle bottom top :summary: This table contains valuable data. +------------------------+-----------+----------+-----------+ " Header row, column 1 " Justified " Centered " Price ($) " " (header rows optional) " " " " +========================+===========+==========+===========+ " row 1 " column " column " 1.23 " +------------------------+-----------+----------+-----------+ " row 2 " col col " col " 45.67 " " " col col " " " " " col col " " " " " col " " " +------------------------+-----------+----------+-----------+ " row 3 " Cells may span columns. " " " Lorem ipsum dolor sit amet, " " " consetetur sadipscing elitr, sed " " " nonumy eirmod tempor invidunt ut " " " labore et dolore magna aliquyam " " " sed diam voluptua. At vero eos " " " accusam et justo duo dolores et " " " rebum. " +------------------------+-----------+----------+-----------+ " Cells may span rows and " Cells " row 4 " " columns. Lorem ipsum dolor sit " may span +-----------+ " amet, consetetur adipiscing. " rows. " row 5 " +------------------------------------+----------+-----------+
.. table:: Truth table for “and” :class: norules :align: center :width: 50% ===== ===== ========= A B A and B ===== ===== ========= False False False True False False False True False True True True ===== ===== =========
|