[Feature] Provide a Way to Escape Blocks of Content about termimad HOT 24 CLOSED

@zicklag FYI I just published 0.7.4 with templates

But it's still not what you need. I must work a little more to determine the exact specification to support named placeholders, whole texts (not just inline snippets), placeholders covering several lines, etc.

from termimad.

Templating with names and sub-templates is coming soon.

static TEMPLATE: &str = r#"
# ${app-name} v${app-version}
**${app-name}** is *fantastic*!
## Modules
In a table:
|:-:|:-:|:-:|
|**name**|**path**|**description**|
|-:|:-:|:-|
${module-rows
|**${module-name}**|`${app-version}/${module-key}`|${module-description}|
}
|-|-|-|
and the same data in another form:
${module-rows
### ${module-name} (${module-key})
${module-description}
}
## Items
${formatted-items
* **${item-name}:** `${item-code}`
}
"#;

fn main() -> Result<()> {
    let skin = make_skin();
    let text_template = TextTemplate::from(TEMPLATE);
    let mut expander = text_template.expander();
    expander
        .set("app-name", "MyApp")
        .set("app-version", "42");
    expander.sub("module-rows")
        .set("module-name", "lazy-regex")
        .set("module-key", "lrex")
        .set("module-description", "eases regexes");
    expander.sub("module-rows")
        .set("module-name", "termimad")
        .set("module-key", "tmd")
        .set("module-description", "do things on terminal");
    expander.sub("formatted-items")
        .set("item-name", "3*5")
        .set("item-code", "187/12");
    expander.sub("formatted-items")
        .set("item-name", "π")
        .set("item-code", "22/7");
    let text = expander.expand();
    let (width, _) = terminal_size();
    let fmt_text = FmtText::from_text(&skin, text, Some(width as usize));
    println!("{}", &fmt_text);
    Ok(())
}

from termimad.

@zicklag I should make that clearer in the documentation: The TextTemplate is part of the Minimad library which is developed for Termimad and contains the Markdown making parts.

You should have a look at how templates are used in broot: https://github.com/Canop/broot/blob/master/src/help_content.rs

You'll need this in your dependencies:

minimad = "0.5.0"
termimad = "0.8.0"

from termimad.

The current lifetime design of Minimad and Termimad minimizes memory and string copies but make a few things more complicated.
And when creating MadView, I had this in mind but not the templates.
There should probably be some new tool replacing MadView, or maybe some guidelines, to help deal with those problems.
But I don't want to clutter the lib with redundant structs so I'll have to think a little more before.

Side note: rebuilding everything at each render is reasonable: it's fast enough (normally less than a ms).

from termimad.

You might be interested by that:

fn main() {
    let mut skin = MadSkin::default();
    skin.bold.set_fg(Yellow);
    skin.inline_code.add_attr(Reverse);
    skin.bold.set_fg(Yellow);

    // with interpolation, after parsing
    mad_print!(&skin, "*count:* **$0**", "27"); // note that only &str is supported now
    println!();

    // another one: see that the arguments aren't interpreted as markdown,
    //  which is convenient for user supplied texts
    mad_print!(&skin, "**Formula for $1:** ` $0 `", "π*r*²", "disk");
    println!();

    // using any Write:
    mad_write!(&mut std::io::stdout(), &skin, "**$0** is *$1*\n", "Meow", "crazy").unwrap();
}

I hope to publish it this weekend (testing it in broot).

In short: mad_print takes as argument a template interpreted as markdown but accepting replacements. The following arguments replace $0, $1, etc. and aren't interpreted as markdown (that's the whole point). The template is also compiled only once (using lazy_static).

from termimad.

That looks great. 👍

One note: I would want to be able to do keyword arguments in the template. So something like $help_message in addition to the $0 syntax.

from termimad.

Right now placeholders are $0 to $9 only but accept omissions, repetitions and arbitrary order.

Are named placeholders really necessary ?

from termimad.

I have my docs in separate files like this that I include using include_str! so having a $0 in that would be a little out of context.

Still it wouldn't be a problem for me to have {{help_message}} in the external markdown file and then substitute that with $0 before passing that to the mad_write! macro. That would probably work just fine and not require the keyword replacement in the macro, if I'm not missing something.

from termimad.

That wouldn't work with the mad_ macros, as the templace is of type &'static str (so that it's compiled only once).

But:

• there's a Template type directly usable without macro (losing the convenience of the one liner but probably more suited to big texts anyway)
• I'll look into named placeholders, I guess...

from termimad.

It probably wouldn't be bad to use the Template type if we had to. It is a more involved setup to use a separate file for the doc anyway.

from termimad.

Ooh, that looks pretty neat. Nice work. That will be more than I need. :)

from termimad.

@zicklag I've published a new version with a description : https://github.com/Canop/termimad#templates

It should close this issue.

Please tell me how it works for you, though.

from termimad.

Awesome, I can't wait to try it out. I'll let you know how it goes.

from termimad.

It seems like there is no TextTemplate type that I can find in the repo or docs.rs. Did those changes somehow get left out of the Git commit?

from termimad.

Oh, perfect thanks.

from termimad.

I got it working! Thanks for the help!

The usage is substituted into the template from the clap long help message.

Some of the terminal control and rendering stuff took a little bit of experimentation for me to get right, but now it is working nicely.

from termimad.

Oh that's pretty. I'll use it for a gallery if I can get a few other ones.

I'd be interested by suggestions regarding the documentation.

from termimad.

I'll take some more pictures when I get some more documentation written. 😉.

The biggest problem I had API-wise was that I couldn't use the MadView with the template because MadView takes a markdown string instead of a Text. Looking at your code from broot I did figure out how to reinitialize the Area, FmtText, and TextView ever frame and achieve the same effect.

from termimad.

Yeah, the current design isn't bad or anything, it just isn't immediately apparent as a newbie. Also I'm new to terminal rendering so I had some confusion of when to flush the writer, etc.

There should probably be some new tool replacing MadView, or maybe some guidelines, to help deal with those problems.

That would be cool.

Side note: rebuilding everything at each render is reasonable: it's fast enough (normally less than a ms).

OK, thanks for the assurance of that. :) Also, I had some issue where, while scrolling, some of the text would get left over from previous lines in the command help. It only seems to happen in the command output.

Anyway, I just ended up clearing the whole screen at every update. Is that a decent solution? It caused more flickering, but I'm on a slow SSH connection at the moment, so I think it probably won't be a problem in general.

from termimad.

No, you should not clean the whole screen at every render, the flickering isn't acceptable in my opinion.

There's a case of leftovers which happens when you resize the screen. That's why I usually do a screen cleaning at resize.

If your screenshot isn't related to terminal resizing, then an investigation is in order (and I can help if you build a minimal reproducible example). And if it's confirmed, this should be another issue.

from termimad.

OK, cool. I'll try to get a minimal example for you soonish.

from termimad.

Here is a minimal demonstration: https://github.com/katharostech/termimad/tree/termimad-test/examples/colored-template-scroll. Maybe not completely minimal, but it is simple ( tell me if you need me to trim it down furthur ).

The problem only happens when the text has to wrap a lot, and it only happens when color is enabled:

Edit: Also, I'm pretty sure this was happening without the template, too, when I was just using format! to get the help message in there.

from termimad.

I just published Termimad 0.8.1 which should solve the problem.

Side note: crossterm has a function to get the size of the terminal, you don't need to import another crate for that.

from termimad.

That worked! Thanks for the fix. 😃

Thanks for the crossterm tip. 👍 I'm really liking crossterm. Very nice API.

from termimad.