@c AnsiCmd Library User's Guide  - - - - - - - - - - - - - - - - - - - - - - - -
@c 09.0 AcEdit Application   - - - - - - - - - - - - - - - - - - - - - - - - - -
@c      Simple text editor (AnsiCmd API functionality) - - - - - - - - - - - - -
@node AcEdit Demo App
@unnumbered AcEdit Demo App
@cindex 09.0.00 AcEdit Demo App

@menu
* Introduction to AcEdit::    A description of basic functionality
* Invoking AcEdit::           Command line options
* AcEdit Menu System::        Menus and the user interface
* AcEdit Dialogs::            User Interface Dialogs
* AcEdit Configuration::      Customizing the configuration file
* Build AcEdit from Source::  Building AcEdit from Source
@end menu
@sp 2

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@lowersections

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c Chapter 09.01 Introduction to AcEdit  - - - - - - - - - - - - - - - - - - - -
@c               A description of basic functionality  - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Introduction to AcEdit
@unnumbered Introduction to AcEdit
@cindex 09.01 Introduction to AcEdit

@strong{Documentation for the @t{'AcEdit'} demo application is under construction.}

The @b{@t{AcEdit}} application is designed as a platform for testing the 
high-level functionality of the @b{@t{AnsiCmd library}}, and for demonstrating 
various approaches to building applications based on the @t{AnsiCmd} library.@*
For details, @pxref{Top, , AnsiCmd Link Library} at the top of this document.

@t{AcEdit} is a console application, meaning that it runs within a terminal 
window.

@t{AcEdit} is not designed to be a full-featured text editor, although 
subsequent releases may approach full functionality.

@Subheading{AcEdit Features,
            ---------------}

@enumerate 1
@item @t{AcEdit} is invoked like any command-line utility, although the data 
are not displayed as @t{TTY} output. Instead, @t{AcEdit} is a windowed 
application, visually similar to an application built on the @t{"ncurses"} 
library, but vastly more simple in design and execution than an @t{ncurses} 
application.@*
Please visit the author's website for wide variety of applications 
which @emph{are} built on the @t{ncurses} library.

Please @pxref{Invoking AcEdit} for a discussion of all command-line options.

@item Configuration of @t{AcEdit} is performed by reading the @b{@t{ace.cfg}} 
configuration file on startup.@*
Please @pxref{AcEdit Configuration} for more information.

@item Multiple files may be edited simultaneously, so copy and paste among 
the files via a @LDQ{}local@RDQ{} (application-specific) clipboard is 
straightforward.

Access to the system clipboard is enabled by default, so data may 
be seamlessly transferred between @t{AcEdit} and other active applications.@*
@xref{AnsiCmd Clipboard Access} for a discussion of the system clipboard interface.

@item @t{AcEdit} is designed as a multi-language application. Two languages 
are initially supported: English and Chinese (simplified). All LTR 
(left-to-right) character sets are supported. 

Support for RTL languages is too complex for this demonstration app; sorry 
about that. Please see the author's @t{NcDialog API} which includes full 
support for both LTR and RTL languages.
@end enumerate

@Subheading{Building the Application,
            ------------------------}

