From c028dabfb5a3cb0ca3507f158c760fa95aa2c59c Mon Sep 17 00:00:00 2001 From: "Zed A. Shaw" Date: Mon, 4 May 2026 01:12:51 -0400 Subject: [PATCH] Better docs. --- README.md | 148 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 136 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index ba6701b..4012cf5 100644 --- a/README.md +++ b/README.md @@ -20,21 +20,145 @@ PowerPoint for my use cases. I mostly need to show text and some videos for a s on a randomly attached monitor while also looking at a status screen on another one. Currently you can run `besos.exe` (it might work on other platforms, let me know) and give it a -`.md` file formatted to have slides. See `samples/01-a-good-first-program.md` which is a quick -example from one of my courses. I'll have more docs on this in the future but so far: +`.md` file formatted to have slides. See `samples/about-bezos.md` which is a quick +example from one of my courses. -1. Metadata at the top is json. +## Features + +1. Metadata at the top is json which can set fonts, sizes, etc. 2. Slides start with `===`. 3. Each slide is separated with `---`. -4. Each slide can also have json metadata. You can currently set the background color with `{"bg_color": [255, 0, 0, 255]}` but it's jank right now so put the `{` and `}` on different lines. -4. First line of slide is title. +4. Each slide can also have json metadata for font sizes, shaders, colors, etc. +4. Use `# Title` on the first line for the title. 5. Everything after is content. -6. No actual markdown is being done currently. +6. Hot reloading mostly works. +7. There's a remote control program `bezos_ctl` you can use from the command line. +8. There's one for windows named `bezos_ctrl` that won't open a `cmd.exe`. +9. You can apply shaders to slides. +10. Horrible performance for now. +11. Separate control window to see current/next slides and control the present window. +12. The ability to easily move the present window to another monitor (only tested on Windows). + +# Supported "Markdown" + +It's barely markdown at this point, but look in `samples/about-bezos.md` for a demo of everything. +The features supported are: + +`{}` +: JSON meta data can go at the top of the deck and on each slide. Settings at the top are defaults +and you change then in the slides. + +`#` +: This tags the line as the title. You can change its style using `"title_"` options. + +`Plain Text` +: Just put lines of text. + +`*` +: Bullet points are supported, but nothing fancy. + +`!(assets/some_image.jpg)` +: Images are supported and should work with at least `.png` and `.jpg`. + +`![cell_name](assets/some_image.jpg)` +: You can explicitly place an image in a specific cell by giving the cell name where you'd normally +put alt text. + +That's it. The parser is also very basic and gives terrible errors. If you make a change and +nothing reloads then check the logs in the console. + +## Available Metadata Options + +## Shaders + +You can apply a shader to your slide with `"shader": "name"`. The shaders are configured in +`assets/shaders.json` but I may change this to be just a file. + +Here's an example from `samples/about-bezos.md`: + +``` +{ + "shader": "flame", + "bg_color": [80, 0, 0, 255], + "layout": "no_title", + "font_size": 200 +} +I Made a +PowerPoint +Killer +``` + +I'm actually not very good at writing shaders, but I'm sure you'll cook up something really great. + +## Layout Language + +The layouts are defined in `assets/layouts.json` and use my layout description language from +[lel-guecs](https://git.zedshaw.games/games/lel-guecs). + +Layout Expression Language (lel) is a small +language that describes how ragged arrays of cells are structured. The idea is that you define +where stuff goes separate from the stuff that goes there. This makes it easier to work out common +UI layouts and reuse them, and also makes your code _way_ simpler. Instead of crazy nested objects +inside objects you just create a layout and put stuff in it like a container. + +I'll document this further in a later release, but ifyou look at `"default_ui"` in +`assets/layouts.json" you see this: + +``` +"[t_left|t_center|t_right]", +"[*%(100,600)slide]", +"[_]", +"[_]", +"[_]", +"[_]", +"[_]", +"[=title|=*%(200,100)description|_|_|_]" +``` + +This is multiple strings only because JSON doesn't have a multiline string. This is converted into a +single string to define the layout. + +The `[]` Creates a single cell. The `[t_left]` creates a cell name `t_left`. The `[*%(100,600)slide]` says, "Expand (`*`) to fill percent (`%`) 100 wide by 600 long." In this case the `slide` cell will take up 1 column and 6 rows. If you see `=` that means to center it. + +## Command Line Remote + +There's a `builddir/bezos_cli` that allows for remote control of your presentation. It can do most +things the control window does. Here's the options: + +`-L`/`-R` +: Move the present window to the "Left" or "Right" screen. + +`-N`/`-P` +: Next and Previous slide. + +`-q` +: Quit. + +`-f` +: Toggle full screen. + +`-p` +: What port to use. + +> __WARNING__ This works by opening a UDP port on port 9898. If it doesn't work that's probably +> why. Also, it should only be on localhost but let me know if it's getting it wrong. + +## `bezos_cli` vs. `bezos_ctrl` + +You may notice there's a `bezos_cli` and `bezos_ctrl` + but *only on Windows*. This is because Windows makes a distinction between "console" apps and +"windows" apps. + +The `bezos_cli` is what you want when using it from the command line or on Unix systems. It just +works like you think it does and the code is in `src/bezos_ctl.cpp`. + +The `bezos_ctrl` is compiled as a `windows` subsystem app so when run it does _no console output_. +This lets you run it in things like Stream Deck and other launchers without popping open a `cmd.exe` +window to run it. + +## Future Features -## Future Plans +I'm pretty good with this so far but I may tinker with it more later. If you have ideas or requests +send them to help@learncodethehardway.com and I'll take a look. -1. Control window will show the current and next slide, speaker notes, and other information. -2. Buttons to control things. -3. Ability to trigger sounds. -4. Ability to style the presentation with metadata, so for different fonts and sizes. -5. Ability to pick different layouts and to create your own layouts right in the presentation. +Or...just write your own. This ain't that hard.