chore: prepare v0.9.0 changes (#377)

CHANGELOG.md

@@ -1,3 +1,65 @@
+# v0.9.0 - 2024-10-04
+
+## Breaking changes
+
+* Default themes now no longer use a progress bar based footer. Instead they use indicator of the current page number 
+and the total number of pages. If you'd like to preserve the old behavior, you can override the theme by using 
+`footer.style = progress_bar` in [your 
+theme](https://mfontanini.github.io/presenterm/guides/themes.html#setting-themes).
+* Links that include a title (e.g. `[my title](http://example.com)`) now have their title rendered as well. Removing a 
+link's title will make it look the same as they used to.
+
+## New features
+
+* Use "template" footer in built-in themes ([#358](https://github.com/mfontanini/presenterm/issues/358)).
+* Allow including external code snippets ([#328](https://github.com/mfontanini/presenterm/issues/328)) 
+  ([#372](https://github.com/mfontanini/presenterm/issues/372)).
+* Add `+no_background` property to remove background from code blocks 
+  ([#363](https://github.com/mfontanini/presenterm/issues/363)) 
+  ([#368](https://github.com/mfontanini/presenterm/issues/368)).
+* Show colored output from snippet execution output ([#316](https://github.com/mfontanini/presenterm/issues/316)).
+* Style markdown inside block quotes ([#350](https://github.com/mfontanini/presenterm/issues/350)) 
+  ([#351](https://github.com/mfontanini/presenterm/issues/351)).
+* Allow using all intro slide variables in footer template 
+  ([#338](https://github.com/mfontanini/presenterm/issues/338)).
+* Include hidden line prefix in executors file ([#337](https://github.com/mfontanini/presenterm/issues/337)).
+* Show link labels and titles ([#334](https://github.com/mfontanini/presenterm/issues/334)).
+* Add `+exec_replace` which executes snippets and replaces them with their output 
+  ([#330](https://github.com/mfontanini/presenterm/issues/330)) 
+  ([#371](https://github.com/mfontanini/presenterm/issues/371)).
+* Always show snippet execution bar ([#329](https://github.com/mfontanini/presenterm/issues/329)).
+* Handle suspend signal (SIGTSTP) ([#318](https://github.com/mfontanini/presenterm/issues/318)).
+* Allow closing with `q` ([#321](https://github.com/mfontanini/presenterm/issues/321)).
+* Add event, location, and date labels in intro slide ([#317](https://github.com/mfontanini/presenterm/issues/317)).
+* Use transparent background in mermaid charts ([#314](https://github.com/mfontanini/presenterm/issues/314)).
+* Add `+acquire_terminal` to acquire the terminal when running snippets 
+  ([#366](https://github.com/mfontanini/presenterm/issues/366))
+  ([#376](https://github.com/mfontanini/presenterm/pull/376)).
+* Add PHP executor ([#332](https://github.com/mfontanini/presenterm/issues/332)).
+* Add Racket syntax highlighting ([#367](https://github.com/mfontanini/presenterm/issues/367)).
+* Add TOML highlighting ([#361](https://github.com/mfontanini/presenterm/issues/361)).
+
+## Fixes
+
+* Wrap code snippets if they don't fit in terminal ([#320](https://github.com/mfontanini/presenterm/issues/320)).
+* Allow list-themes/acknowledgements to run without path ([#359](https://github.com/mfontanini/presenterm/issues/359)).
+* Translate tabs in code snippets to 4 spaces ([#356](https://github.com/mfontanini/presenterm/issues/356)).
+* Add padding to right of code block wrapped lines ([#354](https://github.com/mfontanini/presenterm/issues/354)).
+* Don't wrap code snippet separator line ([#353](https://github.com/mfontanini/presenterm/issues/353)).
+* Show block quote prefix when wrapping ([#352](https://github.com/mfontanini/presenterm/issues/352)).
+* Don't crash on code block with only hidden-line-prefixed lines 
+  ([#347](https://github.com/mfontanini/presenterm/issues/347)).
+* Canonicalize resources path ([#333](https://github.com/mfontanini/presenterm/issues/333)).
+* Execute script relative to current working directory ([#323](https://github.com/mfontanini/presenterm/issues/323)).
+* Support rendering mermaid charts on windows ([#319](https://github.com/mfontanini/presenterm/issues/319)).
+
+## Improvements
+
+* Add example on how column layouts and pauses interact ([#348](https://github.com/mfontanini/presenterm/issues/348)).
+* Rename `jump_to_vertical_center` -> `jump_to_middle` in docs 
+  ([#342](https://github.com/mfontanini/presenterm/issues/342)).
+* Document `all` snippet highlighting keyword ([#335](https://github.com/mfontanini/presenterm/issues/335)).
+
 # v0.8.0 - 2024-07-29
 
 ## Breaking changes

Cargo.toml

@@ -4,7 +4,7 @@ authors = ["Matias Fontanini"]
 description = "A terminal slideshow presentation tool"
 repository = "https://github.com/mfontanini/presenterm"
 license = "BSD-2-Clause"
-version = "0.8.0"
+version = "0.9.0"
 edition = "2021"
 
 [dependencies]

docs/src/guides/code-highlight.md

@@ -47,6 +47,7 @@ Code highlighting is supported for the following languages:
 * sql
 * swift
 * svelte
+* toml
 * terraform
 * typescript
 * xml
@@ -112,11 +113,30 @@ See this real example of how this looks like.
 
 [![asciicast](https://asciinema.org/a/iCf4f6how1Ux3H8GNzksFUczI.svg)](https://asciinema.org/a/iCf4f6how1Ux3H8GNzksFUczI)
 
+### Including external code snippets
+
+The `file` snippet type can be used to specify an external code snippet that will be included and highlighted as usual. 
+
+~~~markdown
+```file +exec +line_numbers
+path: snippet.rs
+language: rust
+```
+~~~
+
+### Showing a snippet without a background
+
+Using the `+no_background` flag will cause the snippet to have no background. This is useful when combining it with the 
+`+exec_replace` flag described further down.
+
+## Snippet execution
+
 ### Executing code blocks
 
-Annotating a code block with a `+exec` attribute will make it executable. Once you're in a slide that contains an
-executable block, press `control+e` to execute it. The output of the execution will be displayed on a box below the
-code. The code execution is stateful so if you switch to another slide and then go back, you will still see the output.
+Annotating a code block with a `+exec` attribute will make it executable. Pressing `control+e` when viewing a slide that 
+contains an executable block, the code in the snippet will be executed and the output of the execution will be displayed 
+on a box below it. The code execution is stateful so if you switch to another slide and then go back, you will still see 
+the output.
 
 ~~~markdown
 ```bash +exec
@@ -145,10 +165,12 @@ The list of languages that support execution are:
 * lua
 * nushell
 * perl
+* php
 * python
 * ruby
-* rust-script
 * rust
+* rust-script: this highlights as normal Rust but uses [rust-script](https://rust-script.org/) to execute the snippet so 
+it lets you use dependencies.
 * sh
 * zsh
 
@@ -161,6 +183,46 @@ file](configuration.html#custom-snippet-executors).
 
 > **Note**: because this is spawning a process and executing code, you should use this at your own risk.
 
+### Executing and replacing
+
+Similar to `+exec`, `+exec_replace` causes a snippet to be executable but:
+
+* Execution happens automatically without user intervention.
+* The snippet will be automatically replaced with its execution output.
+
+This can be useful to run programs that generate some form of ASCII art that you'd like to generate dynamically.
+
+[![asciicast](https://asciinema.org/a/hklQARZKb5sP5mavL4cGgbYXD.svg)](https://asciinema.org/a/hklQARZKb5sP5mavL4cGgbYXD)
+
+Because of the risk involved in `+exec_replace`, where code gets automatically executed when running a presentation, 
+this requires users to explicitly opt in to it. This can be done by either passing in the `-X` command line parameter
+or setting the `snippet.exec_replace.enable` flag in your configuration file to `true`. 
+
+### Executing snippets that need a TTY
+
+If you're trying to execute a program like `top` that needs to run on a TTY as it renders text, clears the screen, etc, 
+you can use the `+acquire_terminal` modifier on a code already marked as executable with `+exec`. Executing snippets 
+tagged with these two attributes will cause _presenterm_ to suspend execution, the snippet will be invoked giving it the 
+raw terminal to do whatever it needs, and upon its completion _presenterm_ will resume its execution.
+
+[![asciicast](https://asciinema.org/a/AHfuJorCNRR8ZEnfwQSDR5vPT.svg)](https://asciinema.org/a/AHfuJorCNRR8ZEnfwQSDR5vPT)
+
+### Styled execution output
+
+Snippets that generate output which contains escape codes that change the colors or styling of the text will be parsed 
+and displayed respecting those styles. Do note that you may need to force certain tools to use colored output as they 
+will likely not use it by default.
+
+For example, to get colored output when invoking `ls` you can use:
+
+~~~markdown
+```bash +exec
+ls /tmp --color=always
+```
+~~~
+
+The parameter or way to enable this will depend on the tool being invoked.
+
 ### Hiding code lines
 
 When you mark a code snippet as executable via the `+exec` flag, you may not be interested in showing _all the lines_ to 
@@ -192,8 +254,8 @@ golang code snippet that starts with a `/// ` will be hidden.
 ### Pre-rendering 
 
 Some languages support pre-rendering. This means the code block is transformed into something else when the presentation 
-is loaded. The languages that currently support this are _LaTeX_ and _typst_ where the contents of the code block is 
-transformed into an image, allowing you to define formulas as text in your presentation. This can be done by using the 
-`+render` attribute on a code block.
+is loaded. The languages that currently support this are _mermaid_, _LaTeX_, and _typst_ where the contents of the code 
+block is transformed into an image, allowing you to define formulas as text in your presentation. This can be done by 
+using the `+render` attribute on a code block.
 
 See the [LaTeX and typst](latex.html) and [mermaid](mermaid.html) docs for more information.

docs/src/guides/configuration.md

@@ -254,6 +254,9 @@ bindings:
 
   # the key binding to close the application.
   exit: ["<c-c>", "q"]
+
+  # the key binding to suspend the application.
+  suspend: ["<c-z>"]
 ```
 
 You can choose to override any of them. Keep in mind these are overrides so if for example you change `next`, the 
@@ -263,8 +266,9 @@ default won't apply anymore and only what you've defined will be used.
 
 ### Snippet execution
 
-Snippet execution is disabled by default for security reasons. Besides passing in the `-x` command line parameter every 
-time you run _presenterm_, you can also configure this globally for all presentations by setting:
+[Snippet execution](code-highlight.html#executing-code-blocks) is disabled by default for security reasons. Besides 
+passing in the `-x` command line parameter every time you run _presenterm_, you can also configure this globally for all 
+presentations by setting:
 
 ```yaml
 snippet:
@@ -274,6 +278,21 @@ snippet:
 
 **Use this at your own risk**, especially if you're running someone else's presentations!
 
+### Snippet execution + replace
+
+[Snippet execution + replace](code-highlight.html#executing-and-replacing) is disabled by default for security reasons. 
+Similar to `+exec`, this can be enabled by passing in the `-X` command line parameter or configuring it globally by 
+setting:
+
+```yaml
+snippet:
+  exec_replace:
+    enable: true
+```
+
+**Use this at your own risk**. This will cause _presenterm_ to execute code without user intervention so don't blindly 
+enable this and open a presentation unless you trust its origin!
+
 ### Custom snippet executors
 
 If _presenterm_ doesn't support executing code snippets for your language of choice, please [create an 
@@ -293,6 +312,10 @@ snippet:
         environment:
           MY_FAVORITE_ENVIRONMENT_VAR: foo
 
+        # A prefix that indicates a line that starts with it should not be visible but should be executed if the
+        # snippet is marked with `+exec`.
+        hidden_line_prefix: "/// "
+
         # A list of commands that will be ran one by one in the same directory as the snippet is in.
         commands:
           # Compile if first

docs/src/guides/themes.md

@@ -249,9 +249,17 @@ footer:
 
 #### Template
 
-A template footer that lets you put something on the left, center and/or right of the screen. The template strings have 
-access to `{author}` as specified in the front matter, `{current_slide}` and `{total_slides}` which will point to the 
-current and total number of slides:
+A template footer that lets you put something on the left, center and/or right of the screen. The template strings
+can reference `{current_slide}` and `{total_slides}` which will be replaced with the current and total number of slides.
+
+Besides those special variables, any of the attributes defined in the front matter can also be used:
+
+* `title`.
+* `sub_title`.
+* `event`.
+* `location`.
+* `date`.
+* `author`.
 
 ```yaml
 footer:

src/ansi.rs

@@ -52,7 +52,7 @@ impl AnsiSplitter {
 
 struct GraphicsCode<'a>(&'a [u8]);
 
-impl<'a> GraphicsCode<'a> {
+impl GraphicsCode<'_> {
     fn update(&self, style: &mut TextStyle) {
         // RGB mode
         let codes = self.0;

src/media/kitty.rs

@@ -415,7 +415,7 @@ struct ControlCommand<'a, D> {
     tmux: bool,
 }
 
-impl<'a, D: fmt::Display> fmt::Display for ControlCommand<'a, D> {
+impl<D: fmt::Display> fmt::Display for ControlCommand<'_, D> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         if self.tmux {
             write!(f, "\x1bPtmux;\x1b")?;

src/render/highlighting.rs

@@ -178,7 +178,7 @@ pub(crate) struct LanguageHighlighter<'a> {
     highlighter: HighlightLines<'a>,
 }
 
-impl<'a> LanguageHighlighter<'a> {
+impl LanguageHighlighter<'_> {
     pub(crate) fn highlight_line(&mut self, line: &str, block_style: &CodeBlockStyle) -> TextBlock {
         self.style_line(line, block_style)
     }