From 86c933de354baa1ffbd4d2ae3cba24d7d8cb4e83 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Wed, 22 Jun 2022 09:25:03 -0300 Subject: [PATCH 01/15] Update builder specification for v0.11.0 --- builder.md | 132 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 105 insertions(+), 27 deletions(-) diff --git a/builder.md b/builder.md index cf7a1d4..9785f13 100644 --- a/builder.md +++ b/builder.md @@ -1,41 +1,118 @@ # Builder Guidelines -**Version 0.10.0** +**Version 0.11.0** -A base16 builder is an application that can build syntax highlighting definition files for text editors by using base16 scheme files which contain a collection of colours and base16 template files which contain syntax highlighting rules. +*The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).* -Builders are designed for theme maintainers' ease of use. Theme maintainers should provide built versions of their theme so the end user doesn't need to be aware of the builder. +## Introduction -## File Structure +A base16 builder is, essentially, an application that can build base16 +templates with base16 [schemes](./styling.md). -### Schemes Repository +A template is a "blueprint" that specifies a file representing how to use the +16 base16 colors with that specific software/format. For example: a +[colorscheme template for vim](https://github.com/base16-project/base16-vim). -The schemes repo should either be stored in a common location (perhaps referred to by environment variable or command line flag) or dynamically embedded in the builder. +A scheme is a color palette that consists of 16 colors (hence the name). For +example: [the solarized scheme](https://github.com/base16-project/base16-schemes/blob/main/solarized-dark.yaml) -- `/*.yaml` +Builders are designed for lower-level ("plumbing") usage, specifically for +scripting and as component to build more complex base16 applications, designed +for end users ("porcelain"). -### Template Repository +Template maintainers SHOULD provide built versions (with all existing scheme) +so the end user doesn't need to be aware of the builder. -Each template repository should have a templates folder containing a config.yaml and any needed mustache template files. +## Interface -- `/templates/*.mustache` - A template file (there may be multiples of these) -- `/templates/config.yaml` - A template configuration file +All base16 builders MUST provide a single feature: building a template using 1 or more schemes. -## Workflow -The first thing a builder needs to do is parse all the scheme files from the schemes repository (as defined in the [file guidelines](https://github.com/chriskempson/base16/blob/master/file.md)). All files matching the pattern `*.yaml` should be loaded from the root of the schemes repository. +### CLI -When building a target template repository, a base16 builder should first clear out any old output. Next, for all templates defined in the template repo's config file (located at `/templates/config.yaml`), the builder should iterate through all the defined schemes and output matching files. The built filename should look like `[output-dir]/base16-[slug][extension]`, where the slug is taken from the scheme filename made lowercase with spaces replaced with dashes and both the extension and output-dir are taken from `/template/config.yaml`. +It is REQUIRED that that this functionality is exposed as binary CLI executable +with the exact interface described below. -In the case where schemes share the same slug, a builder will overwrite files previously generated from the template. Should this happen, a builder should show warning messages listing the overwritten files. +To be fully compliant, a builder CLI interface MUST NOT include any other +feature, option, argument, or deviance from the expected interface and +behaviour of the program. + + + +The CLI interface MUST work without relying on any network connection. + +```bash +base16 TEMPLATES-DIRECTORY SCHEME-FILE ... +``` + +`TEMPLATES-DIRETORY` being a directory containing a `config.yaml`, as well as at +least one `.mustache` template. These are usually named `templates` on all +base16 template repositories. + +`SCHEME-FILE` being one or more `.yaml` scheme file. The main source for these +is the [base16-schemes](https://github.com/base16-project/base16-schemes) +repository. + +The program MAY offer a single `--debug | -d` option for increasing log +verbosity. These are considered implementation detail and each author SHOULD +implement them as they see fit. + +### Library + +The compliant base16 builder software MAY also expose a software library other +developers may use to assist developing more complex base16-compatible +software. + +This exposed library, or any internal code, has no required structure or usage. + +The author MAY choose how they will expose these functionalities to the caller, +according to their preferences and SHOULD follow best practices on their +respective programming languages. + +It is RECOMMENDED that builders follow semantic versioning for their library +interface. + +The author MAY implement additional features that are exposed through the +library, as long as it does not affect the CLI functionality compliance. + +## Output and behaviour + +**Note**: As the CLI is not intended for usual human usage, all outputted text +messages are considered implementation detail, so the author MAY output +whatever they prefer (or no message at all). If needed, scripts using the +builder SHOULD check for return codes (specified below) instead of messages. + +For all templates defined in the template config file (`config.yaml`, inside +the specified template directory), the builder MUST iterate through all the +defined schemes and output matching files. + +The built filename should look like [output-dir]/base16-[slug][extension], +where the slug is taken from the scheme filename made lowercase with spaces +replaced with dashes and both the extension and output-dir are taken from +`config.yaml`. + +The builder MUST check for the (unusual) case where schemes share the same +slug, in this case the program MUST exit with code `1` and MAY output an error +message. + +If the build fails for whatever other reasons, the program MUST exit with code +`2` and MAY output an error message. ## Template Variables -A builder should provide the following variables to a template file: +A builder MUST provide the following variables to the template files it +processes: - `scheme-name` - obtained from the scheme file - `scheme-author` - obtained from the scheme file - `scheme-slug` - obtained from the scheme filename, as described above + +- `base00-hex` to `base0F-hex` - obtained from the scheme file e.g "7cafc2" - `base00-hex-r` to `base0F-hex-r` - built from the hex value in the scheme file e.g "7c" - `base00-hex-g` to `base0F-hex-g` - built from the hex value in the scheme file e.g "af" - `base00-hex-b` to `base0F-hex-b` - built from the hex value in the scheme file e.g "c2" +- `base00-hex-bgr` to `base0F-hex-bgr` - built from a reversed version of all the hex values e.g "c2af7c" + - `base00-rgb-r` to `base0F-rgb-r` - converted from the hex value in the scheme file e.g "124" - `base00-rgb-g` to `base0F-rgb-g` - converted from the hex value in the scheme file e.g "175" - `base00-rgb-b` to `base0F-rgb-b` - converted from the hex value in the scheme file e.g "194" @@ -43,15 +120,16 @@ A builder should provide the following variables to a template file: - `base00-dec-g` to `base0F-dec-g` - converted from the rgb value in the scheme file e.g "0.50..." - `base00-dec-b` to `base0F-dec-b` - converted from the rgb value in the scheme file e.g "0.21..." -Builders should also provide the following variables for convenience: - -- `base00-hex` to `base0F-hex` - obtained from the scheme file e.g "7cafc2" -- `base00-hex-bgr` to `base0F-hex-bgr` - built from a reversed version of all the hex values e.g "c2af7c" - -## Code Structure -There is no outline for a recommended code structure that a base16 theme builder should follow but a design goal should be to keep the application as simple as possible providing only the functionality described in this document. If you feel you have a great idea for additional functionality please raise an issue in the [base16 repository](https://github.com/chriskempson/base16). - ## Considerations -Mustache was chosen as the templating language due to its simplicity and widespread adoption across languages. YAML was chosen to describe scheme and configuration files for the same reasons. - -The core scheme repository was based off the single scheme repository so builders supporting v0.8-v0.9 of the spec can continue to function without changes. +Mustache was chosen as the templating language due to its simplicity and +widespread adoption across languages. YAML was chosen to describe scheme and +configuration files for the same reasons. + +The core scheme repository was based off the single scheme repository so +builders supporting v0.8-v0.9 of the spec can continue to function without +changes. + +The revised builder functionality specification introduced in v0.11 did not +introduce any changes to schemes or templates, so no changes to these are +needed Older builders will continue to work, but authors are encouraged to +implement the new, simpler and more consistent, specification. From c4b5397b078bb02520700cf447594f94c4da2f22 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Wed, 22 Jun 2022 09:32:08 -0300 Subject: [PATCH 02/15] info about binary name --- builder.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/builder.md b/builder.md index 9785f13..69142ba 100644 --- a/builder.md +++ b/builder.md @@ -33,6 +33,9 @@ All base16 builders MUST provide a single feature: building a template using 1 o It is REQUIRED that that this functionality is exposed as binary CLI executable with the exact interface described below. +The binary name SHOULD contain `base16`, but is otherwise left as a choice to +the author. + To be fully compliant, a builder CLI interface MUST NOT include any other feature, option, argument, or deviance from the expected interface and behaviour of the program. From 5adbd9f89c43aa1db691e43076cdc827bac64701 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Wed, 22 Jun 2022 09:39:49 -0300 Subject: [PATCH 03/15] add info about managers --- builder.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/builder.md b/builder.md index 69142ba..9401185 100644 --- a/builder.md +++ b/builder.md @@ -18,8 +18,12 @@ A scheme is a color palette that consists of 16 colors (hence the name). For example: [the solarized scheme](https://github.com/base16-project/base16-schemes/blob/main/solarized-dark.yaml) Builders are designed for lower-level ("plumbing") usage, specifically for -scripting and as component to build more complex base16 applications, designed -for end users ("porcelain"). +scripting and as component to build more complex base16 applications. + +The more complex apps designed for end users ("porcelain") are usually referred +to as **managers**, and they don't need to follow any standard besides helping +with base16 theming somehow, in a way that makes sense for their intended +usecase. Template maintainers SHOULD provide built versions (with all existing scheme) so the end user doesn't need to be aware of the builder. From a6fea521ac2e8a36b599d06b2faa97454febdc87 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Wed, 22 Jun 2022 09:43:42 -0300 Subject: [PATCH 04/15] specify that no additional variables are allowed, to avoid incompatibility --- builder.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/builder.md b/builder.md index 9401185..d0027d2 100644 --- a/builder.md +++ b/builder.md @@ -107,8 +107,8 @@ If the build fails for whatever other reasons, the program MUST exit with code `2` and MAY output an error message. ## Template Variables -A builder MUST provide the following variables to the template files it -processes: +A builder MUST provide the following, and no others, variables to the template +files it processes: - `scheme-name` - obtained from the scheme file - `scheme-author` - obtained from the scheme file From 4887ee3ad42adc2e8982c170cb15018487b85d59 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sat, 25 Jun 2022 18:29:41 -0300 Subject: [PATCH 05/15] fix typo Co-authored-by: Jamy --- builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builder.md b/builder.md index d0027d2..7d1b7e2 100644 --- a/builder.md +++ b/builder.md @@ -53,7 +53,7 @@ The CLI interface MUST work without relying on any network connection. base16 TEMPLATES-DIRECTORY SCHEME-FILE ... ``` -`TEMPLATES-DIRETORY` being a directory containing a `config.yaml`, as well as at +`TEMPLATES-DIRECTORY` being a directory containing a `config.yaml`, as well as at least one `.mustache` template. These are usually named `templates` on all base16 template repositories. From 5dfd46bd81a4afc075ba5a58642132f5c176b8b6 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sat, 25 Jun 2022 18:45:48 -0300 Subject: [PATCH 06/15] add missing period Co-authored-by: Jamy --- builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builder.md b/builder.md index 7d1b7e2..e6a966c 100644 --- a/builder.md +++ b/builder.md @@ -138,5 +138,5 @@ changes. The revised builder functionality specification introduced in v0.11 did not introduce any changes to schemes or templates, so no changes to these are -needed Older builders will continue to work, but authors are encouraged to +needed. Older builders will continue to work, but authors are encouraged to implement the new, simpler and more consistent, specification. From ebbb8731e4f8d528a29246cedbe49982c590b3d7 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sat, 25 Jun 2022 19:29:15 -0300 Subject: [PATCH 07/15] add optional help and version options --- builder.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/builder.md b/builder.md index e6a966c..ef6c051 100644 --- a/builder.md +++ b/builder.md @@ -61,9 +61,16 @@ base16 template repositories. is the [base16-schemes](https://github.com/base16-project/base16-schemes) repository. -The program MAY offer a single `--debug | -d` option for increasing log -verbosity. These are considered implementation detail and each author SHOULD -implement them as they see fit. +The program MAY also offer the following options: + +- `--debug | -d` option(s) for increasing log verbosity; +- `--version | -v` option to output its current running version; +- `--help | -h` option to output usage information directly or by opening the + manpage. + +These three options have output that is considered implementation detail, not +intended to be scripted with. Thus each author SHOULD implement them as they +see fit. ### Library From dcf7f47c78906418ffa03c366be27e6bc2a4ba3f Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sun, 26 Jun 2022 22:33:44 -0300 Subject: [PATCH 08/15] clarify reference and extended builders, few adjustments and trims --- builder.md | 146 +++++++++++++++++++++++++++++------------------------ 1 file changed, 79 insertions(+), 67 deletions(-) diff --git a/builder.md b/builder.md index ef6c051..b95fac5 100644 --- a/builder.md +++ b/builder.md @@ -1,41 +1,74 @@ -# Builder Guidelines +# Base16 builder specification **Version 0.11.0** *The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).* -## Introduction +## 1. Introduction -A base16 builder is, essentially, an application that can build base16 -templates with base16 [schemes](./styling.md). +"Building" refers to replacing placeholders on base16 _[template +files](./file.md)_ with colors from base16 _[schemes](./styling.md)_. -A template is a "blueprint" that specifies a file representing how to use the -16 base16 colors with that specific software/format. For example: a -[colorscheme template for vim](https://github.com/base16-project/base16-vim). +A template is a mustache file that acts as a "blueprint": it represents how to +output the scheme into other file formats, or (more commonly) how to output a +configuration file to theme a specific software. For example: a [vim +template](https://github.com/base16-project/base16-vim/blob/main/templates/default.mustache). -A scheme is a color palette that consists of 16 colors (hence the name). For -example: [the solarized scheme](https://github.com/base16-project/base16-schemes/blob/main/solarized-dark.yaml) +A scheme is a yaml file that represents a palette of 16 colors: to be replaced +on the placeholders the template files hold. For example: the [solarized +scheme](https://github.com/base16-project/base16-schemes/blob/main/solarized-dark.yaml) -Builders are designed for lower-level ("plumbing") usage, specifically for -scripting and as component to build more complex base16 applications. +A base16 builder is, essentially, an application that somehow implements the +_building_ feature specification. -The more complex apps designed for end users ("porcelain") are usually referred -to as **managers**, and they don't need to follow any standard besides helping -with base16 theming somehow, in a way that makes sense for their intended -usecase. +Builders are categorized into: -Template maintainers SHOULD provide built versions (with all existing scheme) -so the end user doesn't need to be aware of the builder. +- _reference tooling_: These follow the spec closely and are + designed for unopinionated lower-level ("plumbing") usage, specifically for + scripting and as component to build more complex base16 applications. High + quality reference builders will usually be adopted by the base16-project + organization; +- _extended tooling_: These are built for end users and are usually tailored + for a usecase. This includes GUI apps, ergonomical CLI tools, scheme + managers, web apps, and more. These apps are encouraged to use (or create) + reference implementations as libraries, but may also implement the builder + feature themselves. All of the following `MUST`s can be replaced by `SHOULD`s + when writing this kind of tooling. -## Interface +## 2. Template variables spec -All base16 builders MUST provide a single feature: building a template using 1 or more schemes. +A builder tool MUST provide the following variables, and no others, to the +template files it processes: -### CLI +- `scheme-name` - obtained from the scheme file +- `scheme-author` - obtained from the scheme file +- `scheme-slug` - obtained from the scheme filename, as described above + +- `base00-hex` to `base0F-hex` - obtained from the scheme file e.g "7cafc2" +- `base00-hex-r` to `base0F-hex-r` - built from the hex value in the scheme file e.g "7c" +- `base00-hex-g` to `base0F-hex-g` - built from the hex value in the scheme file e.g "af" +- `base00-hex-b` to `base0F-hex-b` - built from the hex value in the scheme file e.g "c2" +- `base00-hex-bgr` to `base0F-hex-bgr` - built from a reversed version of all the hex values e.g "c2af7c" + +- `base00-rgb-r` to `base0F-rgb-r` - converted from the hex value in the scheme file e.g "124" +- `base00-rgb-g` to `base0F-rgb-g` - converted from the hex value in the scheme file e.g "175" +- `base00-rgb-b` to `base0F-rgb-b` - converted from the hex value in the scheme file e.g "194" +- `base00-dec-r` to `base0F-dec-r` - converted from the rgb value in the scheme file e.g "0.87..." +- `base00-dec-g` to `base0F-dec-g` - converted from the rgb value in the scheme file e.g "0.50..." +- `base00-dec-b` to `base0F-dec-b` - converted from the rgb value in the scheme file e.g "0.21..." + +## 3. Interface + +All base16 reference builders MUST provide a single feature: building a +template using 1 or more schemes. + +This section is not relevant to extended tooling, which will have its own +interface fitting their intended usecases. You should jump to section `4`. + +It is REQUIRED that this functionality is exposed by one (or both) of the following: -It is REQUIRED that that this functionality is exposed as binary CLI executable -with the exact interface described below. +### 3.1. CLI The binary name SHOULD contain `base16`, but is otherwise left as a choice to the author. @@ -72,69 +105,48 @@ These three options have output that is considered implementation detail, not intended to be scripted with. Thus each author SHOULD implement them as they see fit. -### Library +### 3.2. Library -The compliant base16 builder software MAY also expose a software library other -developers may use to assist developing more complex base16-compatible -software. +The other option is exposing a software library other developers may use to +assist developing more complex base16-compatible tooling. -This exposed library, or any internal code, has no required structure or usage. +As above, the library MUST a single feature: building templates. -The author MAY choose how they will expose these functionalities to the caller, -according to their preferences and SHOULD follow best practices on their -respective programming languages. +This exposed library, or any internal code, has no specific required structure. -It is RECOMMENDED that builders follow semantic versioning for their library -interface. +The author MAY choose how (through a class, single function, etc) they will +expose these functionalities to the caller, according to their judegment. -The author MAY implement additional features that are exposed through the -library, as long as it does not affect the CLI functionality compliance. +They SHOULD try to achieve an ergonomical interface and follow the best +practices on their respective programming languages. -## Output and behaviour +Official reference implementations will follow semantic versioning matching +this spec, in the format: `-builder_revision`. -**Note**: As the CLI is not intended for usual human usage, all outputted text -messages are considered implementation detail, so the author MAY output -whatever they prefer (or no message at all). If needed, scripts using the -builder SHOULD check for return codes (specified below) instead of messages. +## 4. Output and behaviour + +**Note**: All text outputted by the CLI binary is considered implementation +detail, so the author MAY output whatever they prefer (or no message at all). +If needed, scripts using the builder SHOULD check for return codes (specified +below) instead of messages. For all templates defined in the template config file (`config.yaml`, inside the specified template directory), the builder MUST iterate through all the defined schemes and output matching files. -The built filename should look like [output-dir]/base16-[slug][extension], +The built filename MUST look like `/base16-`, where the slug is taken from the scheme filename made lowercase with spaces replaced with dashes and both the extension and output-dir are taken from `config.yaml`. -The builder MUST check for the (unusual) case where schemes share the same -slug, in this case the program MUST exit with code `1` and MAY output an error -message. - -If the build fails for whatever other reasons, the program MUST exit with code -`2` and MAY output an error message. - -## Template Variables -A builder MUST provide the following, and no others, variables to the template -files it processes: - -- `scheme-name` - obtained from the scheme file -- `scheme-author` - obtained from the scheme file -- `scheme-slug` - obtained from the scheme filename, as described above +If the build fails for any reasons, the program MUST exit with code `1` and MAY +output an error message. This is not exhaustive and new exit codes might be +added in the future to account for specific errors, so scripters catching +generic errors SHOULD check for non-zero status. -- `base00-hex` to `base0F-hex` - obtained from the scheme file e.g "7cafc2" -- `base00-hex-r` to `base0F-hex-r` - built from the hex value in the scheme file e.g "7c" -- `base00-hex-g` to `base0F-hex-g` - built from the hex value in the scheme file e.g "af" -- `base00-hex-b` to `base0F-hex-b` - built from the hex value in the scheme file e.g "c2" -- `base00-hex-bgr` to `base0F-hex-bgr` - built from a reversed version of all the hex values e.g "c2af7c" - -- `base00-rgb-r` to `base0F-rgb-r` - converted from the hex value in the scheme file e.g "124" -- `base00-rgb-g` to `base0F-rgb-g` - converted from the hex value in the scheme file e.g "175" -- `base00-rgb-b` to `base0F-rgb-b` - converted from the hex value in the scheme file e.g "194" -- `base00-dec-r` to `base0F-dec-r` - converted from the rgb value in the scheme file e.g "0.87..." -- `base00-dec-g` to `base0F-dec-g` - converted from the rgb value in the scheme file e.g "0.50..." -- `base00-dec-b` to `base0F-dec-b` - converted from the rgb value in the scheme file e.g "0.21..." +Otherwise, the program MUST exit with code `0` and an OPTIONAL success message. -## Considerations +## 5. Considerations Mustache was chosen as the templating language due to its simplicity and widespread adoption across languages. YAML was chosen to describe scheme and configuration files for the same reasons. From 88c6f149b06d8fdf559866d4949738e9bf0fff1f Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sun, 26 Jun 2022 22:37:15 -0300 Subject: [PATCH 09/15] specify that extended tooling may expose the reference CLI --- builder.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/builder.md b/builder.md index b95fac5..dff0518 100644 --- a/builder.md +++ b/builder.md @@ -63,8 +63,10 @@ template files it processes: All base16 reference builders MUST provide a single feature: building a template using 1 or more schemes. -This section is not relevant to extended tooling, which will have its own -interface fitting their intended usecases. You should jump to section `4`. +This section (`3`) is not relevant to extended tooling, which will have its own +interface fitting their intended usecases, altough they MAY expose the +reference CLI interface (through a `build` subcommand, for example) and/or a +library, if desired. It is REQUIRED that this functionality is exposed by one (or both) of the following: From 701454b7be6a8896a423654247e205e12c9c2553 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sun, 26 Jun 2022 23:13:17 -0300 Subject: [PATCH 10/15] move outputs to CLI section, fix heading levels --- builder.md | 65 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/builder.md b/builder.md index dff0518..f2e5c47 100644 --- a/builder.md +++ b/builder.md @@ -44,6 +44,7 @@ template files it processes: - `scheme-name` - obtained from the scheme file - `scheme-author` - obtained from the scheme file - `scheme-slug` - obtained from the scheme filename, as described above +- `scheme-kind` - either "light" or "dark", calculated from the `base00` color - `base00-hex` to `base0F-hex` - obtained from the scheme file e.g "7cafc2" - `base00-hex-r` to `base0F-hex-r` - built from the hex value in the scheme file e.g "7c" @@ -79,13 +80,14 @@ To be fully compliant, a builder CLI interface MUST NOT include any other feature, option, argument, or deviance from the expected interface and behaviour of the program. +#### 3.1.1 CLI Arguments and options The CLI interface MUST work without relying on any network connection. ```bash -base16 TEMPLATES-DIRECTORY SCHEME-FILE ... +base16 ... ``` `TEMPLATES-DIRECTORY` being a directory containing a `config.yaml`, as well as at @@ -107,25 +109,7 @@ These three options have output that is considered implementation detail, not intended to be scripted with. Thus each author SHOULD implement them as they see fit. -### 3.2. Library - -The other option is exposing a software library other developers may use to -assist developing more complex base16-compatible tooling. - -As above, the library MUST a single feature: building templates. - -This exposed library, or any internal code, has no specific required structure. - -The author MAY choose how (through a class, single function, etc) they will -expose these functionalities to the caller, according to their judegment. - -They SHOULD try to achieve an ergonomical interface and follow the best -practices on their respective programming languages. - -Official reference implementations will follow semantic versioning matching -this spec, in the format: `-builder_revision`. - -## 4. Output and behaviour +#### 3.1.2. CLI output and behaviour **Note**: All text outputted by the CLI binary is considered implementation detail, so the author MAY output whatever they prefer (or no message at all). @@ -133,12 +117,13 @@ If needed, scripts using the builder SHOULD check for return codes (specified below) instead of messages. For all templates defined in the template config file (`config.yaml`, inside -the specified template directory), the builder MUST iterate through all the -defined schemes and output matching files. +the specified `TEMPLATES-DIRECTORY`), the builder MUST iterate through all the +specified schemes and output matching files. -The built filename MUST look like `/base16-`, -where the slug is taken from the scheme filename made lowercase with spaces -replaced with dashes and both the extension and output-dir are taken from +The built filenames MUST be relative to the directory where the command is +executed, and MUST look like `/base16-`, where the +`SLUG` is taken from the scheme filename made lowercase with spaces replaced +with dashes and both the extension and `output-dir` are taken from `config.yaml`. If the build fails for any reasons, the program MUST exit with code `1` and MAY @@ -148,6 +133,36 @@ generic errors SHOULD check for non-zero status. Otherwise, the program MUST exit with code `0` and an OPTIONAL success message. +#### 3.1.3 CLI example: + +```bash +git clone https://github.com/base16-project/base16-vim.git +git clone https://github.com/base16-project/base16-schemes.git +base16 base16-vim/templates base16-schemes/*.yaml +``` + +Should create a `colors` (on the current directory) containing `base16-XXX.vim` +files. + +### 3.2. Library + +The other option is exposing a software library other developers may use to +assist developing more complex base16-compatible tooling. + +As above, the library MUST a single feature: building templates. + +This exposed library, or any internal code, has no specific required structure. + +The author MAY choose how (through a class, function that operates on file +paths, etc) they will expose the builder functionality to the caller, according +to their judgement. + +They SHOULD try to achieve an ergonomical and powerful interface and follow the +best practices on their respective programming languages. + +Official reference implementations will follow semantic versioning matching +this spec, in the format: `-builder_revision`. + ## 5. Considerations Mustache was chosen as the templating language due to its simplicity and widespread adoption across languages. YAML was chosen to describe scheme and From 9c73029f64ca12450f15cc9e4f7dff065685d5cb Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sun, 26 Jun 2022 23:16:07 -0300 Subject: [PATCH 11/15] small clarification --- builder.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/builder.md b/builder.md index f2e5c47..a1307fd 100644 --- a/builder.md +++ b/builder.md @@ -20,7 +20,8 @@ on the placeholders the template files hold. For example: the [solarized scheme](https://github.com/base16-project/base16-schemes/blob/main/solarized-dark.yaml) A base16 builder is, essentially, an application that somehow implements the -_building_ feature specification. +_building_ feature specification: filling the placeholders on templates with +scheme colors. Builders are categorized into: From b9118e5fe4a938d1ae66b33426587ef9aeb07a32 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sun, 26 Jun 2022 23:18:14 -0300 Subject: [PATCH 12/15] move network specification into 3.1 instead of 3.1.1 --- builder.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/builder.md b/builder.md index a1307fd..e11ca66 100644 --- a/builder.md +++ b/builder.md @@ -81,12 +81,13 @@ To be fully compliant, a builder CLI interface MUST NOT include any other feature, option, argument, or deviance from the expected interface and behaviour of the program. -#### 3.1.1 CLI Arguments and options The CLI interface MUST work without relying on any network connection. +#### 3.1.1 CLI Arguments and options + ```bash base16 ... ``` From 413ad81ed8efbd950c5bc58b23a001af857781e8 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sun, 26 Jun 2022 23:20:01 -0300 Subject: [PATCH 13/15] missing word on 3.2 --- builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builder.md b/builder.md index e11ca66..62bf3c8 100644 --- a/builder.md +++ b/builder.md @@ -151,7 +151,7 @@ files. The other option is exposing a software library other developers may use to assist developing more complex base16-compatible tooling. -As above, the library MUST a single feature: building templates. +As above, the library MUST implement single feature: building templates. This exposed library, or any internal code, has no specific required structure. From 4dac926331eef890356ad03a9d339ad2f83dd33b Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Sun, 26 Jun 2022 23:20:37 -0300 Subject: [PATCH 14/15] fix considerations numbering --- builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builder.md b/builder.md index 62bf3c8..3dc46fc 100644 --- a/builder.md +++ b/builder.md @@ -165,7 +165,7 @@ best practices on their respective programming languages. Official reference implementations will follow semantic versioning matching this spec, in the format: `-builder_revision`. -## 5. Considerations +## 4. Considerations Mustache was chosen as the templating language due to its simplicity and widespread adoption across languages. YAML was chosen to describe scheme and configuration files for the same reasons. From ea5f309095a31d83dddff47d8f69d0629d1dd6c2 Mon Sep 17 00:00:00 2001 From: Gabriel Fontes Date: Mon, 27 Jun 2022 13:13:15 -0300 Subject: [PATCH 15/15] apply suggestions --- builder.md | 78 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 43 insertions(+), 35 deletions(-) diff --git a/builder.md b/builder.md index 3dc46fc..d35bb98 100644 --- a/builder.md +++ b/builder.md @@ -10,32 +10,41 @@ interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc "Building" refers to replacing placeholders on base16 _[template files](./file.md)_ with colors from base16 _[schemes](./styling.md)_. -A template is a mustache file that acts as a "blueprint": it represents how to -output the scheme into other file formats, or (more commonly) how to output a -configuration file to theme a specific software. For example: a [vim +A template is a mustache file that acts as a blueprint; it represents how to +output the scheme into other file formats. For example: a [vim template](https://github.com/base16-project/base16-vim/blob/main/templates/default.mustache). -A scheme is a yaml file that represents a palette of 16 colors: to be replaced -on the placeholders the template files hold. For example: the [solarized +A scheme is a yaml file that represents a palette of 16 colors, for use in +template files. For example: the [solarized scheme](https://github.com/base16-project/base16-schemes/blob/main/solarized-dark.yaml) -A base16 builder is, essentially, an application that somehow implements the +A base16 builder is essentially an application that somehow implements the _building_ feature specification: filling the placeholders on templates with scheme colors. -Builders are categorized into: +The spec is composed of three parts: -- _reference tooling_: These follow the spec closely and are - designed for unopinionated lower-level ("plumbing") usage, specifically for - scripting and as component to build more complex base16 applications. High - quality reference builders will usually be adopted by the base16-project - organization; +- _The main base16 (template variables) spec_: This is a specification REQUIRED for full + compatibility with base16 templates. All base16 tooling aiming for 100% + compliance MUST follow it. It includes template and variables specifications. +- _The standardized CLI spec_: This is a specification REQUIRED for + reference tooling where exposing a CLI is relevant. For non-reference tools, + all the clauses in this specification are to be considered optional. + +With that said, builders are categorized into: + +- _reference tooling_: These MUST follow the main spec and either expose a + command-line or a software library interface, for "plumbing" usage with + scripts or when building other, more complex, base16 tools. High quality + reference builders will usually be adopted by the base16-project + organization. - _extended tooling_: These are built for end users and are usually tailored - for a usecase. This includes GUI apps, ergonomical CLI tools, scheme - managers, web apps, and more. These apps are encouraged to use (or create) - reference implementations as libraries, but may also implement the builder - feature themselves. All of the following `MUST`s can be replaced by `SHOULD`s - when writing this kind of tooling. + for a specific usecase. This means that they MUST follow _only_ the main + base16 (template variables) spec to attain full compliance. These include GUI + apps, ergonomical CLI tools, scheme managers, web apps, and more. Authors are + encouraged to use (or create) reference implementations as libraries, but may + also implement the builder feature themselves. Specs besides the template + variables are to be considered optional. ## 2. Template variables spec @@ -45,6 +54,7 @@ template files it processes: - `scheme-name` - obtained from the scheme file - `scheme-author` - obtained from the scheme file - `scheme-slug` - obtained from the scheme filename, as described above +- `scheme-slug-underscored` - same as `scheme-slug`, but with dashes replaced with underscores - `scheme-kind` - either "light" or "dark", calculated from the `base00` color - `base00-hex` to `base0F-hex` - obtained from the scheme file e.g "7cafc2" @@ -74,8 +84,8 @@ It is REQUIRED that this functionality is exposed by one (or both) of the follow ### 3.1. CLI -The binary name SHOULD contain `base16`, but is otherwise left as a choice to -the author. +The binary name SHOULD contain `base16-builder`, but is otherwise left as a +choice to the author. To be fully compliant, a builder CLI interface MUST NOT include any other feature, option, argument, or deviance from the expected interface and @@ -107,14 +117,13 @@ The program MAY also offer the following options: - `--help | -h` option to output usage information directly or by opening the manpage. -These three options have output that is considered implementation detail, not -intended to be scripted with. Thus each author SHOULD implement them as they -see fit. +These three options have output that is implementation specific, not intended +to be scripted with. Thus each author SHOULD implement them as they see fit. #### 3.1.2. CLI output and behaviour **Note**: All text outputted by the CLI binary is considered implementation -detail, so the author MAY output whatever they prefer (or no message at all). +specific, so the author MAY output whatever they prefer (or no message at all). If needed, scripts using the builder SHOULD check for return codes (specified below) instead of messages. @@ -128,10 +137,15 @@ executed, and MUST look like `/base16-`, where the with dashes and both the extension and `output-dir` are taken from `config.yaml`. -If the build fails for any reasons, the program MUST exit with code `1` and MAY -output an error message. This is not exhaustive and new exit codes might be -added in the future to account for specific errors, so scripters catching -generic errors SHOULD check for non-zero status. +Build failures are mostly related to faulty schemes and/or templates: +- when failling to parse a scheme, the program MUST exit with code `1`; +- when failling to parse a template file, the program MUST exit with code `2`; +- otherwise, the program MUST exit with code `3`. + +All of these errors MAY be accompanied by OPTIONAL error messages. + +The exit codes are not exhaustive and new ones might be added in the future, so +scripters catching generic errors SHOULD check for non-zero status. Otherwise, the program MUST exit with code `0` and an OPTIONAL success message. @@ -170,11 +184,5 @@ Mustache was chosen as the templating language due to its simplicity and widespread adoption across languages. YAML was chosen to describe scheme and configuration files for the same reasons. -The core scheme repository was based off the single scheme repository so -builders supporting v0.8-v0.9 of the spec can continue to function without -changes. - -The revised builder functionality specification introduced in v0.11 did not -introduce any changes to schemes or templates, so no changes to these are -needed. Older builders will continue to work, but authors are encouraged to -implement the new, simpler and more consistent, specification. +Spec upgrades should be backwards compatible with existing templates and +schemes.