BuildCart Application

BuildCart - Release Notes

Copyright 2023-2024 by The Software Samurai.
On the web: http://www.SoftwareSam.us/
Software released under GNU GPL3, and documentation released under FDL1.3
This document describes version 0.0.01 of BuildCart.

Description

The Build Cartouche (‘BuildCart’) utility is a GNU/Linux console application which can be used to convert any block of text into a formatted text block enclosed within a border.

This application was designed under Fedora Linux and is built using the GNU C compiler,
version 13.3.1 or higher (C++17 support required).
If you are not using GCC, then verify that your compiler fully supports the C++17 standard.

Cartouche: A type of shen ring, which is an oval border surrounding and protecting its contents. This was originally used to enclose the name of an Egyptian royal person. Later the word cartouche was used to describe the area of a map enclosing the name of the cartographer. Thus, using the cartouche in your documents makes you royalty (or at least a cartographic artist). Welcome to BuildCart, your Royalness!

Building From Source

Download and unpack the distribution archive.
- Navigate to the base directory where package will be installed (example):
  cd ~/SoftwareDesign
- Move the archive file to the base directory:
  mv ~/Dowloads/buildcart-0.0.01.tar.bz2 .
- Unpack the tar archive:
  tar -xjvf buildcart-0.0.01.tar.bz2
- Navigate to the target directory:
  cd BuildCart

After unpacking the archive, the directory will look something like this:

/home/sam/SoftwareDesign/BuildCart/BuildCart.hpp   <== Application class definition
                                  /BuildCart.cpp   <== Application definition and implementation
                                  /gString.hpp     <== gString class definition
                                                       (text analysis and formatting)
                                  /gString.cpp     <== gString class implementation 
                                  /Makefile        <== Build the 'bcart' application
                                  /README          <== Package description, release notes

Build the application:
gmake all

The GNU G++ compiler is invoked to build and link the binary executable file.
The application should build without errors and without warnings.

Test the build:
./bcart − −version
The application version and a copyright message should be displayed.

BuildCart (bcart) v:0.0.01  Copyright (c) 2023-2024 The Software Samurai
========================================================================
License GPLv3+: GNU GPL version 3 
This is free software: you are free to modify and/or redistribute it
under the terms set out in the license.
There is NO WARRANTY, to the extent permitted by law.

For invocation options, type:
./bcart − −help
See the next section for a description of command-line options.
Make the application visible on the system $PATH:
This can be done in either of two ways:
  1) copy the executable to a directory on the path:
      cp − −preserve=all ./bcart ~/usr/local/bin/.
  2) create a symbolic link to the executable in the source directory.
      cp − −symbolic-link ./bcart ~/usr/local/bin/.

Operational Overview

The BuildCart application's user interface is “fire-and-forget”; that is, application control is entirely through the specified command-line options, and direct user interaction is not required.

The source text may be specified directly on the command line, or may be read from a file.
Text may be pre-formatted, meaning that the cartouche border will be drawn around the text without modifying the text in any way. Alternatively, the text can be automatically reformatted to fit within a specified column width and row height, and the cartouche border will then be drawn around the reformatted block.
The application accepts source text up to 16Kbytes of UTF-8 data. This is equivalent to at least one full typewritten page of text.

Output is written to the terminal window, which may then be highlighted using the mouse, and copied (SHIFT+CTRL+C) to the clipboard. It may then be pasted into any open document, presumably the source document for your documentation project.
Optionally, the output may also be written to a target file.

It is recommended that the generated object be placed in one of the Texinfo block text constructs; either a “@verbatim” block or an “@example” block.
Note that in the example shown here, the generated cartouche object is used for non-HTML output, while the HTML output takes advantage of the automatically-generated cartouche object created through the Texi macro “CartHtml” defined in the author's Infodoc package.

@ifnothtml @example ┌────────────────────────────────────────────────┐ │ Outside of a dog, a book is man's best friend. │ │ Inside of a dog, it's too dark to read. │ │ -- Groucho Marx │ └────────────────────────────────────────────────┘ @end example @end ifnothtml @ifhtml @CartHtml{Outside of a dog, a book is man's best friend. Inside of a dog, it's too dark to read. – Groucho Marx} @end ifhtml

The current BuildCart release is a stand-alone application; however, this functionality will be integrated into the Infodoc Styles package once the algorithm is stable.

This application relies heavily on our gString text-analysis tool which parses the source data, reformats the data to the specified dimensions, and then almost effortlessly draws the border around the text block.
For a full discussion of the gString class, please see the documentation for the author's NcDialog API package, or the stand-alone gString text-analysis-and-formatting package. gString Documentation

Command-line Options

Invocation: bcart [OPTIONS]

Options may be specified in any order.
Options are case sensitive.
The ‘– –help’ option overrides everything except the ‘– –version’ option.
The ‘– –version’ option overrides all other options.
Source text for the cartouche must be specified, either directly (–t option) or from a file (– –sfile option).
All other parameters are optional.

–t=TEXT Text data to be enclosed within the cartouche.

Enclose the block of text within quotation marks, and be sure to “escape” any embedded quotation marks.
The data may be typed directly, or may be copied from another application and pasted into the terminal window using the SHIFT+CTRL+V key combination (or press mouse button two).

