<commit_before>==================
How to use rst2pdf
==================

:author: <NAME> <<EMAIL>>
:version: 0.16
:revision: $LastChangedRevision$

.. header::

   .. oddeven::

      .. class:: headertable

      +---+---------------------+----------------+
      |   |.. class:: centered  |.. class:: right|
      |   |                     |                |
      |   |Section ###Section###|Page ###Page### |
      +---+---------------------+----------------+

      .. class:: headertable

      +---------------+---------------------+---+
      |               |.. class:: centered  |   |
      |               |                     |   |
      |Page ###Page###|Section ###Section###|   |
      +---------------+---------------------+---+


.. contents::

.. section-numbering::

.. raw:: pdf

   PageBreak oneColumn

Introduction
============

This document explains how to use rst2pdf. Here is the very short version::

    rst2pdf.py mydocument.txt -o mydocument.pdf

That will, as long as mydocument.txt is a valid Restructured Text (ReST)
document, produce a file called mydocument.pdf which is a PDF
version of your document.

Of course, that means you just used default styles and settings. If it
looks good enough for you, then you may stop reading this document,
because you are done with it. If you are reading this in a PDF,
it was generated using those default settings.

However, if you want to customize the output, or are just curious to see
what can be done, let´s continue.

Command line options
====================


.. include:: rst2pdf.txt
   :start-line: 30
   :end-before: EXAMPLES

Configuration File
==================

Since version 0.8, rst2pdf will read (if it is available) configuration files in
``/etc/rst2pdf.conf`` and ``~/.rst2pdf/config``.

The user's file at ``~/.rst2pdf/config`` will have priority over the system's at
``/etc/rst2pdf.conf`` [#]_

.. [#] The ``/etc/rst2pdf.conf`` location makes sense for Linux and linux-like systems.
       if you are using rst2pdf in other systems, please contact me and tell me where
       the system-wide config file should be.



Here's an example file showing some of the currently available options:

.. code-block:: ini

    # This is an example config file. Modify and place in ~/.rst2pdf/config

    [general]
    # A comma-separated list of custom stylesheets. Example:
    # stylesheets="fruity.json,a4paper.json,verasans.json"
    stylesheets=""

    # Create a compressed PDF
    # Use true/false (lower case) or 1/0
    # Example: compressed=true
    compressed=false

    # A colon-separated list of folders to search for fonts. Example:
    # font_path="/usr/share/fonts:/usr/share/texmf-dist/fonts/"
    font_path=""

    # Language to be used for hyphenation support
    language="en_US"

    # Default page header and footer
    header=None
    footer=None

    # What to do if a literal block is too large. Can be
    # shrink/truncate/overflow
    fit_mode="shrink"

    # What is the maximum level of heading that starts in a new page.
    # 0 means no level starts in a new page.
    break_level=0

Included with rst2pdf is an example file with every option in it.

Pipe usage
==========

If no input nor output are provided, stdin and stdout will be used respectively

You may want to use rst2pdf in a linux pipe as such::
<commit_msg>Use config.sample in the manual<commit_after>==================
How to use rst2pdf
==================

:author: <NAME> <<EMAIL>>
:version: 0.16
:revision: $LastChangedRevision$

.. header::

   .. oddeven::

      .. class:: headertable

      +---+---------------------+----------------+
      |   |.. class:: centered  |.. class:: right|
      |   |                     |                |
      |   |Section ###Section###|Page ###Page### |
      +---+---------------------+----------------+

      .. class:: headertable

      +---------------+---------------------+---+
      |               |.. class:: centered  |   |
      |               |                     |   |
      |Page ###Page###|Section ###Section###|   |
      +---------------+---------------------+---+


.. contents::

.. section-numbering::

.. raw:: pdf

   PageBreak oneColumn

Introduction
============

This document explains how to use rst2pdf. Here is the very short version::

    rst2pdf.py mydocument.txt -o mydocument.pdf

That will, as long as mydocument.txt is a valid Restructured Text (ReST)
document, produce a file called mydocument.pdf which is a PDF
version of your document.

Of course, that means you just used default styles and settings. If it
looks good enough for you, then you may stop reading this document,
because you are done with it. If you are reading this in a PDF,
it was generated using those default settings.

However, if you want to customize the output, or are just curious to see
what can be done, let´s continue.

Command line options
====================


.. include:: rst2pdf.txt
   :start-line: 30
   :end-before: EXAMPLES

Configuration File
==================

Since version 0.8, rst2pdf will read (if it is available) configuration files in
``/etc/rst2pdf.conf`` and ``~/.rst2pdf/config``.

The user's file at ``~/.rst2pdf/config`` will have priority over the system's at
``/etc/rst2pdf.conf`` [#]_

.. [#] The ``/etc/rst2pdf.conf`` location makes sense for Linux and linux-like systems.
       if you are using rst2pdf in other systems, please contact me and tell me where
       the system-wide config file should be.



Here's an example file showing some of the currently available options:

.. code-block:: ini
   :include: config.sample

Pipe usage
==========

If no input nor output are provided, stdin and stdout will be used respectively

You may want to use rst2pdf in a linux pipe as such::

{'fraction_non_alphanumeric': 0.18090277777777777, 'fraction_numerical': 0.0078125, 'mean_word_length': 2.2603282399547253, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1146622', 'n_tokens_mistral': 1674, 'n_tokens_neox': 1560, 'n_words': 632}