Add description of tags

2025-08-19 11:02:25 +02:00 · 2021-05-28 22:12:45 +02:00
parent 8eb47f0f7a
commit 2cd9bd9a25
6 changed files with 81 additions and 11 deletions
--- 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
--- 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;
 }


--- 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`
--- 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" %}

-<!-- TODO describe tags -->
-
 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:
+
+<PRE><b>TAGS</b> (&quot;<i>tag1</i>&quot;, &quot;<i>tag2</i>&quot;, &quot;<i>tag3</i>&quot;)</PRE>
+
+or, in all versions of *boxes*:
+
+<PRE><b>TAGS</b> &quot;<i>tag1</i>, <i>tag2</i>, <i>tag3</i>&quot;</PRE>
+
+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
--- 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" %}
+
+<PRE><b>TAGS</b> &quot;<i>tag1</i>, <i>tag2</i>, <i>tag3</i>&quot;</PRE>
+
+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
--- 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:
+
+<PRE><b>TAGS</b> (&quot;<i>tag1</i>&quot;, &quot;<i>tag2</i>&quot;, &quot;<i>tag3</i>&quot;)</PRE>
+
+or, in all versions of *boxes*:
+
+<PRE><b>TAGS</b> &quot;<i>tag1</i>, <i>tag2</i>, <i>tag3</i>&quot;</PRE>
+
+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