The special text sequence, “–” (a single minus character) may be used to create an empty cartouche.
bcart –t=“–” –h=5 –w=32
This invocation will generate an empty cartouche with five(5) rows and thirty-two(32) columns.

–w=WIDTH Specify object width in columns.

By default, the height and width of the cartouche object are calculated from the source text‘s rows and columns.
If a width for the object is specified, however, the source text will be reformatted as necessary to fit within the specified width. Example: bcart ––sfile=‘mydata.txt’ –w=48
The source data for this example is approximately 80 columns wide. The text is reformatted to the specified
48-column width minus the columns reserved for the horizontal padding and borders.
↓ ---------------- 48 columns ---------------- ↓ ┌──────────────────────────────────────────────┐ │ China is being buffeted by two weather │ │ extremes, with heavy rain and flooding │ │ forcing the evacuation of tens of thousands │ │ of people in the south and a heat wave │ │ prompting fears of a drought for farmers in │ │ the north.At least one person has died in │ │ the flooding. The body of a student who │ │ fell into a swollen river in the southern │ │ city of Guilin was found two days later on │ │ Saturday, state broadcaster CCTV said in an │ │ online report. Elsewhere in the Guangxi │ │ region, heavy rains flooded homes in some │ │ villages. -- Associated Press 17-Jun-2024 │ └──────────────────────────────────────────────┘

–h=HEIGHT Specify minimum object height in rows.

By default, the height of the cartouche object is calculated as the number of text rows plus the top and bottom borders.
By specifying a minimum object height, empty rows will be added between the end of text and the bottom border to reach the specified height. If the text plus borders is greater than or equal to the specified minimum, then no filler rows will be added.

–p=PADDING Specify the amount of horizontal padding between border and text.

This option specifies the padding (number of space characters) to the left and right of the text seperating the text from the border of the cartouche. The default value is one(1) padding column at left and right margins.
Example: bcart ––sfile=‘mydata.txt’ –p=3

┌────────────────────────────────────────────┐ │ One padding column at each end of the row. │ └────────────────────────────────────────────┘ ┌───────────────────────────────────────────────────┐ │ Three padding columns at each end of the row. │ └───────────────────────────────────────────────────┘

–s=STYLE Specify the border style.

Borders of the cartouche object are constructed using common line-drawing characters. The current release of BuildCart implements three line styles: single-line, dual-line and dashed-line; as well as bold text options for single-line and dashed-line options.

┌─────────────────────────────────────────┐ │ –s=s : This is a single-line cartouche. │ └─────────────────────────────────────────┘ ╔═══════════════════════════════════════╗ ║ –s=d : This is a dual-line cartouche. ║ ╚═══════════════════════════════════════╝ ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐ ┆ –s=D : This is a dashed-line cartouche. ┆ └╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ –s=b : This is a bold single-line cartouche. ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┏╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┓ ╏ –s=B : This is a bold dashed-line cartouche. ╏ ┗╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┛

– –sfile=FILENAME Specify the file containing the source text.

The source text may be read from a plain-text file. The specified file must be in the current working directory (CWD). The contents of the file will be read up to the limit of the source buffer, or until a line containing only the literal token, “#EOF” (end-of-file) is encountered.

Note that source text specified using the “–t” option takes precedence over the “– –sfile” option, so if both are specified, the ‘sfile’ option will be ignored.

– –tfile=FILENAME Specify a file to receive a copy of the output.

The formatted cartouce object is written to the terminal window where it can then be copied and pasted into your document. In addition, a copy of the object can be written to a file. The specified file must be in the current working directory (CWD).

If the target file does not exist, it will be created. If the target file already exists, the data are appended to the end of the file so any existing data will not be lost.

It is therefore practical to specify the same file as both the source file and the target file.
Example: bcart –w=48 ––sfile=‘mycart.txt’ ––tfile=‘mycart.txt’
The following illustration shows “mycart.txt” before and after the operation.
China is being buffeted by two weather extremes, with heavy rain and flooding forcing the evacuation of tens of thousands of people in the south and a heat wave prompting fears of a drought for farmers in the north. #EOF BECOMES China is being buffeted by two weather extremes, with heavy rain and flooding forcing the evacuation of tens of thousands of people in the south and a heat wave prompting fears of a drought for farmers in the north. #EOF BuildCart: Create Texinfo Cartouche. ┌──────────────────────────────────────────────┐ │ China is being buffeted by two weather │ │ extremes, with heavy rain and flooding │ │ forcing the evacuation of tens of thousands │ │ of people in the south and a heat wave │ │ prompting fears of a drought for farmers in │ │ the north. │ └──────────────────────────────────────────────┘

– –help Display application help, then exit.
– –version Display application version and copyright information.

Notes on the current release of “BuildCart”

The files included in this release.

BuildCart/ // Source code directory BuildCart.hpp // Application class definition BuildCart.cpp // Application source code gString.hpp // Text analysis engine (definition) gString.cpp // Text analysis engine (implementation) Makefile // Build the 'bcart' application README // Package description, release notes

Note: The change log is located in the header of “BuildCart.cpp”.

These notes are adapted from the “README” file included with the application archive.
Thank you, and we hope you enjoy using this application! — Software Sam

(Yes, this is an HTML cartouche!)