| Name | presenterm-export JSON |
| Version |
0.2.4
JSON |
| download |
| home_page | None |
| Summary | Presenterm's presentation exporter |
| upload_time | 2024-07-29 13:28:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | BSD 2-Clause License Copyright (c) 2023, Matias Fontanini All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
presenterm
terminal
slideshow
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# presenterm-export
A PDF exporter for [presenterm](https://github.com/mfontanini/presenterm).
---
**This is not meant to be used as a standalone tool but instead by running _presenterm_ using the `--export-pdf`
switch.**
# Installation
This tool requires [tmux](https://github.com/tmux/tmux/) to be installed. Then simply run:
```shell
pip install presenterm-export
```
**Note**: make sure that `presenterm-export` works by running `presenterm-export --version` before attempting to
> generate a PDF file. If you get errors related to _weasyprint_, follow their [installation
> instructions](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) to ensure you meet all of their
> dependencies. This has otherwise caused issues in macOS.
# How it works
This tool's goal is to capture the output of _presenterm_ and turn it into a PDF file. This section outlines roughly how
it works.
## Presentation metadata
Before _presenterm_ runs this tool, it will gnerate a JSON blob that contains metadata about the presentation,
including:
* Its path.
* Where each image is in the original markdown file.
* The keys that _presenterm_ wants this tool to simulate to capture its contents. This allows this tool to be pretty
dumb in terms of capturing: it doesn't even understand slides, it just presses whatever _presenterm_ tells it to.
This metadata is then passed into this tool via stdin.
## Capturing
Capturing the output of _presenterm_ is done via `tmux` by running it, sending keys to it, and performing pane captures.
The output of this stage is a list of panes that contain ANSI escape codes. This means you can print them on a terminal
and they'll look good but you can't really turn them into PDF as-is.
## Conversion to HTML
The next step is to take the ANSI text and turn it into HTML via [ansi2html](https://github.com/pycontribs/ansi2html).
This library creates HTML that looks mostly how we want it to but we perform a few transformations so it looks as close
to _presenterm_ itself as we can.
## Conversion to PDF
Finally, the HTML is converted into PDF by using [weasyprint](https://github.com/Kozea/WeasyPrint). The result is a PDF
that looks exactly as if you had ran _presenterm_ including background colors and images.
# Images
Images are tricky and are the reason why this uses HTML as an intermediate step, given they can't be represented with
just text so `tmux` pane captures will ignore them.
Luckily, [viuer](https://github.com/atanunq/viuer), the crate _presenterm_ uses to display images, falls back to using
text blocks to display images when your terminal emulator doesn't support any of the image protocols (e.g. kitty's).
This means if you ran this under `tmux` you would get an ASCII-based version of your images.
This could be enough but we _really_ want PDF exports to look as close to the real thing as possible. So instead of
keeping those ASCII based images, we do the following:
1. Replace every image with a new image of the same size but made up of a single unique color. This means an image of
300x200px will be replaced with another one of 300x200px but made up of some specific color. The reason for doing
this is we can then easily spot these blocks of text in the HTML output, which means we can know exactly where the
original image should be in the HTML version of the presentation.
2. After the transformation to HTML, we do a pass and find every image based on the color we chose for it and replace it
with an `img` tag pointing to its original and using a properly scaled width attribute.
3. When the PDF generation occurs, the image tags are correctly interpreted and the final PDF output contains every
image where it should be.
# Presentation size
The size of the page in the generated PDF is the same as the size of the terminal you run `presenterm --export-pdf` on.
That means you should adjust your terminal size before running it so that it fits text however you want it to.
Raw data
{
"_id": null,
"home_page": null,
"name": "presenterm-export",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Matias Fontanini <matias.fontanini@gmail.com>",
"keywords": "presenterm, terminal, slideshow",
"author": null,
"author_email": "Matias Fontanini <matias.fontanini@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/a0/a96c9ace6550a596a6d94bf1a4825f23fe99c368c877e99c2bee778b0622/presenterm_export-0.2.4.tar.gz",
"platform": null,
"description": "# presenterm-export\n\nA PDF exporter for [presenterm](https://github.com/mfontanini/presenterm).\n\n---\n\n**This is not meant to be used as a standalone tool but instead by running _presenterm_ using the `--export-pdf` \nswitch.**\n\n# Installation\n\nThis tool requires [tmux](https://github.com/tmux/tmux/) to be installed. Then simply run:\n\n```shell\npip install presenterm-export\n```\n\n **Note**: make sure that `presenterm-export` works by running `presenterm-export --version` before attempting to \n> generate a PDF file. If you get errors related to _weasyprint_, follow their [installation \n> instructions](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) to ensure you meet all of their \n> dependencies. This has otherwise caused issues in macOS.\n\n# How it works\n\nThis tool's goal is to capture the output of _presenterm_ and turn it into a PDF file. This section outlines roughly how \nit works.\n\n## Presentation metadata\n\nBefore _presenterm_ runs this tool, it will gnerate a JSON blob that contains metadata about the presentation, \nincluding:\n* Its path.\n* Where each image is in the original markdown file.\n* The keys that _presenterm_ wants this tool to simulate to capture its contents. This allows this tool to be pretty \n dumb in terms of capturing: it doesn't even understand slides, it just presses whatever _presenterm_ tells it to.\n\nThis metadata is then passed into this tool via stdin.\n\n## Capturing\n\nCapturing the output of _presenterm_ is done via `tmux` by running it, sending keys to it, and performing pane captures.\n\nThe output of this stage is a list of panes that contain ANSI escape codes. This means you can print them on a terminal \nand they'll look good but you can't really turn them into PDF as-is.\n\n## Conversion to HTML\n\nThe next step is to take the ANSI text and turn it into HTML via [ansi2html](https://github.com/pycontribs/ansi2html). \nThis library creates HTML that looks mostly how we want it to but we perform a few transformations so it looks as close \nto _presenterm_ itself as we can.\n\n## Conversion to PDF\n\nFinally, the HTML is converted into PDF by using [weasyprint](https://github.com/Kozea/WeasyPrint). The result is a PDF \nthat looks exactly as if you had ran _presenterm_ including background colors and images.\n\n# Images\n\nImages are tricky and are the reason why this uses HTML as an intermediate step, given they can't be represented with \njust text so `tmux` pane captures will ignore them.\n\nLuckily, [viuer](https://github.com/atanunq/viuer), the crate _presenterm_ uses to display images, falls back to using \ntext blocks to display images when your terminal emulator doesn't support any of the image protocols (e.g. kitty's). \nThis means if you ran this under `tmux` you would get an ASCII-based version of your images.\n\nThis could be enough but we _really_ want PDF exports to look as close to the real thing as possible. So instead of \nkeeping those ASCII based images, we do the following:\n\n1. Replace every image with a new image of the same size but made up of a single unique color. This means an image of \n 300x200px will be replaced with another one of 300x200px but made up of some specific color. The reason for doing \n this is we can then easily spot these blocks of text in the HTML output, which means we can know exactly where the \n original image should be in the HTML version of the presentation.\n2. After the transformation to HTML, we do a pass and find every image based on the color we chose for it and replace it \n with an `img` tag pointing to its original and using a properly scaled width attribute.\n3. When the PDF generation occurs, the image tags are correctly interpreted and the final PDF output contains every \n image where it should be.\n\n# Presentation size\n\nThe size of the page in the generated PDF is the same as the size of the terminal you run `presenterm --export-pdf` on. \nThat means you should adjust your terminal size before running it so that it fits text however you want it to.\n\n",
"bugtrack_url": null,
"license": "BSD 2-Clause License Copyright (c) 2023, Matias Fontanini All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "Presenterm's presentation exporter",
"version": "0.2.4",
"project_urls": {
"Bug Reports": "https://github.com/mfontanini/presenterm-export",
"Homepage": "https://github.com/mfontanini/presenterm-export",
"Source": "https://github.com/mfontanini/presenterm-export"
},
"split_keywords": [
"presenterm",
" terminal",
" slideshow"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e2d325834ad61b16cf1aff818a8f9bcc80f9ea5c7269dcdc1f609886b4702e6f",
"md5": "67a5b38108d25071f6aa69b793c0dd37",
"sha256": "75411ab99cb9d26749e562f0abce0b5d7167c410bc30adc2836c4289c3916ea0"
},
"downloads": -1,
"filename": "presenterm_export-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "67a5b38108d25071f6aa69b793c0dd37",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11298,
"upload_time": "2024-07-29T13:28:33",
"upload_time_iso_8601": "2024-07-29T13:28:33.110613Z",
"url": "https://files.pythonhosted.org/packages/e2/d3/25834ad61b16cf1aff818a8f9bcc80f9ea5c7269dcdc1f609886b4702e6f/presenterm_export-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4fa0a96c9ace6550a596a6d94bf1a4825f23fe99c368c877e99c2bee778b0622",
"md5": "06dc89c288bdcb8f5e8668088700c8e8",
"sha256": "611a7dd79276bcc3537900f0301471ef3d02e9bc23db66be67f68e31f1ee7a88"
},
"downloads": -1,
"filename": "presenterm_export-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "06dc89c288bdcb8f5e8668088700c8e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 11385,
"upload_time": "2024-07-29T13:28:35",
"upload_time_iso_8601": "2024-07-29T13:28:35.385131Z",
"url": "https://files.pythonhosted.org/packages/4f/a0/a96c9ace6550a596a6d94bf1a4825f23fe99c368c877e99c2bee778b0622/presenterm_export-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-29 13:28:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mfontanini",
"github_project": "presenterm-export",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "presenterm-export"
}
