Metadata-Version: 1.2
Name: Panache
Version: 0.2.11
Summary: Pandoc wrapped in styles
Home-page: https://github.com/sebogh/panache
Author: Sebastian Bogan
Author-email: sebogh@qibli.net
License: BSD 3-Clause License
Description: panache
        =======
        
        `build-status <https://travis-ci.org/sebogh/panache>`__
        `codefactor <https://www.codefactor.io/repository/github/sebogh/panache>`__
        `Known Vulnerabilities <https://snyk.io/test/github/sebogh/panache>`__
        
        https://pypi.org/project/Panache/
        
        Overview
        --------
        
        panache adds styles to `Pandoc <https://pandoc.org>`__.
        
        The idea of panache is similar to that of
        `panzer <https://github.com/msprev/panzer>`__ and
        `Pandocomatic <https://heerdebeer.org/Software/markdown/pandocomatic/>`__.
        It is yet another Pandoc wrapper, that allows to assemble
        Pandoc-commandline options, -metadata and -filter into styles. Through
        that, panache simplifies Pandoc calls and ensures consistency across
        documents.
        
        panache is similar to others in that cascading styles may be defined in
        separate YAML-files and within documents.
        
        panache is different in that its styles may contain variables and that
        documents may specify multiple styles / context dependable styles.
        
        Context Dependable Styles
        -------------------------
        
        Often a Markdown document is the source for different targets. For
        example a single document may be converted to HTML as part of a Wiki, a
        draft HTML file may be used while writing the document, and a standalone
        and self-contained HTML-file may be send to a friend. At the same time,
        all version should be rendered using the private style (as oposed to
        (for example) a company style).
        
        To address this situation, panache allows documents to specify multiple
        styles, which get selected depending on a commandline option.
        
        Assume, for example, a document with the following metadata-block:
        
        .. code:: yaml
        
           ---
           styles_:
             drafthtml: privatedrafthtml
             finalhtml: privatefinalhtml
             wiki: wikihtml
           ---
        
        Depending on the value of the command line option ``--medium`` (e.g.
        ``darfthtml``, ``finalhtml``, or ``wiki``), panache would select either
        the ``privatedrafthtml``-, ``privatefinalhtml``- or ``wikihtml``-style.
        It would then compute the commandline, filters and metadata for the
        selected style and finally call Pandoc.
        
        Cascading Style Definition
        --------------------------
        
        panache allows to define styles in separate YAML-files and within
        documents. The definition for a style with the name ``wikihtml`` might
        look like the following:
        
        .. code:: yaml
        
           ---
           styledef_:
             wikihtml:
               commandline:
                 template: /home/sebastian/templates/wiki-en.html
               metadata:
                 build-os: Linux
               filter:
                 run: pandoc-citeproc
           ---
        
        A second derived style, that changes the template, may be defined by
        adding:
        
        .. code:: yaml
        
           ---
           germanwikihtml:
             parent: wikihtml
             commandline:
                 template: /home/sebastian/pandoc-templates/templates/wiki-de.html
           ---
        
        to the previous ``styledef_`` or by adding it to a separate
        ``styledef_`` in another file.
        
        Style Variables
        ---------------
        
        Obviously, the style definitions above may work for the user
        ``sebastian`` but are likely to fail for a different user. This is where
        parameterized style definitions may be handy.
        
        panache uses `{{ mustache
        }} <https://github.com/mustache/mustache.github.com>`__ as template
        engine. Through that, panache allows to use “tags” in style definitions,
        wich are substituted based on commandline options and some defaults.
        Using this, the above definition of the ``germanwikihtml``-style may be
        rewritten as follows:
        
        .. code:: yaml
        
           ---
           germanwikihtml:
             parent: wikihtml
             commandline:
                 template: {{home}}/pandoc-templates/wiki-de.html
           ---
        
        Now, if ``--style-var=home:/home/sebastian`` would be passed to panache,
        then ``template`` would be resolved to
        ``/home/sebastian/pandoc-templates/wiki-de.html`` (and as
        ``--template=/home/sebastian/pandoc-templates/wiki-de.html`` passed to
        Pandoc). Obviously, using ``--style-var=home:~`` makes the panache call
        user agnostic (in Bash).
        
        Using regular `{{ mustache
        }}-syntax <http://mustache.github.io/mustache.5.html>`__ one may express
        conditions and repetitions.
        
        Installation
        ============
        
        Options
        -------
        
        There are two options for using panache:
        
        -  running the Python source
        -  running a binary version
        
        Both options will be described below.
        
        Python Source
        -------------
        
        Make sure the following requirements are satisfied:
        
        -  `Pandoc <https://pandoc.org>`__ >= 2.0
        -  Python >= 3.4 (incl. pyyaml, pystache)
        -  [git]
        -  [virtualenv]
        
        Get ``panache.py`` by either:
        
        -  getting the latest release from the `releases
           page <https://github.com/sebogh/panache/releases/latest>`__ or
        -  cloning the
           `github-repository <https://github.com/sebogh/panache.git>`__:
        
           .. code:: bash
        
              git clone https://github.com/sebogh/panache.git
        
        Run ``panache.py``.
        
        Binary
        ------
        
        Make sure the following requirement is satisfied:
        
        -  `Pandoc <https://pandoc.org>`__ >= 2.1
        
        Dowload the latest binary from the `releases
        page <https://github.com/sebogh/panache/releases/latest>`__ and run
        ``panache.exe`` (Windows) or ``panache`` (Linux).
        
        Details
        =======
        
        Default Style- and Meta-Variables
        ---------------------------------
        
        The following Style- and Meta-Variables will be added by default, if
        input comes from STDIN:
        
        +-------------+--------------------------------------------------------+
        | Variable    | Description                                            |
        +=============+========================================================+
        | ``panache_d | directory of the panache script                        |
        | ir``        |                                                        |
        +-------------+--------------------------------------------------------+
        | ``panache_v | panache version where ``X``, ``Y``, ``Z`` are major,   |
        | ersion_X.Y. | minor and patch (see `Semantic                         |
        | Z``         | Versioning <https://semver.org/>`__)                   |
        +-------------+--------------------------------------------------------+
        | ``os_X``    | os type where ``X`` is one of ``posix``, ``nt``,       |
        |             | ``ce``, ``java``.                                      |
        +-------------+--------------------------------------------------------+
        | ``build_dat | the date and time when panache was invoked (in the     |
        | e``         | form ``YYYY-mm-ddTHH:MM:SSZ``)                         |
        +-------------+--------------------------------------------------------+
        
        If input comes from a file the following additional Style- and
        Meta-Variables will be added by default:
        
        +------------------------------+----------------------------------------------+
        | Variable                     | Description                                  |
        +==============================+==============================================+
        | ``input_dir``                | directory of the input file                  |
        +------------------------------+----------------------------------------------+
        | ``input_basename``           | basename of the input file                   |
        +------------------------------+----------------------------------------------+
        | ``input_basename_root``      | basename without extension of the input file |
        +------------------------------+----------------------------------------------+
        | ``input_basename_extension`` | extension of the basename                    |
        +------------------------------+----------------------------------------------+
        | ``vcsreference``             | vcs reference of the file                    |
        +------------------------------+----------------------------------------------+
        | ``vcsdate``                  | vcs date (last change)                       |
        +------------------------------+----------------------------------------------+
        
        MORE
        ----
        
        tbd.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >3.5.0
