From d1aee4d74abe838efb986f0d2c83843b73b4d859 Mon Sep 17 00:00:00 2001 From: Thomas Jensen Date: Tue, 12 May 2015 21:50:01 +0200 Subject: [PATCH] Apply 'markdown' layout to 5 pages --- _includes/boxes/about.md | 36 ---- _includes/boxes/build.md | 77 -------- _includes/boxes/contributing.md | 74 -------- _includes/boxes/download.md | 33 ---- _includes/boxes/examples.md | 305 ------------------------------- about.html | 42 ++++- build.html | 83 ++++++++- contributing.html | 80 +++++++- download.html | 39 +++- examples.html | 311 +++++++++++++++++++++++++++++++- 10 files changed, 530 insertions(+), 550 deletions(-) delete mode 100644 _includes/boxes/about.md delete mode 100644 _includes/boxes/build.md delete mode 100644 _includes/boxes/contributing.md delete mode 100644 _includes/boxes/download.md delete mode 100644 _includes/boxes/examples.md diff --git a/_includes/boxes/about.md b/_includes/boxes/about.md deleted file mode 100644 index fc39203..0000000 --- a/_includes/boxes/about.md +++ /dev/null @@ -1,36 +0,0 @@ -# ASCII Box Drawing - the *boxes* filter program - - - /*********************/ - boxes draws any /* boxes draws any */ - kind of boxes ===> /* kind of boxes */ - around your text! /* around your text! */ - /*********************/ - -*Boxes* is a [text filter]({{ site.baseurl }}/docs/filters.html) which can draw ASCII art boxes around its input text. These boxes may also be removed, even if they have been badly damaged by editing of the text inside. Since boxes may be open on any side, *boxes* can also be used to create regional comments in any programming language. With the help of an editor macro or mapping, damaged boxes can easily be repaired. - -This is useful for making the function headers in your programming language look better, for spicing up your news postings and emails, or just for decorating your documentation files. - -New box designs of all sorts can easily be added and shared by appending to a free format configuration file. *boxes* was originally intended to be used with the vim(1) text editor, but can be tied to any text editor which supports filters. - - -## Some Of The Features - - - Drawing of ASCII art boxes around input text - - Generation of regional comments in any programming language - - Freely and conveniently user-configurable boxes - - Alignment and positioning of text inside a box - - Removal of boxes, even if box is damaged by editing of contained text - - A number of preconfigured box designs in example config file - - Many useful command line options (such as box size specification etc.) - - Regular expression substitutions on input text - (e.g. used for quoting closing comment tags in a C comment box) - - -## Author - -*Boxes* is developed by Thomas Jensen {{ page.bxemail }}. - -Special thanks go to the many [contributors]({{ site.baseurl }}/contributing.html#contributors), who have helped improve *boxes* over the years. - -*Boxes* is free software. Go and download your copy from the [download page]({{ site.baseurl }}/download.html)! diff --git a/_includes/boxes/build.md b/_includes/boxes/build.md deleted file mode 100644 index 8b067bf..0000000 --- a/_includes/boxes/build.md +++ /dev/null @@ -1,77 +0,0 @@ -# Building from Source - -Here's how to build your own version of *boxes* using the [boxes sources](https://github.com/{{ site.github }}). - -## Building on Linux / UNIX - -Just unzip the [source archive](https://github.com/{{ site.github }}/releases/latest) or [clone the GitHub repo](https://help.github.com/articles/cloning-a-repository/). Make sure you have your C compiler installed, including [Flex](http://flex.sourceforge.net/) and [Bison](http://www.gnu.org/software/bison/). In the top level directory, type `make && make test`. Find the resulting binary in the *src* folder. In case of problems, check the [compilation faq]({{ site.baseurl }}/docs/faq.html#q5). - -That should be all. *Boxes* is built so that this works almost everywhere. - -## Building on Windows - -Boxes was written for UNIX, but it can also run on Windows! Boxes is a 32bit application, but it works on 64bit systems, too. Here's how to build on Windows. - -> Special thanks go to Ron Aaron, who provided a specially crafted Makefile for win32 and also created the Windows versions of boxes that have been around to this day. - -In order to build *boxes* on Windows, the required win32 executable can be created like this: - -1. Install [MinGW32](http://www.mingw.org/) -2. Configure MinGW32 -3. Open a MinGW shell and run `make win32` - -Basically very simple, but there may be a few pitfalls, so we'll go through each step in detail. - -### 1. Install MinGW32 - -1. Download MinGW from [mingw.org](http://www.mingw.org/) by pressing the **Download Installer** button in the top right corner of the page. You'll receive a mingw-get-setup.exe. -2. Right-click mingw-get-setup.exe and choose **Run as Administrator** from the pop-up menu. - This brings up the Installation Preferences. -3. Choose `C:\MinGW` as installation directory. This is really important. If for some reason you cannot use this highly recommended directory, choose another one that has a short path, does not contain spaces (!), and does not include a Windows "special path". For example, `C:\MinGW_2`. -4. Select "install support for GUI" (yes, even though *boxes* has no GUI) and install "for all users". -5. Press **Continue** and wait for download of the *Installation Manager*. -6. After the download of the Installation Manager is completed, press **Continue** again. - The Installation Manager opens. -7. Choose **mingw32-base** and **msys-base**. Also, further down, under *MSYS / MinGW Developer Toolkit*, choose **msys-bison** and **msys-flex**. - **Do not** install mingw-developer-toolkit, because if on 64bit, this requires tweaking of several environment variables to get gcc to use 32bit libs all around (which may be hard to get right for laymen). -8. In the menu, select *Installation* → *Apply Changes*. - Something like 104 Packages will be installed, which may take a few minutes. -9. Upon success, select *Installation* → *Quit* from the menu. - -### 2. Configure MinGW32 - -1. Change into C:\MinGW\msys\1.0\etc. -2. Copy the file *fstab.sample* to a new file called simply *fstab*. -3. Open *fstab* and make sure that the only lines which are not comments are these: - - c:/mingw /mingw - d:/path/to/boxes /boxes - - Note that the whitespace in this example are tab characters. The d:/path/to/boxes is the path where you placed your clone of the boxes repo. Avoid spaces in its path, too. -4. Add C:\MinGW\bin to your system PATH. -5. Create a "MinGW Shell" shortcut somewhere (I chose my desktop). The shortcut invokes the C:\MinGW\msys\1.0\msys.bat script, which is installed as a component of MSYS; (if you installed to an alternative directory, you should adjust the C:\MinGW prefix accordingly). - An icon file is provided in the same directory, in case you want to set it on the new shortcut. - -### 3. Open a MinGW shell and trigger the Windows build - -1. Double click your new **MinGW Shell** shortcut icon. - This opens a command window with the correct environment set up for you, including the correct path references, allowing you to run any of the MinGW or MSYS applications within that command window. -2. Within the MinGW shell: - - cd /boxes - make clean && make win32 - - If you want to create an executable with debug information, call `make clean && make debug.win32` instead. -3. boxes.exe is created in /boxes/src. -4. Optionally, run `make test` to check that your executable is working OK. - -### 4. Deployment - -In order to run boxes on any Windows machine, two files are required: - -- boxes.exe -- boxes.cfg - -*boxes.cfg* is obtained by simply renaming the *boxes-config* file from the root of the boxes repo into *boxes.cfg*. - -Both files should be placed together somewhere on your PATH. diff --git a/_includes/boxes/contributing.md b/_includes/boxes/contributing.md deleted file mode 100644 index 16abd8e..0000000 --- a/_includes/boxes/contributing.md +++ /dev/null @@ -1,74 +0,0 @@ -# Contributing - -You are considering a contribution to *boxes*? That's fantastic! - -All *boxes* development has moved to the GitHub social coding platform: - - - [Sources](https://github.com/{{ site.github }}) - - [Building from Source]({{ site.baseurl }}/build.html) - - [Writing Test Cases]({{ site.baseurl }}/testing.html) - - [Bug Reports and Feature Requests](https://github.com/{{ site.github }}/issues) - - [Change Log](https://github.com/{{ site.github }}/commits/master) - - [History of Releases]({{ site.baseurl }}/docs/releases.html) - -Boxes has been around a long time. It is available for many platforms (in reality for many more than those featured on the [download page]({{ site.baseurl }}/download.html)). Great care has been taken to make the *boxes* source as compatible as possible with all kinds of different platforms. - -The planned functionality has long been implemented, and it is very stable. Development has thus slowed down and concentrates on maintenance and contributor-supplied changes. - -The author can be contacted by email anytime, but please do not be offended when the response is slow. Even if it takes weeks or months, your email is never lost! - -## Contribution Process - -Changes must be introduced by creating pull requests on GitHub. Note that you can improve the *boxes* code as well as the website content! Ideas for new box designs should be submitted via GitHub, but since the most beautiful designs sometimes come from non-technical people, emails are acceptable for those. - -It is best to discuss the planned change before actually doing work on it by [creating an issue for it](https://github.com/{{ site.github }}/issues). This is really not a big deal, but it helps to ensure that your work will end up on the *boxes* master branch. - -In order to create a pull request, you must first [fork the *boxes* repo](https://help.github.com/articles/fork-a-repo/). Then create a new feature branch for your change. Commit the changes to your feature branch. After that, you can [create the pull request](https://help.github.com/articles/using-pull-requests/) against the *boxes* master. - -The pull request must meet the criteria mentioned below. If additional changes are identified during the review, you can simply push them to your forked repo, and the pull request will update automatically. - - -## Pull Request Acceptance Criteria - -Since *boxes* is not actively being developed anymore, changes to the code base must be "production ready" from the start. The following check list may help: - - - The [Travis CI build](https://travis-ci.org/{{ site.github }}) must pass for the pull request. This is indicated by a small green check mark next to your pull request. - - Provide [test cases]({{ site.baseurl}}/testing.html) for any code that you add. This helps make sure that nobody else breaks it later. - - Cross-platform compatibility is very important for *boxes*. Since *boxes* does not (and cannot really) make use of *autoconf*, the C code itself must work on every platform. In other words, you can use only such C commands that are known on every platform. When in doubt, restrict yourself to commands that you already find in the current sources. - -These criteria apply only to code changes. (Although other changes should not break the build, either.) - - -## Contributors - -Now that *boxes* is on GitHub, all contributors are automatically [listed on GitHub](https://github.com/{{ site.github }}/graphs/contributors). But in the years before GitHub, *boxes* has received support from additional people: - - - Ron Aaron - win32 port - - Peter van den Berkmortel - HPUX 10 binaries of v1.0.1 - - Salvatore Bonaccorso - enable compilation on GNU/kFreeBSD and GNU/Hurd; fixes to the man page - - Charles E. Campbell - vim syntax file fixes - - Christoph Dreyer - tab unexpansion - - Andreas Heiduk - bug fixes and compatibility improvements; Jed integration - - Jakub Hrozek - patch to eliminate a compilation warning on Fedora - - Yosuke Kimura - DEC alpha/OSF binaries of v1.0.1 - - Jeff Lanzarotta - contribution to FAQ - - Elmar Loos - 'mend' option - - Zdenek Sekera - SGI/Irix6 binaries of v1.0.1 - - Jason L. Shiffer - Emacs integration - - Henry Spencer - kindly permitted the use of his regular expression library for *boxes* - - Lu Weifeng - OpenWRT port - *boxes* now runs on routers, too - - Tommy Williams - i386/FreeBSD port - - Joe Zbiciak - compatibility improvements and Solaris binaries - - - AlpT - the *c-cmt3* design - - Ted Berg - the *javadoc* design - - Neil Bird - the *ada-cmt* and *ada-box* designs - - Bas van Gils - the *cc* design - - Karl E. Jorgensen - the *ian_jones* design - - Vijay Lakshminarayanan - the *lisp-cmt* design - - Elmar Loos - the *ccel* and *underline* designs - - Christian Molls - the *boxquote* design - - Fredrik Steen - the *stone* design - - Michael Tiernan - the *caml* design - -Many thanks to these awesome folks! diff --git a/_includes/boxes/download.md b/_includes/boxes/download.md deleted file mode 100644 index e2230cf..0000000 --- a/_includes/boxes/download.md +++ /dev/null @@ -1,33 +0,0 @@ -# Download *Boxes* - -*Boxes* is free software under the GNU General Public License (GNU GPL), version 2. - -The current release is **version 1.1.2**. For older revisions, feel free to browse the [release history]({{ site.baseurl }}/docs/releases.html). - - -## Sources - -The *boxes* sources are now all on GitHub, including previous releases: - -[https://github.com/{{ site.github }}](https://github.com/{{ site.github }}) - -For the (historical) record, the source of the outdated version 1.1 is also on [metalab](ftp://metalab.unc.edu/pub/Linux/utils/text/boxes-1.1.src.tar.gz) (FTP). - - -## Binaries - -The author supports binaries for intel/linux and intel/win32. *Boxes* has been compiled on a very wide variety of platforms, and for older releases, some of these binaries are available via the [release history]({{ site.baseurl }}/docs/releases.html). If you have binaries for different and/or new platforms, please send them in! - -**Windows** and **Linux** binary download: -[https://github.com/{{ site.github }}/releases/latest](https://github.com/{{ site.github }}/releases/latest) - -**MacOS X** -According to *boxes* user *Michel*, *boxes* can be installed on MacOS X (32bit) by simply typing `brew install boxes`. (Information of October 3, 2012) - - -## Miscellaneous - - - The current [list of available box designs]({{ site.baseurl }}/box-designs.txt). - Want to see your design in the official config file? Submit it as a [pull request](https://github.com/{{ site.github }}/pulls) on GitHub. If this seems too complicated, or you are not an IT person, feel free to send email, too. Emails take much longer to be processed, though. - - A vim syntax - file to enable the vim editor to use syntax highlighting with *boxes* config files (beta state). diff --git a/_includes/boxes/examples.md b/_includes/boxes/examples.md deleted file mode 100644 index 7a49e4e..0000000 --- a/_includes/boxes/examples.md +++ /dev/null @@ -1,305 +0,0 @@ -# Examples - -Remember, *boxes* is designed to be tied to your editor as a [text filter](docs/filters.html). So these examples assume you need only push a single key (or at least very few) in order to call *boxes*. Don't be worried by seemingly long argument lists - you'll only have to type them once. - -Unless stated otherwise, the input used for these examples is the following: - - Different all twisty a - of in maze are you, - passages little. - - -## Default action - -`boxes` - - /**************************/ - /* Different all twisty a */ - /* of in maze are you, */ - /* passages little. */ - /**************************/ - -Draws a standard box of the first valid design found in your config file. If you have the config file as it comes with the *boxes* distribution, you get a "C" box, as you can see above. - - - - -## Choosing a different design - -`boxes -d parchment` - - ________________________ - /\ \ - \_|Different all twisty a| - |of in maze are you, | - |passages little. | - | ___________________|_ - \_/_____________________/ - -The **-d** *design_name* option selects another design from your config file. - - - - -## Positioning of text inside box - -`boxes -d diamonds -a hcvc` - - /\ /\ /\ - /\//\\/\ /\//\\/\ /\//\\/\ - /\//\\\///\\/\//\\\///\\/\//\\\///\\/\ - //\\\//\/\\///\\\//\/\\///\\\//\/\\///\\ - \\//\/ \/\\// - \/ \/ - /\ Different all twisty a /\ - //\\ of in maze are you, //\\ - \\// passages little. \\// - \/ \/ - /\ /\ - //\\/\ /\//\\ - \\///\\/\//\\\///\\/\//\\\///\\/\//\\\// - \/\\///\\\//\/\\///\\\//\/\\///\\\//\/ - \/\\//\/ \/\\//\/ \/\\//\/ - \/ \/ \/ - -The **-a** *format* option can be used to position the input text inside a box which is larger than needed for our text. `hcvc` stands for "horizontally centered, vertically centered". - -Note that the box was drawn in this size because the shapes that compose it are very big, so that it is not possible to fit the box tighter around our text. Note also that the input lines themselves are *not* centered; `hc` only centers the input text block as a whole. - - -## Line justification - -`boxes -d simple -a jr` - - ************************ - *Different all twisty a* - * of in maze are you,* - * passages little.* - ************************ - -This uses the third possible argument to the **-a** option, `j`. `jr` stands for "justification right". - - -## Quick alignment/positioning - -`boxes -d dog -a c` - - __ _,--="=--,_ __ - / \." .-. "./ \ - / ,/ _ : : _ \/` \ - \ `| /o\ :_: /o\ |\__/ - `-'| :="~` _ `~"=: | - \` (_) `/ - .-"-. \ | / .-"-. - .---{ }--| /,.-'-.,\ |--{ }---. - ) (_)_)_) \_/`~-===-~`\_/ (_(_(_) ( - ( Different all twisty a ) - ) of in maze are you, ( - ( passages little. ) - ) ( - '---------------------------------------' - -Since noone really wants to type `-a hcvcjc` only to actually center text inside a box, there are shorthand notations (`l`, `c`, and `r`). - -Note the blank line at the bottom of the box (after `little`, but before the dashes) which is necessary to make the bottom of the box look right. If the blank line was not there, the box would end on a closing parenthesis, thus looking broken. - - - - -## Box size specification - -`boxes -d html -s 40` - - - - - - - -Using `-s 40`, we have set the box width to 40 characters. - - -## Box size specification (2) - -`boxes -d peek -a c -s 40x11` - - /* _\|/_ - (o o) - +----oOO-{_}-OOo----------------------+ - | | - | | - | Different all twisty a | - | of in maze are you, | - | passages little. | - | | - | | - +------------------------------------*/ - -Using `-s 40x11`, you can set both width and height. Setting just the height is possible with `-s x11` (note the leading `x` on the argument). - - - - -## Text Padding - -`boxes -d shell -p a1l2` - - ########################### - # # - # Different all twisty a # - # of in maze are you, # - # passages little. # - # # - ########################### - -Normally, the padding values depend on the design. The "shell" design has no default padding, so we can see the effects of our command line option unchanged. `a1l2` stands for "all 1, left 2", and tells *boxes* to put one space (or empty line, in the vertical direction) around the input text block, except for the left side where two spaces shall be used. - - -## Text Padding (2) - -`boxes -p h0v0` - - /************************/ - /*Different all twisty a*/ - /*of in maze are you, */ - /*passages little. */ - /************************/ - -This uses again the default design, which by default features a horizontal padding value of one space (as you know from the very first example). By specifying `-p h0v0`, we set all padding to zero ("horizontal 0, vertical 0"). In this case, the same could have been achieved by `-p h0` or `-p a0`. - - - - -## Regional comments - -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 */ - -`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 *\/ */ - -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 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 */ - -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 particular box design. If you want this to work recursively, simply add more such statements. - - - - -## Box removal - -Imagine your once beautiful box in "C" style like this in your editor, after you are done editing the text inside: - - /********************************************************************/ - - /* Generate sorted listing of available box styles. - Uses design name from BOX spec and sample picture plus author. - */ - /* RETURNS: != 0 on error (out of memory) */ - == 0 on success */ - /********************************************************************/ - -`boxes -r` - - Generate sorted listing of available box styles. - Uses design name from BOX spec and sample picture plus author. - - RETURNS: != 0 on error (out of memory) - == 0 on success - -The box is correctly removed even though it's been badly damaged by editing of the text inside. Obviously, the box design was correctly autodected as being "C". -Note there is only a single leading space in the output text, whereas there are two leading spaces in the input text. This is because the "C" box design has a default horizontal padding of one space. Since *boxes* assumes it has added the padding space, it also attempts to removes the same number of spaces when removing the box. Thus, if you were to add a new box around the text, the box internal indentation would be retained. It is easily possible to use this feature to make an editor key mapping which repairs a box for you (see [installation]({{ site.baseurl}}/docs/install.html) in the documentation section). - - -## Box removal (2) - -Imagine an HTML comment box like the follwing, and imagine that *boxes* does not correctly autodetect it as being an HTML box: - - - - - - - -`boxes -r -d html` - - Different all twisty a - of in maze are you, - passages little. - -In cases where design autodetection fails, **-d** *design_name* can be added to the **-r** command in order to tell *boxes* which design exactly to remove. It is always a good thing to use the **-d** option, because it makes autodetection unnecessary. Autodetection takes more time, because the entire config file must be parsed instead of just the one design needed, and all designs must be matched against the input text in order to see which one fits best. - - - - -## Indentation handling - -For this example, our input text is indented by four spaces: - - Different all twisty a - of in maze are you, - passages little. - -`boxes -d java-cmt -i box` - - // Different all twisty a - // of in maze are you, - // passages little. - -The default indent mode is `box`, which indents the box by the same value as the input text was indented. As shown here, this is useful when adding regional comments to your source code, e.g. when "commenting out" a large portion of your code. Most people generally prefer to indent comments by the same value as the code they refer to, so they don't upset the code structure. - -`boxes -d vim-cmt -i text` - - " Different all twisty a - " of in maze are you, - " passages little. - -By specifying `-i text`, the box is made to start at column zero and any input text indentation is retained inside the box. - -`boxes -d pound-cmt -i none` - - # Different all twisty a - # of in maze are you, - # passages little. - -Finally, it is also possible to throw away any indentation altogether by specifying `-i none`. - - - - -## Use of Regular Expressions - - Global Variables - -`boxes -d headline` - - /*************************************/ - /* G l o b a l V a r i a b l e s */ - /*************************************/ - -The `replace` and `reverse` statements may contain regular expressions and backreferences, which can be used for more elaborate text modifications. The example shown here, where spaces are inserted between the individual characters, is configured [like this](https://github.com/{{ site.github }}/blob/master/boxes-config#L1895-L1898). - -`boxes -d headline -r` - - Global Variables diff --git a/about.html b/about.html index f829220..35692b7 100644 --- a/about.html +++ b/about.html @@ -1,9 +1,41 @@ --- -layout: default +layout: markdown title: Overview --- -{% capture includedMarkdown %}{% include boxes/about.md %}{% endcapture %} -
-{{ includedMarkdown | markdownify }} -
+# ASCII Box Drawing - the *boxes* filter program + + + /*********************/ + boxes draws any /* boxes draws any */ + kind of boxes ===> /* kind of boxes */ + around your text! /* around your text! */ + /*********************/ + +*Boxes* is a [text filter]({{ site.baseurl }}/docs/filters.html) which can draw ASCII art boxes around its input text. These boxes may also be removed, even if they have been badly damaged by editing of the text inside. Since boxes may be open on any side, *boxes* can also be used to create regional comments in any programming language. With the help of an editor macro or mapping, damaged boxes can easily be repaired. + +This is useful for making the function headers in your programming language look better, for spicing up your news postings and emails, or just for decorating your documentation files. + +New box designs of all sorts can easily be added and shared by appending to a free format configuration file. *boxes* was originally intended to be used with the vim(1) text editor, but can be tied to any text editor which supports filters. + + +## Some Of The Features + + - Drawing of ASCII art boxes around input text + - Generation of regional comments in any programming language + - Freely and conveniently user-configurable boxes + - Alignment and positioning of text inside a box + - Removal of boxes, even if box is damaged by editing of contained text + - A number of preconfigured box designs in example config file + - Many useful command line options (such as box size specification etc.) + - Regular expression substitutions on input text + (e.g. used for quoting closing comment tags in a C comment box) + + +## Author + +*Boxes* is developed by Thomas Jensen {{ page.bxemail }}. + +Special thanks go to the many [contributors]({{ site.baseurl }}/contributing.html#contributors), who have helped improve *boxes* over the years. + +*Boxes* is free software. Go and download your copy from the [download page]({{ site.baseurl }}/download.html)! diff --git a/build.html b/build.html index db89d87..4e76bb1 100644 --- a/build.html +++ b/build.html @@ -1,9 +1,82 @@ --- -layout: default +layout: markdown title: Building from Source --- -{% capture includedMarkdown %}{% include boxes/build.md %}{% endcapture %} -
-{{ includedMarkdown | markdownify }} -
+# Building from Source + +Here's how to build your own version of *boxes* using the [boxes sources](https://github.com/{{ site.github }}). + +## Building on Linux / UNIX + +Just unzip the [source archive](https://github.com/{{ site.github }}/releases/latest) or [clone the GitHub repo](https://help.github.com/articles/cloning-a-repository/). Make sure you have your C compiler installed, including [Flex](http://flex.sourceforge.net/) and [Bison](http://www.gnu.org/software/bison/). In the top level directory, type `make && make test`. Find the resulting binary in the *src* folder. In case of problems, check the [compilation faq]({{ site.baseurl }}/docs/faq.html#q5). + +That should be all. *Boxes* is built so that this works almost everywhere. + +## Building on Windows + +Boxes was written for UNIX, but it can also run on Windows! Boxes is a 32bit application, but it works on 64bit systems, too. Here's how to build on Windows. + +> Special thanks go to Ron Aaron, who provided a specially crafted Makefile for win32 and also created the Windows versions of boxes that have been around to this day. + +In order to build *boxes* on Windows, the required win32 executable can be created like this: + +1. Install [MinGW32](http://www.mingw.org/) +2. Configure MinGW32 +3. Open a MinGW shell and run `make win32` + +Basically very simple, but there may be a few pitfalls, so we'll go through each step in detail. + +### 1. Install MinGW32 + +1. Download MinGW from [mingw.org](http://www.mingw.org/) by pressing the **Download Installer** button in the top right corner of the page. You'll receive a mingw-get-setup.exe. +2. Right-click mingw-get-setup.exe and choose **Run as Administrator** from the pop-up menu. + This brings up the Installation Preferences. +3. Choose `C:\MinGW` as installation directory. This is really important. If for some reason you cannot use this highly recommended directory, choose another one that has a short path, does not contain spaces (!), and does not include a Windows "special path". For example, `C:\MinGW_2`. +4. Select "install support for GUI" (yes, even though *boxes* has no GUI) and install "for all users". +5. Press **Continue** and wait for download of the *Installation Manager*. +6. After the download of the Installation Manager is completed, press **Continue** again. + The Installation Manager opens. +7. Choose **mingw32-base** and **msys-base**. Also, further down, under *MSYS / MinGW Developer Toolkit*, choose **msys-bison** and **msys-flex**. + **Do not** install mingw-developer-toolkit, because if on 64bit, this requires tweaking of several environment variables to get gcc to use 32bit libs all around (which may be hard to get right for laymen). +8. In the menu, select *Installation* → *Apply Changes*. + Something like 104 Packages will be installed, which may take a few minutes. +9. Upon success, select *Installation* → *Quit* from the menu. + +### 2. Configure MinGW32 + +1. Change into C:\MinGW\msys\1.0\etc. +2. Copy the file *fstab.sample* to a new file called simply *fstab*. +3. Open *fstab* and make sure that the only lines which are not comments are these: + + c:/mingw /mingw + d:/path/to/boxes /boxes + + Note that the whitespace in this example are tab characters. The d:/path/to/boxes is the path where you placed your clone of the boxes repo. Avoid spaces in its path, too. +4. Add C:\MinGW\bin to your system PATH. +5. Create a "MinGW Shell" shortcut somewhere (I chose my desktop). The shortcut invokes the C:\MinGW\msys\1.0\msys.bat script, which is installed as a component of MSYS; (if you installed to an alternative directory, you should adjust the C:\MinGW prefix accordingly). + An icon file is provided in the same directory, in case you want to set it on the new shortcut. + +### 3. Open a MinGW shell and trigger the Windows build + +1. Double click your new **MinGW Shell** shortcut icon. + This opens a command window with the correct environment set up for you, including the correct path references, allowing you to run any of the MinGW or MSYS applications within that command window. +2. Within the MinGW shell: + + cd /boxes + make clean && make win32 + + If you want to create an executable with debug information, call `make clean && make debug.win32` instead. +3. boxes.exe is created in /boxes/src. +4. Optionally, run `make test` to check that your executable is working OK. + +### 4. Deployment + +In order to run boxes on any Windows machine, two files are required: + +- boxes.exe +- boxes.cfg + +*boxes.cfg* is obtained by simply renaming the *boxes-config* file from the root of the boxes repo into *boxes.cfg*. + +Both files should be placed together somewhere on your PATH. diff --git a/contributing.html b/contributing.html index a745d59..27221d0 100644 --- a/contributing.html +++ b/contributing.html @@ -1,9 +1,79 @@ --- -layout: default +layout: markdown title: Contributing --- -{% capture includedMarkdown %}{% include boxes/contributing.md %}{% endcapture %} -
-{{ includedMarkdown | markdownify }} -
+# Contributing + +You are considering a contribution to *boxes*? That's fantastic! + +All *boxes* development has moved to the GitHub social coding platform: + + - [Sources](https://github.com/{{ site.github }}) + - [Building from Source]({{ site.baseurl }}/build.html) + - [Writing Test Cases]({{ site.baseurl }}/testing.html) + - [Bug Reports and Feature Requests](https://github.com/{{ site.github }}/issues) + - [Change Log](https://github.com/{{ site.github }}/commits/master) + - [History of Releases]({{ site.baseurl }}/docs/releases.html) + +Boxes has been around a long time. It is available for many platforms (in reality for many more than those featured on the [download page]({{ site.baseurl }}/download.html)). Great care has been taken to make the *boxes* source as compatible as possible with all kinds of different platforms. + +The planned functionality has long been implemented, and it is very stable. Development has thus slowed down and concentrates on maintenance and contributor-supplied changes. + +The author can be contacted by email anytime, but please do not be offended when the response is slow. Even if it takes weeks or months, your email is never lost! + +## Contribution Process + +Changes must be introduced by creating pull requests on GitHub. Note that you can improve the *boxes* code as well as the website content! Ideas for new box designs should be submitted via GitHub, but since the most beautiful designs sometimes come from non-technical people, emails are acceptable for those. + +It is best to discuss the planned change before actually doing work on it by [creating an issue for it](https://github.com/{{ site.github }}/issues). This is really not a big deal, but it helps to ensure that your work will end up on the *boxes* master branch. + +In order to create a pull request, you must first [fork the *boxes* repo](https://help.github.com/articles/fork-a-repo/). Then create a new feature branch for your change. Commit the changes to your feature branch. After that, you can [create the pull request](https://help.github.com/articles/using-pull-requests/) against the *boxes* master. + +The pull request must meet the criteria mentioned below. If additional changes are identified during the review, you can simply push them to your forked repo, and the pull request will update automatically. + + +## Pull Request Acceptance Criteria + +Since *boxes* is not actively being developed anymore, changes to the code base must be "production ready" from the start. The following check list may help: + + - The [Travis CI build](https://travis-ci.org/{{ site.github }}) must pass for the pull request. This is indicated by a small green check mark next to your pull request. + - Provide [test cases]({{ site.baseurl}}/testing.html) for any code that you add. This helps make sure that nobody else breaks it later. + - Cross-platform compatibility is very important for *boxes*. Since *boxes* does not (and cannot really) make use of *autoconf*, the C code itself must work on every platform. In other words, you can use only such C commands that are known on every platform. When in doubt, restrict yourself to commands that you already find in the current sources. + +These criteria apply only to code changes. (Although other changes should not break the build, either.) + + +## Contributors + +Now that *boxes* is on GitHub, all contributors are automatically [listed on GitHub](https://github.com/{{ site.github }}/graphs/contributors). But in the years before GitHub, *boxes* has received support from additional people: + + - Ron Aaron - win32 port + - Peter van den Berkmortel - HPUX 10 binaries of v1.0.1 + - Salvatore Bonaccorso - enable compilation on GNU/kFreeBSD and GNU/Hurd; fixes to the man page + - Charles E. Campbell - vim syntax file fixes + - Christoph Dreyer - tab unexpansion + - Andreas Heiduk - bug fixes and compatibility improvements; Jed integration + - Jakub Hrozek - patch to eliminate a compilation warning on Fedora + - Yosuke Kimura - DEC alpha/OSF binaries of v1.0.1 + - Jeff Lanzarotta - contribution to FAQ + - Elmar Loos - 'mend' option + - Zdenek Sekera - SGI/Irix6 binaries of v1.0.1 + - Jason L. Shiffer - Emacs integration + - Henry Spencer - kindly permitted the use of his regular expression library for *boxes* + - Lu Weifeng - OpenWRT port - *boxes* now runs on routers, too + - Tommy Williams - i386/FreeBSD port + - Joe Zbiciak - compatibility improvements and Solaris binaries + + - AlpT - the *c-cmt3* design + - Ted Berg - the *javadoc* design + - Neil Bird - the *ada-cmt* and *ada-box* designs + - Bas van Gils - the *cc* design + - Karl E. Jorgensen - the *ian_jones* design + - Vijay Lakshminarayanan - the *lisp-cmt* design + - Elmar Loos - the *ccel* and *underline* designs + - Christian Molls - the *boxquote* design + - Fredrik Steen - the *stone* design + - Michael Tiernan - the *caml* design + +Many thanks to these awesome folks! diff --git a/download.html b/download.html index f01293e..dbc25c4 100644 --- a/download.html +++ b/download.html @@ -1,9 +1,38 @@ --- -layout: default +layout: markdown title: Downloads --- -{% capture includedMarkdown %}{% include boxes/download.md %}{% endcapture %} -
-{{ includedMarkdown | markdownify }} -
+# Download *Boxes* + +*Boxes* is free software under the GNU General Public License (GNU GPL), version 2. + +The current release is **version 1.1.2**. For older revisions, feel free to browse the [release history]({{ site.baseurl }}/docs/releases.html). + + +## Sources + +The *boxes* sources are now all on GitHub, including previous releases: + +[https://github.com/{{ site.github }}](https://github.com/{{ site.github }}) + +For the (historical) record, the source of the outdated version 1.1 is also on [metalab](ftp://metalab.unc.edu/pub/Linux/utils/text/boxes-1.1.src.tar.gz) (FTP). + + +## Binaries + +The author supports binaries for intel/linux and intel/win32. *Boxes* has been compiled on a very wide variety of platforms, and for older releases, some of these binaries are available via the [release history]({{ site.baseurl }}/docs/releases.html). If you have binaries for different and/or new platforms, please send them in! + +**Windows** and **Linux** binary download: +[https://github.com/{{ site.github }}/releases/latest](https://github.com/{{ site.github }}/releases/latest) + +**MacOS X** +According to *boxes* user *Michel*, *boxes* can be installed on MacOS X (32bit) by simply typing `brew install boxes`. (Information of October 3, 2012) + + +## Miscellaneous + + - The current [list of available box designs]({{ site.baseurl }}/box-designs.txt). + Want to see your design in the official config file? Submit it as a [pull request](https://github.com/{{ site.github }}/pulls) on GitHub. If this seems too complicated, or you are not an IT person, feel free to send email, too. Emails take much longer to be processed, though. + - A vim syntax + file to enable the vim editor to use syntax highlighting with *boxes* config files (beta state). diff --git a/examples.html b/examples.html index 2b6bf69..7f796b7 100644 --- a/examples.html +++ b/examples.html @@ -1,9 +1,310 @@ --- -layout: default +layout: markdown title: Examples --- -{% capture includedMarkdown %}{% include boxes/examples.md %}{% endcapture %} -
-{{ includedMarkdown | markdownify }} -
+# Examples + +Remember, *boxes* is designed to be tied to your editor as a [text filter](docs/filters.html). So these examples assume you need only push a single key (or at least very few) in order to call *boxes*. Don't be worried by seemingly long argument lists - you'll only have to type them once. + +Unless stated otherwise, the input used for these examples is the following: + + Different all twisty a + of in maze are you, + passages little. + + +## Default action + +`boxes` + + /**************************/ + /* Different all twisty a */ + /* of in maze are you, */ + /* passages little. */ + /**************************/ + +Draws a standard box of the first valid design found in your config file. If you have the config file as it comes with the *boxes* distribution, you get a "C" box, as you can see above. + + + + +## Choosing a different design + +`boxes -d parchment` + + ________________________ + /\ \ + \_|Different all twisty a| + |of in maze are you, | + |passages little. | + | ___________________|_ + \_/_____________________/ + +The **-d** *design_name* option selects another design from your config file. + + + + +## Positioning of text inside box + +`boxes -d diamonds -a hcvc` + + /\ /\ /\ + /\//\\/\ /\//\\/\ /\//\\/\ + /\//\\\///\\/\//\\\///\\/\//\\\///\\/\ + //\\\//\/\\///\\\//\/\\///\\\//\/\\///\\ + \\//\/ \/\\// + \/ \/ + /\ Different all twisty a /\ + //\\ of in maze are you, //\\ + \\// passages little. \\// + \/ \/ + /\ /\ + //\\/\ /\//\\ + \\///\\/\//\\\///\\/\//\\\///\\/\//\\\// + \/\\///\\\//\/\\///\\\//\/\\///\\\//\/ + \/\\//\/ \/\\//\/ \/\\//\/ + \/ \/ \/ + +The **-a** *format* option can be used to position the input text inside a box which is larger than needed for our text. `hcvc` stands for "horizontally centered, vertically centered". + +Note that the box was drawn in this size because the shapes that compose it are very big, so that it is not possible to fit the box tighter around our text. Note also that the input lines themselves are *not* centered; `hc` only centers the input text block as a whole. + + +## Line justification + +`boxes -d simple -a jr` + + ************************ + *Different all twisty a* + * of in maze are you,* + * passages little.* + ************************ + +This uses the third possible argument to the **-a** option, `j`. `jr` stands for "justification right". + + +## Quick alignment/positioning + +`boxes -d dog -a c` + + __ _,--="=--,_ __ + / \." .-. "./ \ + / ,/ _ : : _ \/` \ + \ `| /o\ :_: /o\ |\__/ + `-'| :="~` _ `~"=: | + \` (_) `/ + .-"-. \ | / .-"-. + .---{ }--| /,.-'-.,\ |--{ }---. + ) (_)_)_) \_/`~-===-~`\_/ (_(_(_) ( + ( Different all twisty a ) + ) of in maze are you, ( + ( passages little. ) + ) ( + '---------------------------------------' + +Since noone really wants to type `-a hcvcjc` only to actually center text inside a box, there are shorthand notations (`l`, `c`, and `r`). + +Note the blank line at the bottom of the box (after `little`, but before the dashes) which is necessary to make the bottom of the box look right. If the blank line was not there, the box would end on a closing parenthesis, thus looking broken. + + + + +## Box size specification + +`boxes -d html -s 40` + + + + + + + +Using `-s 40`, we have set the box width to 40 characters. + + +## Box size specification (2) + +`boxes -d peek -a c -s 40x11` + + /* _\|/_ + (o o) + +----oOO-{_}-OOo----------------------+ + | | + | | + | Different all twisty a | + | of in maze are you, | + | passages little. | + | | + | | + +------------------------------------*/ + +Using `-s 40x11`, you can set both width and height. Setting just the height is possible with `-s x11` (note the leading `x` on the argument). + + + + +## Text Padding + +`boxes -d shell -p a1l2` + + ########################### + # # + # Different all twisty a # + # of in maze are you, # + # passages little. # + # # + ########################### + +Normally, the padding values depend on the design. The "shell" design has no default padding, so we can see the effects of our command line option unchanged. `a1l2` stands for "all 1, left 2", and tells *boxes* to put one space (or empty line, in the vertical direction) around the input text block, except for the left side where two spaces shall be used. + + +## Text Padding (2) + +`boxes -p h0v0` + + /************************/ + /*Different all twisty a*/ + /*of in maze are you, */ + /*passages little. */ + /************************/ + +This uses again the default design, which by default features a horizontal padding value of one space (as you know from the very first example). By specifying `-p h0v0`, we set all padding to zero ("horizontal 0, vertical 0"). In this case, the same could have been achieved by `-p h0` or `-p a0`. + + + + +## Regional comments + +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 */ + +`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 *\/ */ + +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 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 */ + +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 particular box design. If you want this to work recursively, simply add more such statements. + + + + +## Box removal + +Imagine your once beautiful box in "C" style like this in your editor, after you are done editing the text inside: + + /********************************************************************/ + + /* Generate sorted listing of available box styles. + Uses design name from BOX spec and sample picture plus author. + */ + /* RETURNS: != 0 on error (out of memory) */ + == 0 on success */ + /********************************************************************/ + +`boxes -r` + + Generate sorted listing of available box styles. + Uses design name from BOX spec and sample picture plus author. + + RETURNS: != 0 on error (out of memory) + == 0 on success + +The box is correctly removed even though it's been badly damaged by editing of the text inside. Obviously, the box design was correctly autodected as being "C". +Note there is only a single leading space in the output text, whereas there are two leading spaces in the input text. This is because the "C" box design has a default horizontal padding of one space. Since *boxes* assumes it has added the padding space, it also attempts to removes the same number of spaces when removing the box. Thus, if you were to add a new box around the text, the box internal indentation would be retained. It is easily possible to use this feature to make an editor key mapping which repairs a box for you (see [installation]({{ site.baseurl}}/docs/install.html) in the documentation section). + + +## Box removal (2) + +Imagine an HTML comment box like the follwing, and imagine that *boxes* does not correctly autodetect it as being an HTML box: + + + + + + + +`boxes -r -d html` + + Different all twisty a + of in maze are you, + passages little. + +In cases where design autodetection fails, **-d** *design_name* can be added to the **-r** command in order to tell *boxes* which design exactly to remove. It is always a good thing to use the **-d** option, because it makes autodetection unnecessary. Autodetection takes more time, because the entire config file must be parsed instead of just the one design needed, and all designs must be matched against the input text in order to see which one fits best. + + + + +## Indentation handling + +For this example, our input text is indented by four spaces: + + Different all twisty a + of in maze are you, + passages little. + +`boxes -d java-cmt -i box` + + // Different all twisty a + // of in maze are you, + // passages little. + +The default indent mode is `box`, which indents the box by the same value as the input text was indented. As shown here, this is useful when adding regional comments to your source code, e.g. when "commenting out" a large portion of your code. Most people generally prefer to indent comments by the same value as the code they refer to, so they don't upset the code structure. + +`boxes -d vim-cmt -i text` + + " Different all twisty a + " of in maze are you, + " passages little. + +By specifying `-i text`, the box is made to start at column zero and any input text indentation is retained inside the box. + +`boxes -d pound-cmt -i none` + + # Different all twisty a + # of in maze are you, + # passages little. + +Finally, it is also possible to throw away any indentation altogether by specifying `-i none`. + + + + +## Use of Regular Expressions + + Global Variables + +`boxes -d headline` + + /*************************************/ + /* G l o b a l V a r i a b l e s */ + /*************************************/ + +The `replace` and `reverse` statements may contain regular expressions and backreferences, which can be used for more elaborate text modifications. The example shown here, where spaces are inserted between the individual characters, is configured [like this](https://github.com/{{ site.github }}/blob/master/boxes-config#L1895-L1898). + +`boxes -d headline -r` + + Global Variables