From 2cd9bd9a255ea2eeb8b2b0771d0759150d715914 Mon Sep 17 00:00:00 2001 From: Thomas Jensen Date: Fri, 28 May 2021 22:12:45 +0200 Subject: [PATCH] Add description of tags --- _data/navigation.yml | 2 +- _sass/_boxes.scss | 2 ++ pages/config-best-practices.md | 10 +++++----- pages/config-syntax.md | 33 ++++++++++++++++++++++++++++++--- pages/v2.0.0/config-syntax.md | 14 +++++++++++++- pages/v2.1.0/config-syntax.md | 31 ++++++++++++++++++++++++++++++- 6 files changed, 81 insertions(+), 11 deletions(-) diff --git a/_data/navigation.yml b/_data/navigation.yml index 9dec268..5dabaaf 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -19,7 +19,7 @@ toc: url: /editors.html - title: Manual Page url: /boxes-man-1.html - - group: Custom Designs + - group: Box Designs subfolderitems: - title: General Concept url: /config-general.html diff --git a/_sass/_boxes.scss b/_sass/_boxes.scss index 65cdf69..0f08d3e 100644 --- a/_sass/_boxes.scss +++ b/_sass/_boxes.scss @@ -112,6 +112,7 @@ pre { > code { padding: 0; border-radius: 0; + white-space: pre; } } code { @@ -119,6 +120,7 @@ code { background-color: $light; border-radius: $border-radius-sm; padding: 2px 3px; + white-space: pre-wrap; } diff --git a/pages/config-best-practices.md b/pages/config-best-practices.md index 1ad1a4a..beb5799 100644 --- a/pages/config-best-practices.md +++ b/pages/config-best-practices.md @@ -14,11 +14,11 @@ through this list. - **Align Shape Lines** – Multi-line shapes should be arranged in the configuration file so that their lines align. This makes it much easier for a human to recognize the shapes. For example, - ``` - n ("/'''\", - "| |", - "\___/") - ``` + + n ("/'''\", + "| |", + "\___/") + is easier to read than just `n("/'''\","| |","\___/")`, although *boxes* considers both the same. - **Apply Proper Tags** – In our official config file, all box designs should be properly tagged using the `tags` diff --git a/pages/config-syntax.md b/pages/config-syntax.md index 59bf715..73a2403 100644 --- a/pages/config-syntax.md +++ b/pages/config-syntax.md @@ -6,7 +6,7 @@ redirect_from: - /docs/config-syntax.shtml longContent: true created_at: 1999-04-06 -last_modified_at: 2021-04-24 14:44:35 +0200 +last_modified_at: 2021-05-28 22:11:00 +0200 --- # Config File Syntax @@ -14,8 +14,6 @@ last_modified_at: 2021-04-24 14:44:35 +0200 {% assign thisVersion = site.currentVersion | prepend: 'v' -%} {%- include version-select.html currentVersion=thisVersion contentPiece="config-syntax" %} - - The *boxes* config file is a succession of box design definitions. Everything following a pound sign (`#`) is considered a **comment** (unless, of course, the pound sign is part of a string or something). @@ -257,6 +255,35 @@ Please try to give both fields always. Especially in those cases where existing for use with *boxes*, it is important (and good manners) to give credit to the original artist. +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=3 + text="Tags" %} + +Since *boxes* v2.1.0: + +
TAGS ("tag1", "tag2", "tag3")
+ +or, in all versions of *boxes*: + +
TAGS "tag1, tag2, tag3"
+ +The legacy notation has the advantage of being backwards compatible with all versions of *boxes*, which is why we use +it exclusively in the official config file. But once we're reasonably sure that all the world is at least on v2.1.0, +we can upgrade that. + +The `tags` statement applies one or more tags to the box design which can later be used to find and select the design +in a tag query. A tag can only contain the lower-case letters `a-z`, digits, or a dash (`-`). It must not start with +a dash. + +At the end of the output of `boxes -l`, *boxes* will print a summary of all tags found in the configuration, +complete with counts of how often the tag was encountered. + +A *tag query* can be issued by invoking `boxes -q`. *Boxes* will then print the names of all matching box designs. +Details about tag queries can be found in the [manual page]({{ site.baseurl }}/boxes-man-1.html#OPTIONS) for the `-q` +option. + + {% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html level=3 diff --git a/pages/v2.0.0/config-syntax.md b/pages/v2.0.0/config-syntax.md index ee6b6e0..8f41cbc 100644 --- a/pages/v2.0.0/config-syntax.md +++ b/pages/v2.0.0/config-syntax.md @@ -4,7 +4,7 @@ permalink: /v2.0.0/config-syntax.html longContent: true bxVersion: v2.0.0 created_at: 1999-04-06 -last_modified_at: 2019-06-09 21:49:00 +0200 +last_modified_at: 2021-05-28 22:11:00 +0200 --- # Config File Syntax @@ -233,6 +233,18 @@ Please try to give both fields always. Especially in those cases where existing for use with *boxes*, it is important (and good manners) to give credit to the original artist. +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=3 + text="Tags" %} + +
TAGS "tag1, tag2, tag3"
+ +The `tags` statement applies one or more tags to the box design. This is currently purely informational, but we plan +to implement a *tag query* functionality in a later version of *boxes*. A tag can only contain the lower-case letters +`a-z`, digits, or a dash (`-`). It must not start with a dash. + + {% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html level=3 diff --git a/pages/v2.1.0/config-syntax.md b/pages/v2.1.0/config-syntax.md index 852c5d7..024a476 100644 --- a/pages/v2.1.0/config-syntax.md +++ b/pages/v2.1.0/config-syntax.md @@ -4,7 +4,7 @@ permalink: /v2.1.0/config-syntax.html longContent: true bxVersion: v2.1.0 created_at: 1999-04-06 -last_modified_at: 2021-04-24 14:44:35 +0200 +last_modified_at: 2021-05-28 22:11:00 +0200 --- # Config File Syntax @@ -253,6 +253,35 @@ Please try to give both fields always. Especially in those cases where existing for use with *boxes*, it is important (and good manners) to give credit to the original artist. +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=3 + text="Tags" %} + +Since *boxes* v2.1.0: + +
TAGS ("tag1", "tag2", "tag3")
+ +or, in all versions of *boxes*: + +
TAGS "tag1, tag2, tag3"
+ +The legacy notation has the advantage of being backwards compatible with all versions of *boxes*, which is why we use +it exclusively in the official config file. But once we're reasonably sure that all the world is at least on v2.1.0, +we can upgrade that. + +The `tags` statement applies one or more tags to the box design which can later be used to find and select the design +in a tag query. A tag can only contain the lower-case letters `a-z`, digits, or a dash (`-`). It must not start with +a dash. + +At the end of the output of `boxes -l`, *boxes* will print a summary of all tags found in the configuration, +complete with counts of how often the tag was encountered. + +A *tag query* can be issued by invoking `boxes -q`. *Boxes* will then print the names of all matching box designs. +Details about tag queries can be found in the +[manual page]({{ site.baseurl }}/{{ page.bxVersion }}/boxes-man-1.html#OPTIONS) for the `-q` option. + + {% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html level=3