The application is based on the author's @t{AnsiCmd} link library. The library 
is fully self-contained and the build requires only the GNU compiler and 
its standard dynamic-load libraries.@*
(The compiler version must support the @b{@t{C++17}} functionality which 
became available in GCC v:7.@*
@xref{Build AcEdit from Source} for details.

A local clipboard is built into the library; however, access to the system 
clipboard requires the @b{@t{wl-clipboard}} package which is available for 
downlad on most distribution sites.
@sp 2


@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c Chapter 09.02 Invoking AcEdit - - - - - - - - - - - - - - - - - - - - - - - -
@c               Command line options  - - - - - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Invoking AcEdit
@unnumbered Invoking AcEdit
@cindex 09.02 Invoking AcEdit
@cindex invoking AcEdit
@cindex AcEdit invoking

This chapter lists the command-line options for invoking the @t{AcEdit} (ace).
The @t{'help'} and @t{'version'} options override all other specified options. 

For a detailed discussion of the @t{AnsiCmd} terminal setup options used for 
applications based on the @t{AnsiCmd} link library. 
@ifhtml
@*
@end ifhtml
please @pxref{Invoking - Terminal Setup}.

@Subheading{Summary of Options,------------------}

@indentedblock
@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@headitem @ @ OPTION @tab @ @ DESCRIPTION
@item @ @ @ref{ace color option}          @tab @ application color attributes
@item @ @ @ref{ace language option}       @tab @ user interface language
@item @ @ @ref{ace dimensions option}     @tab @ application height/width
@c @item @ @ @ref{ace cfg option}            @tab @ alternate config file
@item @ @ @ref{ace help option}           @tab @ Display all application
                                               @ options
@item @ @ @ref{ace helpless option}       @tab @ Same as @t{'--help'} option
                                               @ except pipe through @t{'less'}
@item @ @ @ref{ace version option}        @tab @ Reports AcEdit version 
                                               @ number and copyright info.
@item @ @ @t{---} Development Options @t{---}   @tab @ @verb{|    ------------------|}
@item @ @ @ref{ace test option}           @tab @ Sandbox (testing only)
@end multitable
@end indentedblock

All parameters are optional, and may be specified in any order.

For each option that requires one or more arguments, the option name and 
its argument(s) may be separated by either @t{'='} or @t{' '} (space).@*
Note that if the argument contains whitespace, then the entire argument 
sequence must be enclosed within single-quotes or double-quotes.@*
This prevents the terminal's shell program from @i{@LDQ{}interpreting@RDQ{}} 
your argument formatting.

Parsing of command line options requires at least the first six(6) characters 
of the option token.@*
For instance, the @t{"@b{--language}"} token is fully identified 
by the first six characters: @t{@b{--lang}"}.

Avoid specifying the same option multiple times. Multiple instances of 
an option may cause unpredictable results.
@spi

@Subheading{Invocation Options,------------------}
@ifnothtml
@sp 1
@end ifnothtml

@c = = = = = = = = = = = = = =
@c =   file specification    =
@c = = = = = = = = = = = = = =
@indentedblock
@H5heading{Specify file(s) to be edited:,
           ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
@end indentedblock
@enumerate 1
@item Any parameter that does not begin with a dash, @LSQ{}@NDASH{}@RSQ{} character) 
is interpreted as a filename specification.
@enumerate a
@item Specify the filename only, which will be interpreted as a file located 
in the current working directory (CWD).@*
Example: @t{ace strip_cr.pl}

@item Specify a path relative to the CWD.@*
Example: @t{ace "../../Perl Utilities/strip_cr.pl"}

@item Specify a full filespec.@*
Example: @t{ace "/home/sam/Documents/Perl Utilities/strip_cr.pl"}
@end enumerate

@item Environment variable substitutions and special filespec characters 
are supported.@*
@verb{|Example: ace ~/Videos/DVD_List.txt|}@*
@verb{|         ace '${HOME}/Videos/Blu-ray/Videos With Subtitles.txt'|}@*
@verb{|         ace ./Subtitles.txt|}

@item Symbolic links are followed. Example: @t{ace WkExer.lnk}@*
with the link referencing @t{~/Documents/Weekly_Exercise.txt}.

@item Note that the names of files edited in previous sessions will have 
been stored in the configuration file.@*
If the file was open for editing when the application was closed, it will 
automatically be re-opened on application startup.

@item If a filename specified on the command line duplicates a filename saved in 
the configuration file, the duplicate name will be discarded.

@item Only @LDQ{}regular@RDQ{} text files may be edited using @t{AcEdit}. 
For example: Bash scripts, Perl, C, C++, HTML, XML, etc.@*
Binary files and complex files such as LibreOffice documents will be rejected 
for edit.

@end enumerate

@c = = = = = = = = = = = = = =
@c =    --color option       =
@c = = = = = = = = = = = = = =
@anchor{ace color option}
@cindex ace color option
@cindex option, ace color
@ifnothtml
@sp 1
@ @minus{}@minus{}color=BORDER_FG:BORDER_BG@*
@verb{|         [,TEXT_FG:TEXT_BG[,HILITE_FG:HILITE_BG]|}
@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;color=BORDER_FG:BORDER_BG[,TEXT_FG:TEXT_BG[,HILITE_FG:HILITE_BG]</span>
<span style="margin-left:2.0em;">
Application color attributes.
</span></span>
@end html
@indentedblock

@enumerate a
@item Border attributes must be specified.
@item Text-field and cursor-row attributes are optional
@item Application's default value is indicated by zeros for both 
foreground and background values:@*
@t{Example: --color=f00:f00,f10:f04}
@c @item Undocumented: dialog/menu/aux/termwin attributes may be appended.
@end enumerate

Note that selecting a color scheme should normally be done in the 
configuration file. @xref{AcEdit Configuration}.

Command line specification of color attributes mirrors 
the syntax of the config file; and while this makes for efficient coding, 
it is certainly not user friendly. The option sequence is as follows:

@verbatim
--color=Border_FG:Border_BG, Text_FG:Text_BG, Hilite_FG:Hilite_BG
   │     │         │          │       │        │         │
   │     │         │          │       │        │         │
   │     │         │          │       │        │         └ cursor row background
   │     │         │          │       │        └ cursor row foreground
   │     │         │          │       └ text field background
   │     │         │          └ text field foreground
   │     │         └ border background
   │     └ border foreground
   └ option name
@end verbatim

The color options correspond to the terminal color registers for 4-bit 
palette (16 colors), 8-bit palette (256 colors) and 24-bit palette (RGB).

Each specified attribute consists of a single character (case insensitive), 
followed by an integer value.@*
Foreground/Background pairs are seperated by a colon @t{':'}.@*
Color pairs are seperated by a comma @t{','} (and optional whitespace).

@verbatim
   Palette:  Character:  Value Range:
   --------  ----------  ------------
   4-bit       f         00 - 15
   8-bit       e         16 - 231
   24-bit      r         00 - 252

   EXAMPLES:  ace --color="f12:f03"
              ace --color="f00:e38, e16:e21"
              ace --color="f12:f03, r108:r216, r108:r252"
@end verbatim

Please refer to the color chart in the configuration file, or@*
@pxref{AcEdit Configuration} for additional information.
@end indentedblock
@sp 1


@c = = = = = = = = = = = = = =
@c =   --language option     =
@c = = = = = = = = = = = = = =
@anchor{ace language option}
@cindex ace language option
@cindex option, ace language
@ifnothtml
@sp 1
@ @minus{}@minus{}language=[en | zh | te]  User Interface Language
@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;language=[en | zh | te]</span>
<span style="margin-left:2.0em;">
User Interface Language.
</span></span>
@end html
@indentedblock
Specify the user interface language for the application.@*

@t{AcEdit} is designed specifically for multi-language support. The menus, 
dialogs and most informational messages are provided in each supported language. 
An example would be the @LDQ{}Help About@RDQ{} dialog.

@ifnothtml
@verbatim
┌────────────────────────────────────────────────────────────────┐
│ AcEdit (ace): Copyright (c) 2023-2026 v:0.0.05                 │
│               The Software Samurai                             │
│               http://www.SoftwareSam.us/                       │
│                                                                │
│ This application is based upon the author's AnsiCmd library    │
│ which implements the ANSI escape sequences available within a  │
│ Linux terminal window. It is not intended as a full-featured   │
│ text editor; but rather is a testing platform for the AnsiCmd  │
│ library and the ACWin and ACDlg classes within the library.    │
│              AnsiCmd v:0.0.07  WaylandCB    v:0.0.06           │
│              gString v:0.0.37  wl-clipboard v:2.2.1            │
│                             ▒▒OK▒▒                             │
└────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐                                       
│ AcEdit (ace): 版权 (c) 2023-2026 版:0.0.05              │
│               The Software Samurai (软件武士)           │
│               http://www.SoftwareSam.us/                │
│                                                         │
│   该应用程序基于同一作者的 AnsiCmd 库。该库实现了       │
│   Linux 终端窗口内可用的 ANSI 转义序列。它并非一个      │
│   全功能的文本编辑器；而是一个 AnsiCmd 功能的测试平台。 │
│        AnsiCmd 版:0.0.07  WaylandCB    版:0.0.06        │
│        gString 版:0.0.37  wl-clipboard 版:2.2.1         │
│                        ▒▒.好的▒▒                        │
└─────────────────────────────────────────────────────────┘
@end verbatim
@end ifnothtml
@ifhtml
@indentedblock
@html
<div class="tscap" style="background-color:#993300; max-width:38.00em; line-height:1.165em;"><span class="gybl">┌────────────────────────────────────────────────────────────────┐</span>
<span class="gybl">│</span><span class="gybk"> AcEdit (ace): Copyright (c) 2023-2026 v:0.0.05                 </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">               The Software Samurai                             </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">               http://www.SoftwareSam.us/                       </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">                                                                </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk"> This application is based upon the author's AnsiCmd library    </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk"> which implements the ANSI escape sequences available within a  </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk"> Linux terminal window. It is not intended as a full-featured   </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk"> text editor; but rather is a testing platform for the AnsiCmd  </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk"> library and the ACWin and ACDlg classes within the library.    </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">              AnsiCmd v:0.0.07  WaylandCB    v:0.0.06           </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">              gString v:0.0.37  wl-clipboard v:2.2.1            </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">                            <span class="re_r">  <span style="text-decoration:underline">O</span>K  </span>                              </span><span class="gybl">│</span>
<span class="gybl">└────────────────────────────────────────────────────────────────┘</span>
</div>
<br>
@html
<div class="tscap" style="background-color:#993300; max-width:35.00em; line-height:1.165em;"><span class="gybl">┌─────────────────────────────────────────────────────────┐</span>
<span class="gybl">│</span><span class="gybk"> AcEdit (ace): Copyright (c) 2023-2026 v:0.0.05          </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">               The Software Samurai  (<span class="cjk">软件武士</span>)          </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">               http://www.SoftwareSam.us/                </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">                                                         </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">   <span class="cjk">该应用程序基于同一作者的</span> AnsiCmd <span class="cjk">库。该库实现了</span>       </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">   Linux <span class="cjk">终端窗口内可用的</span> ANSI <span class="cjk">转义序列。它并非一个</span>      </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">   <span class="cjk">全功能的文本编辑器；而是一个</span> AnsiCmd <span class="cjk">功能的测试平台。</span> </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">         AnsiCmd v:0.0.07  WaylandCB    v:0.0.06         </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">         gString v:0.0.37  wl-clipboard v:2.2.1          </span><span class="gybl">│</span>
<span class="gybl">│</span><span class="gybk">                       <span class="re_r">  <span class="cjk"><span style="text-decoration:underline">.</span>好的</span>  </span>                         </span><span class="gybl">│</span>
<span class="gybl">└─────────────────────────────────────────────────────────┘</span>
</div>
<!--
hair space : &#8202; or &hairsp;
6-per-em space : &#8198; (no character reference available)
narrow no-break space : &#8239; (no character reference available)
thin space : &#8201; or &thinsp;
4-per-em space : &#8197; or &emsp14;
non breaking space : &#160; or &nbsp;
punctuation space : &#8200; or &puncsp; 
3-per-em space : &#8196; or &emsp13;
en space : &#8194; or &ensp;
figure space : &#8199; or &numsp; 
em space : &#8195; or &emsp;
-->
@end html
@end html
@end indentedblock
@end ifhtml

The current release supports two languages:@*
@verb{| 1) English|}@*
@verb{| 2) Zhōngwén, 中文|} (Chinese, simplified)@*
By default, the application uses the language specified in the terminal 
environment if that language is supported. If the language specified in 
the environment is unsupported, English will be the fall-back language.

Hooks for additional languages are provided, so additional languages 
may be added as desired.

@verbatim
   EXAMPLES:  ace --language=zh     // Zhōngwén interface language
              ace --language=en     // English interface language
              ace --language=te     // Use language specified in 
                                    // terminal environment
              ace                   // language automatically taken
                                    // from terminal environment
@end verbatim

@i{@b{Technical Note:} The command-line code for taking the language from 
the terminal environment is @t{"te"}. This is technically the code for 
Telugu, a Dravidian language of south-eastern India. If an enterprising 
programmer from Telangana builds an application that supports Telugu, 
then we will be happy to assist in making modifications to our code.}@*
@largetext{@ @ @ @ @ @ @ @ @ @ @ @ తెలుగు ఒక అందమైన లిఖిత భాష.}
@c @verb{|            |}తెలుగు ఒక అందమైన లిఖిత భాష.

@end indentedblock
@sp 1

@c = = = = = = = = = = = = = =
@c =  --dimensions option    =
@c = = = = = = = = = = = = = =
@anchor{ace dimensions option}
@cindex ace dimensions option
@cindex option, ace dimensions
@ifnothtml
@sp 1
@ @minus{}@minus{}dimensions @w{   } Report dimensions of terminal window.

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;dimensions</span>
<span style="margin-left:2.0em;">
Report dimensions of terminal window.
</span></span>
@end html

@indentedblock
Report the terminal window dimensions (rows and columns), then exit.

This option can be used when updating the configuration file to specify 
the application dimensions to be used on startup.
@end indentedblock
@sp 1

@ignore
@c = = = = = = = = = = = = = =
@c =      --cfg option       =
@c = = = = = = = = = = = = = =
@anchor{ace cfg option}
@cindex ace cfg option
@cindex option, ace cfg
@sp 1
@end ignore

@c = = = = = = = = = = = = = =
@c =      --test option      =
@c = = = = = = = = = = = = = =
@anchor{ace test option}
@cindex ace test option
@cindex option, ace test

The @LDQ{}@b{Sandbox}@RDQ{} is the traditional name for a section of the 
application code which can be used for testing new functionality without 
disturbing the functional code.

The AcEdit application accesses code within the Sandbox using the 
@t{--test} command-line option. To invoke a specific test, provide the 
test number: @b{@t{ace --test=[0|1|2|3]}}. These tests numbers are 
reserved for ad-hoc tests.

Depending on build options, the Sandbox may also contain several pre-constructed 
test routines for use during regression testing.@*
For a list of available tests, invoke without specifying a test number: 
@b{@t{ace --test}}@*

@example
@b{Example:}

Development Test Menu
00, 01, 02. 03 - Temporary Tests
11 - Test updateFocus/updateText methods
12 - Timestamp Formatting
13 - Terminal Configuration
14 - skField Text Formatting Options
15 - Report locale settings
99 - This Menu
     Press any key to exit...
@end example
@sp 1


@c = = = = = = = = = = = = = =
@c =     --help option       =
@c = = = = = = = = = = = = = =
@cindex ace help option
@cindex option, ace help
@anchor{ace help option}
@ifnothtml
@sp 1
@ @minus{}@minus{}help  (or @minus{}h)  Display command-line help.

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;help &nbsp;&nbsp; (or &ndash;h)</span>
<span style="margin-left:2.0em;">
Display command-line help.
</span></span>
@end html
@indentedblock
Command-line Help. Display a brief summary of command-line usage and 
options.@*
(overrides everything on command line except @w{@t{'--version'})}

@verbatim
   EXAMPLES:  ace --help
              ace -h
@end verbatim
@end indentedblock
@sp 1


@c = = = = = = = = = = = = = =
@c =   --helpless option     =
@c = = = = = = = = = = = = = =
@cindex ace helpless option
@cindex option, ace helpless
@anchor{ace helpless option}
@ifnothtml
@sp 1
@w{ @minus{}@minus{}helpless  (or @minus{}hl)  Display command-line help.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;helpless &nbsp;&nbsp; (or @minus{}hl)</span>
<span style="margin-left:2.0em;">
Display command-line help.
</span></span>
@end html
@indentedblock
Display command-line help. Same as the @t{'--help'} option above except 
that the help menu will be piped through the @t{'less'} utility.

@verbatim
   EXAMPLES:  ace --helpless
              ace -hl
@end verbatim
@end indentedblock
@sp 1


@c = = = = = = = = = = = = = =
@c =    --version option     =
@c = = = = = = = = = = = = = =
@cindex ace version option
@cindex option, ace version
@anchor{ace version option}
@ifnothtml
@sp 1
@w{ @minus{}@minus{}version  Report AcEdit version number.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;version</span>
<span style="margin-left:2.0em;">
Report AcEdit version number.
</span></span>
@end html
@indentedblock
Display the @t{AcEdit} version number and copyright information.@*
(overrides everything else on the command line)@*
The AnsiCmd-class and gString-class version numbers are optionally reported 
by appending the letter @t{'@b{V}'} (verbose) to the command.

@ifhtml
@example
@b{EXAMPLE:  ace --version}
           AcEdit (ace) v:0.0.05 (c) 2023-2026  The Software Samurai            
================================================================================
License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
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.

@b{EXAMPLE:  ace --versionv}
           AcEdit (ace) v:0.0.05 (c) 2023-2026  The Software Samurai            
================================================================================
           AnsiCmd Link Library v:0.0.07  (gString v:0.0.37)                    
--------------------------------------------------------------------------------
License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
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.
@end example
@end ifhtml
@ifnothtml
@format
@b{EXAMPLE:  ace --version}
       AcEdit (ace) v:0.0.05 (c) 2023-2026  The Software Samurai
=========================================================================
License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
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.

@b{EXAMPLE:  ace --versionv}
       AcEdit (ace) v:0.0.05 (c) 2023-2026  The Software Samurai
=========================================================================
       AnsiCmd Link Library v:0.0.07  (gString v:0.0.37)
-------------------------------------------------------------------------
License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
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.
@end format
@end ifnothtml
@end indentedblock
@sp 1

@hr40{}
@sp 2


@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c Chapter 09.03 AcEdit Menu System  - - - - - - - - - - - - - - - - - - - - - -
@c               Menus and the user interface  - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node AcEdit Menu System
@unnumbered AcEdit Menu System
@cindex 09.03 AcEdit Menu System

@Subheading{TEMP - EXPERIMENTAL,-------------------}

Documentation for the @t{'AcEdit'} demo application is under construction.

@sp 2


@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c Chapter 09.04 Dialogs - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c               User Interface Dialogs- - - - - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node AcEdit Dialogs
@unnumbered AcEdit Dialogs
@cindex 09.05 AcEdit Dialogs

@Subheading{TEMP - EXPERIMENTAL,-------------------}

Documentation for the @t{'AcEdit'} demo application is under construction.

@section User Interface Dialogs

@strong{CZONE - AcEdit User Interface Dialogs}

@anchor{AcEdit Crash Recovery}
@section Crash Recovery

All applications, even you humble author's applications, will occasionally 
experience an uncontrolled shutdown, either through a system error or (gasp!), 
due to programmer error. This is primarily due to the developer 
underestimating the absolute stupidity of the user.

When an application crashes for whatever reason, it is possible that it 
will leave behind some potentially recoverable data. The @t{AcEdit} 
application is no exception.

On the next startup following an uncontrolled exit, @t{AcEdit} scans 
for orphaned temporary files and if found compares them with the 
associated source files and asks the user how to handle the recovered data.

The following example demonstrates the dialog window used to obtain the 
user's decision. In this case, an uncontrolled exit was simulated by 
manually creating a temporary backup file associated with the 
file under edit, namely:@*
@b{@verb{|   Welcome_To_AcEdit.txt|}}@*
The backup file is a @LDQ{}hidden@RDQ{} file located in the same directory 
as the file under edit, and takes it name from the source file:@*
@b{@verb{|   .#Welcome_To_AcEdit.txt#|}}@*
This naming convention is similar to that used by other text editors, and 
is useful in recovering data abandoned in an application crash.

The dialog reports the names of the source and recovered files, as well as 
the last modification timestamp and file size for each file.@*
In this example, the recovered file is about three minutes newer than 
the source file and is a different size. This indicates that the recovered 
file may contain useful data. The available options are shown.@*
First, select one of the four Radiobuttons and then press the @t{CONTINUE} 
Pushbutton; or none of the options matches your needs, select the @t{EXIT} 
Pushbutton to abandon the recovered file without modification.

@enumerate 1
@item Compare the two files.@*
Invoke the @t{'diff'} utility to format the contents of the files 
for side-by-side display. The data are displayed using the @t{'less'} 
utility. (Press 'q' key to close @t{'less'} and return to the dialog.)

@item Save the recovered file as "Recovered_nn.txt".@*
Rename the recovered file. The original source file is not modified.@*
Because multiple files may have been orphaned by the previous application 
crash, to prevent accidental overwrite of another file, a serialized 
filename format is used where the @t{"nn"} is replaced by a two-digit 
serial number: @t{Recovered_01.txt, Recovered_02.txt,} etc.
The renamed file can then be moved, renamed or opened for editing if 
desired.

@item Replace the source file with the recovered file.@*
If it is determined that the recovered data are more complete than 
the source file, then the original source file will be renamed as a 
backup file, and the recovered file will be renamed as the source file.@*
@verb{|   Welcome_To_AcEdit.txt     -->  Welcome_To_AcEdit.txt~|}@*
@verb{|   .#Welcome_To_AcEdit.txt#  -->  Welcome_To_AcEdit.txt|}@*
No data are lost. Note that the appended tilde character (@t{'~'}) is 
recognized by Linux system as indicating a @LDQ{}backup@RDQ{} file.

The recovered file will then be opened as if it were the original 
source file. The old source file remains in the current directory 
and can be saved or discarded, as desired.

@item Discard the recovered temporary file.@*
If it is determined that the data in the recovered file are of no 
practical value, use this option to delete the recovered file.
@end enumerate

After the desired operation has been performed, a status message will 
be displayed, and then the dialog will wait for the next keystroke 
before closing.

@ifnothtml
@verbatim
┌────────────┤ Recover Data From Abnormal Shutdown ├───────────┐
│                                                              │
│ Source File    : Welcome_To_AcEdit.txt                       │
│   Last Modified: 18 Oct 2025 17:12:33  Size:    628 bytes    │
│ Recovered File : .#Welcome_To_AcEdit.txt#                    │
│   Last Modified: 18 Oct 2025 17:15:22  Size:    681 bytes    │
│ ─────────── ─────────── ─────────── ─────────── ───────────  │
│  [♦] Compare the two files.                                  │
│  [ ] Save the recovered file as "Recovered_nn.txt".          │
│  [ ] Replace the source file with the recovered file.        │
│  [ ] Discard the recovered temporary file.                   │
│                                                              │
│                 ==CONTINUE==   ====EXIT====                  │
│                                                              │
└──────────────────────────────────────────────────────────────┘
@end verbatim
@end ifnothtml
@ifhtml
@html
<div style=padding-left:8em;">
<div class="tscap" style="text-color:inherit; background-color:inherit; max-width:22.85em; line-height:1.165em;">
<span style="color:white; background-color:blue; font-weight:bold;">┌────────────┤ Recover Data From Abnormal Shutdown ├───────────┐</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">                                                              </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC"> Source File    : Welcome_To_AcEdit.txt                       </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">   Last Modified: 18 Oct 2025 17:12:33  Size:    628 bytes    </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC"> Recovered File : .#Welcome_To_AcEdit.txt#                    </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">   Last Modified: 18 Oct 2025 17:15:22  Size:    681 bytes    </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC"> ─────────── ─────────── ─────────── ─────────── ───────────  </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">  [♦] <span class="ulin">C</span>ompare the two files.                                  </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">  [ ] <span class="ulin">S</span>ave the recovered file as &ldquo;Recovered_nn.txt&rdquo;           </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">  [ ] <span class="ulin">R</span>eplace the source file with the recovered file.        </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">  [ ] <span class="ulin">D</span>iscard the recovered temporary file.                   </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">                                                              </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">                  <span class="brre">  C<span style="text-decoration:underline">O</span>NTINUE  </span>   <span class="brgr">    E<span style="text-decoration:underline">X</span>IT    </span>                 </span><span style="color:white; background-color:blue; font-weight:bold;">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">│</span><span style="background-color:#33FFCC">                                                              </span><span class="gybl">│</span>
<span style="color:white; background-color:blue; font-weight:bold;">└──────────────────────────────────────────────────────────────┘</span>
</div></div>
@end html
@end ifhtml
@spi

You can test this functionality without actually needing to cause a crash 
simply by: 1)closing the application, 2)copying any file that was open for 
edit using the filename format described above, and then 3)reopening the 
application:@*
@verb{|   ./ace MyApp.cpp|}@*
@verb{|   Close the application|}@*
@verb{|   cp --preserve=all 'MyApp.cpp' '.#MyApp.cpp#'|}@*
@verb{|   ./ace|}@*
On startup, the backup file will be recognized, and the recovery dialog 
will be automatically invoked as described above.
@spi

@hr40

@section FileMan - File Management Class
@anchor{FileMan class}
@cindex FileMan class

While the @t{AcEdit} application is designed as a test and demonstration app 
for the @t{AnsiCmd} library, and specifically for the @t{ACWin and ACDlg} 
classes, it reaches a few centimeters into the realm of an actually useful 
console application.

File management within the application is done through an array of 
@b{@t{FileMan}} records, one for each file under edit.@*
While a large number of files can simultaneously be open for edit, the number 
of files which are currently visible is limited by the number of @emph{visible} 
edit fields.@*
Full-window mode: The @LDQ{}@b{active}@RDQ{} FileMan record references the file 
displayed in that field.@*
Dual-window mode: The @LDQ{}@b{active}@RDQ{} FileMan record references the file 
in the field that has the input focus, and the @LDQ{}@b{inactive}@RDQ{} FileMan 
record references the file displayed in the field which is visible, but does 
not have the input focus.@*
Other open (or recently closed) files are reference by other members of the 
FileMan array.
Please @pxref{AcEdit Menu System} for information on navigating among the 
files which are open for edit.

@Subsubheading{@ @ FileMan Class Data Members,
               @ @ ..........................}
@enumerate 1
@item @b{tnFName tnf:} Source file stats data.@*
The data include owner of the file, file type, timestamps, access flags and 
other data which identify the file within the filesystem.
@item @b{char srcSpec @EMDASH S}ou@b{rc}e file@b{Spec}:@*
Filespec of source file. The file may currently be under edit, @emph{OR} 
may have recently been under edit.

@item @b{char wrkSpec @EMDASH W}o@b{rk}ing copy file@b{Spec}@*
Filespec for working copy of source file. This is a @LDQ{}hidden@RDQ{} file 
located in the same directory as the source file. It is an intermediate 
buffer between the text being edited and the source file. It is used for 
auto-save operations and miscellaneous updates; thus protecting the source 
file from possible corruption due to system problems or @i{!gasp!}, program 
error.

@item @b{fldIndex tindx @EMDASH T}extEdit @b{Ind}e@b{x}@*
Index of the TextEdit control in which file data are currently displayed.@*
@i{(Initialized only for @LDQ{}active@RDQ{} records.)}

@item @b{fldIndex lindx @EMDASH L}ine number @b{Ind}e@b{x}@*
Index of the LineNumber control associated with @t{'teindx'}.@*
@i{(Initialized only for @LDQ{}active@RDQ{} records.)}

@item @b{char* scr @EMDASH Scr}atch buffer@*
for tracking miscellaneous data during file edit.@*
This is a pointer to dynamic allocation.
    @enumerate a
    @item [NOT YET DEFINED]
    @item [NOT YET DEFINED]
    @item [NOT YET DEFINED]
    @end enumerate
@item @b{int32_t scrCnt @EMDASH S}ou@b{rc}e @b{C}ou@b{nt}@*
Number of bytes allocated for the @t{'scr'} buffer.

@item @b{int vtop @EMDASH V}ertical @b{Top} row:@*
This is the (1-based) line number of top visible data row in TextEdit control.
    @enumerate a
    @item If the source file was referenced in config file, then this value 
       is initialized from data in the config file.
    @item Afterwards, it tracks the line number of the data row displayed at 
       the top of the field and when updating the LineNum field.
    @item When file is closed (or application is closed) this value is stored 
       in the config file record for the file.
    @end enumerate
@item @b{int voff @EMDASH V}ertical @b{Off}set:
Vertical offset from @t{'vtop'} to cursor line.@*
This value is used to indicate the cursor position when updating the 
gutter field.
    @enumerate a
    @item If the source file was referenced in config file, then this value 
       is initialized from data in the config file.
    @item Afterwards, it tracks the offset from the top display row to the row 
       containing the cursor.
    @item When file is closed (or application is closed) this value is stored 
       in the config file record for the file.
    @end enumerate

@item @b{int hoff @EMDASH H}orizontal @b{Off}set:@*
Character (not column) offset from first character of cursor row to IP 
(Insertion Point).@*
This value is used to indicate the cursor position when updating the 
gutter field.

@item @b{int sindx @EMDASH S}ource @b{Ind}e@b{x}:@*
Index of FileMan record from which the live FileMan data were retrieved.@*
When the data are copied from one record to another, the index of the 
source record is stored in target record so that it can be copied back later, 
either when the file is closed by the user, or when the application exits.@*
@i{(Initialized only for @LDQ{}active@RDQ{} records.)}

@item @b{bool open:}@*
Set if source file is currently open @b{@i{or}} is to be opened on startup.@*
Note that @LDQ{}open@RDQ{} in this case does not mean that the source file 
is literally open. It means that the @emph{data} of the file are currently 
(or about to be) under edit. The source file is opened periodically, and 
only long enough to save updates and then is immediately closed to 
ensure data integrity.

@item @b{bool mods:}@*
Set if TextEdit field data are newer than working copy of the file ('wrkSpec'). 
This indicates that a save to target file is pending.

@item @b{bool wmods:}@*
Set if working copy of file (@t{'wrkSpec'}) is newer than the source file 
(@t{'srcSpec'}). This indicates that a save to source is pending.

@item @b{bool active:}@*
Set when the data of the FileMan record is actively being used during 
file edit (dynamically updated in response to user interaction).

@item @b{int64_t extime @EMDASH Ex}ternal access @b{Time}:@*
Timestamp when file was most recently updated by the application.@*
Used on startup to determine whether file has been modified by another 
application.
@end enumerate

@hr40

@sp 2


@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c Chapter 09.05 AcEdit Configuration  - - - - - - - - - - - - - - - - - - - - -
@c               Customizing the configuration file  - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node AcEdit Configuration
@unnumbered AcEdit Configuration
@cindex 09.05 AcEdit Configuration

@Subheading{Introduction,------------}

The @t{AcEdit} application startup sequence is built around a configuration file, 
@b{@t{ace.cfg}} by default. This file provides definitions for initialization 
of application dimensions, position, color attributes, shortcut keycodes, 
a list of previously open files and other setup information.

@ifnothtml
@example
┌───────────────────────────────────────────────────────────┐
│ The configuration algorithm is not yet fully implemented. │
│ For the current release (@ACEVERSION), the configuration       │
│ file is read on startup, but is not updated on exit.      │
└───────────────────────────────────────────────────────────┘
@end example
@end ifnothtml
@ifhtml
@CartHtml{
The configuration algorithm is not yet fully implemented.
For the current release (@ACEVERSION), the configuration 
file is read on startup, but is not updated on exit.}
@end ifhtml



@Subheading{TEMP - EXPERIMENTAL,-------------------}

Documentation for the @t{'AcEdit'} demo application is under construction.


@sp 2


@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c Chapter 09.06 Build AcEdit from Source  - - - - - - - - - - - - - - - - - - -
@c               Building AcEdit from Source - - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Build AcEdit from Source
@unnumbered Build AcEdit from Source
@cindex 09.06 Build AcEdit from Source

@Subheading{TEMP - EXPERIMENTAL,-------------------}

Documentation for the @t{'AcEdit'} demo application is under construction.

@sp 2

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@raisesections
@sp 2
