PG-RST Extensions

Previous

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.

Styles

You 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".

Table of Contents

Use 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

  • Installing EpubMaker

    • Windows

    • Debian

  • PG-RST Classes

    • Classes For Inline Text

    • Classes For Block Text

    • Classes For Front Matter Markup

  • PG-RST Extensions

    • Styles

    • Pagination

    • Table of Contents

    • List of Figures

    • List of Tables

    • Toc-Entry

    • Footnotes

    • Page Numbers

    • Dropcaps

    • Tables

  • PG Metadata

    • Top Boilerplate

    • Metadata Directive

    • Bottom Boilerplate

  • PG-RST Best Practices

  • Examples and Tests

    • Section 3.1

    • Section 3.2

    • Section 3.3

List of Figures

Use 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

  • Richard and Drucilla Martin

List of Tables

Use 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

  • Classes For Inline Text I
  • Classes For Inline Text II
  • Classes For Inline Text III
  • Classes For Block Text
  • Classes For Front Matter Markup
  • Directives For Pagination
  • Footnote Positions
  • Support for dropcaps in output formats
  • Demo Table
  • Truth table for “and”
  • Fields In the PG Scheme
  • Fields In the DC Scheme
  • Fields In the MARCREL Scheme
  • Fields Without Scheme
  • TABLE 8 Types of Computers Used in the Systems Reported

Toc-Entry

Use the toc-entry directive to:

  • provide an alternate toc entry

  • suppress a toc entry, or

  • switch toc gathering on or off.

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

Footnotes

Always define footnotes right after the paragraph they are referenced.

Positioning of footnotes

Format

Position

HTML

Collected under the footnotes directive.

EPUB

Idem.

TXT

Where they are defined.

PDF

At the bottom of the current page.

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.1

Test23 .

.. footnotes:: Footnotes
:class: smaller

Page Numbers

The 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]_.

Dropcaps

You 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.

Support for dropcaps in output formats

Format

Letter

Image

HTML

enlarged and dropped

resized and dropped

EPUB

enlarged on baseline

resized on baseline

TXT

normal size

alt text

PDF

enlarged and dropped5

resized and dropped5

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]

orem 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.

Tables

Be careful with tables because the table support of many ereaders is weak or nil.

Tables also support these options:

width

Makes the table that wide.

widths

A space-separated list of unitless values, each specifying the relative width of one table column.

If you don’t use the option widths, the column widths are calculated from the layout of the table in your source file.

aligns

Horizontally align the columns.

A space-separated list of alignments, each specifying the alignment of one column.

Valid alignments values are: left, center, right and justify.

vertical-aligns

Vertically align the columns.

A space-separated list of vertical alignments, each specifying the alignment of one column.

Valid alignments values are: top, middle, and bottom.

Note: vertical alignment is fully supported in HTML only. Other formats may support it in varying degrees.

summary (HTML only.)

Puts a summary attribute on the table element.

These are the extra classes supported by PG-RST:

norules

Omits the rules between table rows. (Not the rule between header and body nor the rules at the top and bottom of the table.)

Use this class when the eye can follow the table rows without the aid of rules.

.. 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 "
+------------------------------------+----------+-----------+
Demo Table

Header row, column 1 (header rows optional)

Justified

Centered

Price ($)

row 1

column

column

1.23

row 2

col col col col col col col

col

45.67

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 columns. Lorem ipsum dolor sit amet, consetetur adipiscing.

Cells may span rows.

row 4

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
===== ===== =========
Truth table for “and”

A

B

A and B

False

False

False

True

False

False

False

True

False

True

True

True

                                                                                                                                                                                                                                                                                                           

Clyx.com


Top of Page
Top of Page