mirror of
https://github.com/ascii-boxes/boxes.git
synced 2025-02-28 15:21:50 +01:00
Add config file best practices
This commit is contained in:
Thomas Jensen
parent
0a42f2b42b
commit
8eb47f0f7a
@ -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
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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;
|
||||
|
||||
72
pages/config-best-practices.md
Normal file
72
pages/config-best-practices.md
Normal file
@ -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!
|
||||
@ -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.
|
||||
<p class="text-muted">DEPRECATED</p>
|
||||
|
||||
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 <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.
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user