Add config file best practices

_data/navigation.yml

@@ -27,8 +27,8 @@ toc:
         url: /config-syntax.html
       - title: Step-by-Step
         url: /config-step.html
-      - title: Complete examples
+      - title: Best Practices
-        url: /config-complete_exp.html
+        url: /config-best-practices.html
       - divider: true
       - title: List of Designs
         url: /box-designs.html

_includes/analytics.html

@@ -2,4 +2,4 @@
     Privacy-friendly analytics with plausible.io - no personal information is collected, no cookies
 {%- endcomment -%}
 
-<script async defer data-domain="{{ site.plausible.data_domain }}" src="https://plausible.io/js/plausible.js"></script>
+<script async defer data-domain="{{ site.plausible.data_domain }}" src="https://thomasjensen.com/js/script.js"></script>

_sass/_boxes.scss

@@ -22,6 +22,9 @@ ul.pagination, li.page-item, p.post-meta, .card-header, .card-subtitle, .navbar-
 li {
     margin-bottom: $spacer;
 }
+ol ul li, ul ul li {
+    margin-bottom: 0;
+}
 
 
 /*
@@ -111,9 +114,6 @@ pre {
         border-radius: 0;
     }
 }
-li pre {
-    margin: 0;
-}
 code {
     color: inherit;
     background-color: $light;

pages/config-best-practices.md

@@ -0,0 +1,72 @@
+---
+title: Docs - Best Practices
+permalink: /config-best-practices.html
+created_at: 2021-05-27 20:55:00 +0200
+last_modified_at: 2021-05-27 20:55:00 +0200
+---
+
+# Config Best Practices
+
+Finally, here is a small list of best practices to consider when creating your own box design. Especially when you
+consider having your box design added to the [official configuration
+file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"}, it makes sense to quickly run
+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 ("/'''\",
+     "|   |",
+     "\___/")
+  ```
+  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`
+  statement. This normally means that you choose some of the existing tags and set them on your box design. The list
+  can be seen at the end of `boxes -l` output. Currently, the most important tags are:
+
+  - `artwork` - It's an ASCII art box, not a simple thing like a box of asterisks or hash characters. When in doubt,
+    don't use this tag.
+  - `box` - It's a box that goes around the input text, i.e. at most one open side.
+  - `comment` - A regional comment in a programming language.
+  - `programming` - All comments in a programming language, including boxes which are valid comments. Anything tagged
+    `comment` would also be tagged `programming`.
+  - `sign` - An ASCII art figure holding or showing a sign which contains the input text.
+  - `simple` - A simple box, normally excluding `artwork`.
+  - `speech` - A box which includes a speech bubble.
+
+- **Give Credit Where Credit is Due** – This point is really important. If your box is based on someone else's artwork,
+  the original artist must be credited in a `designer` entry, and you must make sure that the person allowed you to
+  use his artwork. Very often, the ASCII artists already say so on their website, which is great, but as the author
+  of a design, it is your responsibility to make sure that no intellectual property is violated. Some artists also
+  want their initials placed on the box, in which cases your box design must also include them. This is not a hard
+  thing to do at all, just something to think of. 
+
+- **Indent Sample Block by 4 Spaces** – It's nice when the `sample` block gives a real-world example of your box.
+  Currently it is also nice if the sample is indented by exactly 4 spaces. Then it appears nicely in line in the
+  box listing produced by `boxes -l`, as we are currently still too lazy to align the samples automatically.
+
+- **Maximize Text Area** – Try to design every box so that there is as little whitespace on its inside as possible.
+  Many boxes don't really look very good unless there is some space between the text area and the box, but this can be
+  addressed by a default padding value. The advantage is that when a really small box size is specified by the user,
+  padding will be sacrificed by *boxes* in order to meet the size. This wouldn't be possible if the spaces were
+  hard-coded into the box shapes.
+
+- **Prefer Small Shapes** – Try to find the smallest possible shapes which draw your box. For example, a row of dashes
+  (`"------"`) should be drawn by repeating a shape that consists of a single dash (`"-"`) not multiple ones (`"--"`).
+  The advantage is that this way, *boxes* has the most freedom when sizing your box, and can produce boxes which
+  fit better around their input text. There is no need to make shapes on one side of a box the same size as shapes on
+  an opposing side. *Boxes* will handle that.
+
+- **Support Nested Comments** – If your box is supposed to be used in code, then consider adding `replace` and
+  `reverse` statements to it. When the box is applied to a piece of code which already contains comments, those
+  can be escaped. When the box is removed, the comments are restored
+  ([example]({{ site.baseurl }}/examples.html#comments)).
+
+- **Use DELIM Judiciously** – If possible, avoid using the `delimiter` statement. It's an advanced feature which helps
+  when a box design contains a lot of backslashes or quotation marks, but it otherwise makes a box design harder to
+  read for humans - we are simply not used to weird characters that function as escape characters. But if you must use
+  it, then by all means do - the `delimiter` statement has no technical disadvantages. It's all about readability.
+
+
+That's it for now! We may add to this list when new topics come up. Enjoy creating your very own box designs!

pages/config-complete_exp.md

@@ -5,93 +5,14 @@ redirect_from:
   - /docs/config-complete_exp.html
   - /docs/config-complete_exp.shtml
 created_at: 1999-04-06
-last_modified_at: 2014-12-23 22:50:09 +0100
+last_modified_at: 2021-05-27 20:55:00 +0200
 ---
 
 # Complete Examples
 
-In order to illustrate the *boxes* configuration language described in the previous chapters, we now look at the source
+<p class="text-muted">DEPRECATED</p>
-code of two complete box designs, one simple and one more complex.
 
-In addition to the examples shown here, please refer to the [official boxes config
+This page was deprecated, because really the best source of examples is the [official boxes config
-file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"} for tons more.
+file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"}, which contains all kinds of
+simple and complex uses of every syntax element.
 
-{%- comment %}  TODO simply refer to config file, add best practices section instead {% endcomment -%}
-
-## Simple Example
-
-    BOX simple
-    
-        sample
-            ++++++++++++
-            +          +
-            ++++++++++++
-        ends
-    
-        shapes {
-            n("+")  s("+")  e("+")  w("+")
-           nw("+") ne("+") se("+") sw("+")
-        }
-    
-        elastic (n,s,e,w)
-    
-    END simple
-
-
-## Complex Example
-
-    BOX tjc
-    
-        author   "John Doe <john@doe.com>"
-        revision "1.1"
-        revdate  "July 16, 1999 (Friday, 18:55h)"
-        created  "April 02, 1999 (Friday, 19:26h)"
-    
-        Sample
-            static char *foo (const int a, const int b)
-            /*
-             *  Do the foo on the bar and around again.
-             *
-             *      a     number of doodlefrobs
-             *      b     barfoo mode (0 == off)
-             *
-             *  Memory will be allocated for the result.
-             *  Should only be called for lines of length > 0;
-             *
-             *  RETURNS:  Success: Pointer to result line
-             *            Error:   -1   (e.g. frobs depleted)
-             *
-            * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-             */
-            {
-                static char temp ....
-                int ii;          ....
-        ends
-    
-        indent "none"                 # alternatives: "box", "text"
-    
-        shapes {
-            wnw ("/*")
-            w   (" *")
-            sw  ("* ", " *")
-            ssw ("*", "/")
-            s   (" *", "  ")
-        }
-    
-        elastic (s, w)
-    
-        delimiter ?"
-    
-        replace "\*/" with "*\/"      # quote closing comment tags
-        reverse "\*\\/" to "*/"
-    
-        padding {
-            left 2
-            vertical 1
-        }
-    
-    END tjc
-
-Note the `SAMPLE` block of the latter example. It shows much more than just the box itself, trying to give the user an
-impression of what the box would look like if used in reality. We only need half the backslashes in the `REVERSE` and
-`REPLACE` statements because we use `delimiter` to change the escape character from backslash to question mark.

pages/config-step.md

@@ -47,4 +47,4 @@ It is precision work to finalize the box design. But this needs to be done only
 and reused easily.
 
 
-Read on in the next part: [Complete Examples of Box Designs]({{ site.baseurl }}/config-complete_exp.html)
+Read on in the next part: [Configuration File Best Practices]({{ site.baseurl }}/config-best-practices.html)

pages/examples.md

@@ -236,21 +236,25 @@ achieved by `-p h0` or `-p a0`.
 
 Imagine you want to comment out the following C code:
 
-    if (!s2 || *s2 == '\0')
+```c
+if (!s2 || *s2 == '\0')
     return (char *) s1;  /* error 1 */
-    if (!s1 || *s1 == '\0')
+if (!s1 || *s1 == '\0')
     return NULL;         /* error 2 */
-    if (skip < 0)
+if (skip < 0)
     skip = 0;            /* foo bar */
+```
 
 `boxes -d c-cmt`
 
-    /* if (!s2 || *s2 == '\0')                 */
+```c
-    /*     return (char *) s1;  /* error 1 *\/ */
+/* if (!s2 || *s2 == '\0')                 */
-    /* if (!s1 || *s1 == '\0')                 */
+/*     return (char *) s1;  /* error 1 *\/ */
-    /*     return NULL;         /* error 2 *\/ */
+/* if (!s1 || *s1 == '\0')                 */
-    /* if (skip < 0)                           */
+/*     return NULL;         /* error 2 *\/ */
-    /*     skip = 0;            /* foo bar *\/ */
+/* if (skip < 0)                           */
+/*     skip = 0;            /* foo bar *\/ */
+```
 
 Note that the closing comment tags in the input text have been escaped by adding a backslash between the asterisk and
 the slash. This way, the comments that have been commented out along with the rest of the code will not interfere with
@@ -258,12 +262,14 @@ the new comments.
 
 `boxes -r`
 
-    if (!s2 || *s2 == '\0')
+```c
+if (!s2 || *s2 == '\0')
     return (char *) s1;  /* error 1 */
-    if (!s1 || *s1 == '\0')
+if (!s1 || *s1 == '\0')
     return NULL;         /* error 2 */
-    if (skip < 0)
+if (skip < 0)
     skip = 0;            /* foo bar */
+```
 
 Should you decide to reactivate the code previouly commented out, the escaped closing comment tags are changed back
 into normal ones. This is achieved by the `replace` and `reverse` statements in the config file entry describing this