Metadata-Version: 2.1
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
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
Requires-Dist: pyyaml (>=4.2b1)
Requires-Dist: pystache
Requires-Dist: defusedxml

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.


