## TECO-64 Internals Notes

### Overview

This document is a work in progress. It provides a description of the
design of TECO-64 for the benefit of those who maintain or enhance it,
as well as those who are curious about how it is structured.

### History

TECO-64 development began in October 2019 a on Linux/Ubuntu system,
using *gcc* and other GNU tools.
It has been successfully executed on Linux, Windows 10, and MacOS,
although testing on the latter two is currently out of date.
It was also successfully compiled on VMS, but was not able to be
executed in that environment owing to the absence of additional
run-time library support.

### Development

The general guidelines used during development were:

- Familiarity – Use names that are either familiar to the reader
(e.g., with a Linux-like directory structure), or which are otherwise
descriptive of their purpose (e.g., er_cmd.c for a file which processes
the ER command).
- Consistency – Use the same conventions in one place that are used in
another (e.g., all functions which process specific commands have names
of the form exec_*()).
- Readability – Use names that can be pronounced (as opposed to an alphabet
soup of acronyms), and as much as possible, use names that include verbs
(e.g., reset_term() or clear_win()).
- Simplicity – Avoid long functions. Also avoid large files containing
numerous unrelated functions, and don’t duplicate code.
- Modularity – Hide details of functions and modules as much as possible.
This has made it possible to have more than one method for handling data
in the edit buffer, and more than one method for handling paging.

### Testing & Debugging

- *assert()* statements were used to verify run-time assumptions, including
the validity of function parameters.
- PC-Lint was used to verify the correctness of code and detect possible bugs.
- Valgrind was used to detect memory leaks, as was some added debug code.
- *strace* was used to profile system calls.
- *gprof* was used to profile function and library calls.
- *gdb* was used for debugging.

### Documentation

- Doxygen comments were used in source code to provide in-line
documentation.
- XML and XSL files were used to create documentation as well as code
defining TECO command-line options.
- Markdown files were created for the README file, system-dependent setup
notes, and the TECO reference manual.

### Directory Names

- `./` - Contains the makefile used to build TECO, and the README.md file.
- `./bin` - Contains the TECO-64 executable.
- `./doc` - Contains Markdown documentation files.
- `./etc` - Contains files used to build and test TECO.
    - `./etc/build` - Contains supplemental files used by *make*.
    - `./etc/pattern` - Contains files that are used in conjunction with XML
and XSL files to generate other files used to compile code or create
documentation.
    - `./etc/xml` - Contains XML and XSL files that defines the run-time errors,
the command-line options, and TECO's commands.
- `./html` - Contains documentation files generated by Doxygen.
- `./include` - Contains .h header files used for building TECO, as well as
several files that will be generated if needed during the build process.
- `./lib` - Contains examples of TECO macro files.
- `./obj` - Contains generated object files created during the build process.
- `./src` - Contains the .c source files used to build TECO, and a configuration
file used by PC-Lint.
- `./test` - Contains test scripts and other files used to test TECO commands
and features.

### File Names

- `cmd_*.c` - Files that perform general processing of TECO commands.
- `*_cmd.c` - Files that perform a specific TECO command (e.g., er_cmd.c
contains code for processing ER commands), or perform multiple related
TECO commands (e.g., yank_cmd.c contains code for processing commands
that yank data into memory).
- `*_buf.c` - Files that implement an interface for command, edit, or
terminal buffers.
    - `cmd_buf.c` - Implements a command buffer interface.
    - `gap_buf.c` – Implements an edit buffer interface using a gap buffer
 method.
    - `term_buf.c` - Implements a terminal buffer interface.
- `page_*.c` - Files that provide an interface for paging forward (and
possibly backward) through a file. Only one of the following is used
in any specific build:
    - `page_file.c` – Writes pages to output file, uses a temporary file
to allow for backwards paging (TBD).
    - `page_std.c` – Writes pages to output file; no backwards paging
implemented (classic TECO paging method).
    - `page_vm.c` – Writes pages to output file only when file is closed;
virtual memory is used to store pages, which allows for backwards paging.
- `term_*.c` - Files that process terminal input and output.
- `*_sys.c` - Files that provide interfaces to system-dependent features.
Code in all other files should be system-independent, but this is subject
to change during further testing.

### Function Names

- `*_cbuf()` - Functions that implement a command buffer interface.
- `cmd_*()` - Functions that provide general processing for TECO commands.
- `*_dpy()` - Functions that implement a display window interface.
- `*_edit()` - Functions that implement a edit buffer interface.
- `exec_*()` - Functions that execute specific TECO commands.
- `*_tbuf()` - Functions that implement a terminal buffer interface.
