From 8eb47f0f7ab37d393d3669812dfe8a87d5363a4b Mon Sep 17 00:00:00 2001 From: Thomas Jensen Date: Fri, 28 May 2021 21:13:10 +0200 Subject: [PATCH] Add config file best practices --- _data/navigation.yml | 4 +- _includes/analytics.html | 2 +- _sass/_boxes.scss | 6 +-- pages/config-best-practices.md | 72 +++++++++++++++++++++++++++ pages/config-complete_exp.md | 89 ++-------------------------------- pages/config-step.md | 2 +- pages/examples.md | 42 +++++++++------- 7 files changed, 108 insertions(+), 109 deletions(-) create mode 100644 pages/config-best-practices.md diff --git a/_data/navigation.yml b/_data/navigation.yml index 8ffc7ef..9dec268 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -27,8 +27,8 @@ toc: url: /config-syntax.html - title: Step-by-Step url: /config-step.html - - title: Complete examples - url: /config-complete_exp.html + - title: Best Practices + url: /config-best-practices.html - divider: true - title: List of Designs url: /box-designs.html diff --git a/_includes/analytics.html b/_includes/analytics.html index 5ce9e8f..ded22f9 100644 --- a/_includes/analytics.html +++ b/_includes/analytics.html @@ -2,4 +2,4 @@ Privacy-friendly analytics with plausible.io - no personal information is collected, no cookies {%- endcomment -%} - + diff --git a/_sass/_boxes.scss b/_sass/_boxes.scss index 206d1c0..65cdf69 100644 --- a/_sass/_boxes.scss +++ b/_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; diff --git a/pages/config-best-practices.md b/pages/config-best-practices.md new file mode 100644 index 0000000..1ad1a4a --- /dev/null +++ b/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! diff --git a/pages/config-complete_exp.md b/pages/config-complete_exp.md index 4512f7c..9c52ce2 100644 --- a/pages/config-complete_exp.md +++ b/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 -code of two complete box designs, one simple and one more complex. +

DEPRECATED

-In addition to the examples shown here, please refer to the [official boxes config -file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"} for tons more. +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"}, 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 " - 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. diff --git a/pages/config-step.md b/pages/config-step.md index c45a332..8afd685 100644 --- a/pages/config-step.md +++ b/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) diff --git a/pages/examples.md b/pages/examples.md index 64918b8..2cbd15d 100644 --- a/pages/examples.md +++ b/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') - return (char *) s1; /* error 1 */ - if (!s1 || *s1 == '\0') - return NULL; /* error 2 */ - if (skip < 0) - skip = 0; /* foo bar */ +```c +if (!s2 || *s2 == '\0') + return (char *) s1; /* error 1 */ +if (!s1 || *s1 == '\0') + return NULL; /* error 2 */ +if (skip < 0) + skip = 0; /* foo bar */ +``` `boxes -d c-cmt` - /* if (!s2 || *s2 == '\0') */ - /* return (char *) s1; /* error 1 *\/ */ - /* if (!s1 || *s1 == '\0') */ - /* return NULL; /* error 2 *\/ */ - /* if (skip < 0) */ - /* skip = 0; /* foo bar *\/ */ +```c +/* if (!s2 || *s2 == '\0') */ +/* return (char *) s1; /* error 1 *\/ */ +/* if (!s1 || *s1 == '\0') */ +/* return NULL; /* error 2 *\/ */ +/* 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') - return (char *) s1; /* error 1 */ - if (!s1 || *s1 == '\0') - return NULL; /* error 2 */ - if (skip < 0) - skip = 0; /* foo bar */ +```c +if (!s2 || *s2 == '\0') + return (char *) s1; /* error 1 */ +if (!s1 || *s1 == '\0') + return NULL; /* error 2 */ +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