From 3db1d1c278bf5035fb0c90c4abfd133c6c2f0e7f Mon Sep 17 00:00:00 2001 From: flyingsl0ths Date: Fri, 17 Jun 2022 22:46:18 -0500 Subject: [PATCH 1/2] Add markup language documentation (#1) --- README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 65 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 28b5936..46c4558 100644 --- a/README.md +++ b/README.md @@ -11,25 +11,81 @@ `forest` provides some flexibility in usage of its API: 1. `print`: The most straightforward function, prints to `stdout` -1. `print_to`: Prints to provided `std::FILE*` stream -1. `format`: Obtains formatted text as a `std::string` -1. `format_to`: fully `constexpr` code path that formats text to a provided output iterator -1. `literal`: compile-time alternative for literals +2. `print_to`: Prints to provided `std::FILE*` stream +3. `format`: Obtains formatted text as a `std::string` +4. `format_to`: fully `constexpr` code path that formats text to a provided output iterator +5. `literal`: compile-time alternative for literals [example/forest-example.cpp](example/forest-example.cpp) contains some samples. +## Markup Language + +Below is a description of the markup language used by all functions exposed by the API + +### Open & Closed tags + +Both `open` and `closed` tags behave the same the former is just a shorthand for the latter: + +- Closed tags are of the form `` + +- Open tags are of the form `` + +#### Color Properties + +`R, G, B` can be any number ranging from :zero::arrow_right::five: + +## Style Tags + +| NAME | TAG | ALT. TAG | CLOSED | OPEN | PARAMETERS | +| -------------- | -------------- | -------- | ------------------ | ------------------ | ---------- | +| bold | `` | | :white_check_mark: | :white_check_mark: | :x: | +| italic | `` | | :white_check_mark: | :white_check_mark: | :x: | +| underline | `` | | :white_check_mark: | :white_check_mark: | :x: | +| dim | `` | | :white_check_mark: | :white_check_mark: | :x: | +| blink | `` | | :white_check_mark: | :white_check_mark: | :x: | +| invert | `` | | :white_check_mark: | :white_check_mark: | :x: | +| strike through | `` | | :white_check_mark: | :white_check_mark: | :x: | +| RGB | `` | | :white_check_mark: | :white_check_mark: | `R, G, B` | +| background | `` | `` | :white_check_mark: | :white_check_mark: | `R, G, B` | +| reset | `` | | | :white_check_mark: | :x: | +| clear | `` | | | :white_check_mark: | :x: | + +### Tag Names + +For the most part all tags clearly describe their intent, except for the follwing which may cause some confusion: + +#### RGB + +This tag acts essentially as a way to style the **foreground color** of a string and together with `background` can be used to create a more controlled version of what `inverse` provides + +#### Clear + +Unlike `reset`, which removes all styling apllied to a string, is used to **clear the output** leading up to where it was last used + ## Usage ### Requirements 1. C++17 -1. CMake 3.17+ [optional] +2. CMake 3.17+ [optional] ### Steps 1. Copy [include/forest/forest.hpp](include/forest/forest.hpp) into your build tree, or -1. Use CMake: +2. Use CMake: 1. Import `forest` - 1. Add `forest` to build tree via `add_subdirectory(path/to/forest)`, or - 1. Locate `forest` via `find_package(forest)` (must be installed to a path in `CMAKE_INSTALL_PREFIX`) - 1. Link to `forest` via `target_link_libraries(your_project PRIVATE forest::forest)` (use `PUBLIC` instead to propagate include paths to all dependencies) + 1. Add `forest` to build tree via `add_subdirectory(path/to/forest)`, or + 2. Locate `forest` via `find_package(forest)` (must be installed to a path in `CMAKE_INSTALL_PREFIX`) + 2. Link to `forest` via `target_link_libraries(your_project PRIVATE forest::forest)` (use `PUBLIC` instead to propagate include paths to all dependencies) From f31eab27ae77325b334abdafefbcd510b5acfe85 Mon Sep 17 00:00:00 2001 From: flyingsl0ths Date: Sun, 19 Jun 2022 14:22:20 -0500 Subject: [PATCH 2/2] Improve markup language doc. --- README.md | 100 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 46c4558..aeb7878 100644 --- a/README.md +++ b/README.md @@ -22,45 +22,95 @@ Below is a description of the markup language used by all functions exposed by the API -### Open & Closed tags +### Style -Both `open` and `closed` tags behave the same the former is just a shorthand for the latter: +A style consists of two things -- Closed tags are of the form `` +- Scope -- Open tags are of the form `` + +## Style Types + +There are 3 types of styles + +- **Hint** + +- **Decoration** + +- **Property** + +### Hint + +Refers to a set of styles that are single-use and open scoped + +### Decoration + +Refers to all closed scoped styles + +### Property + +Refers to a set of styles that parameterized over a set of specified values which can be given via the `=` syntax - `...` +- `...` + +**Note** + +**Properties with either open/closed scope can be used interchangeibly within a single group of text** + #### Color Properties -`R, G, B` can be any number ranging from :zero::arrow_right::five: +Styles with color properties are denoted by an `R, G, B` in their properties column in the table below. The set of acceptable values for each color unit is then any number within the range `[0..5]`. For example red would be `...` + +**Note** + +**Specifying a value outside of the allowed range is not an error as all values are effectively clamped** + +## Styles + +| NAME | TAG | ALT. TAG | OPENING TAG | CLOSING TAG | PROPERTIES | TYPE | +| -------------- | -------------- | -------- | ------------------ | ------------------ | ---------- | ------ | +| bold | `` | | :white_check_mark: | :white_check_mark: | :x: | `D` | +| italic | `` | | :white_check_mark: | :white_check_mark: | :x: | `D` | +| underline | `` | | :white_check_mark: | :white_check_mark: | :x: | `D` | +| dim | `` | | :white_check_mark: | :white_check_mark: | :x: | `D` | +| blink | `` | | :white_check_mark: | :white_check_mark: | :x: | `D` | +| invert | `` | | :white_check_mark: | :white_check_mark: | :x: | `D` | +| strike through | `` | | :white_check_mark: | :white_check_mark: | :x: | `D` | +| RGB | `` | | :white_check_mark: | :white_check_mark: | `R, G, B` | `D\|P` | +| background | `` | `` | :white_check_mark: | :white_check_mark: | `R, G, B` | `D\|P` | +| reset | `` | | :white_check_mark: | :x: | :x: | `H` | +| clear | `` | | :white_check_mark: | :x: | :x: | `H` | -## Style Tags +### Table Legend -| NAME | TAG | ALT. TAG | CLOSED | OPEN | PARAMETERS | -| -------------- | -------------- | -------- | ------------------ | ------------------ | ---------- | -| bold | `` | | :white_check_mark: | :white_check_mark: | :x: | -| italic | `` | | :white_check_mark: | :white_check_mark: | :x: | -| underline | `` | | :white_check_mark: | :white_check_mark: | :x: | -| dim | `` | | :white_check_mark: | :white_check_mark: | :x: | -| blink | `` | | :white_check_mark: | :white_check_mark: | :x: | -| invert | `` | | :white_check_mark: | :white_check_mark: | :x: | -| strike through | `` | | :white_check_mark: | :white_check_mark: | :x: | -| RGB | `` | | :white_check_mark: | :white_check_mark: | `R, G, B` | -| background | `` | `` | :white_check_mark: | :white_check_mark: | `R, G, B` | -| reset | `` | | | :white_check_mark: | :x: | -| clear | `` | | | :white_check_mark: | :x: | +Due to there being styles that fall under 1 or more types and the type names being rather long for the table cells, a combination of the first letter of each type separated by a `|` character will be used instead where applicable ### Tag Names @@ -72,7 +122,7 @@ This tag acts essentially as a way to style the **foreground color** of a string #### Clear -Unlike `reset`, which removes all styling apllied to a string, is used to **clear the output** leading up to where it was last used +Unlike `reset`, which removes all styling apllied to a string, is used to **clear the output** (whatever that may be) ## Usage