\input texinfo  @c -*-texinfo-*-

@c %**start of header
@setfilename ctlseqs.info
@include version.texi
@settitle ctlseqs @value{VERSION} Manual
@c %**end of header


@copying
This manual is for ctlseqs, a helper library for control sequences.

Copyright @copyright{} 2021  CismonX <admin@@cismon.net>

@quotation
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.3 or any later
version published by the Free Software Foundation; with no Invariant Sections,
with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the
license is included in the section entitled ``GNU Free Documentation License''.
@end quotation
@end copying


@titlepage
@title ctlseqs
@subtitle Helper Library for Control Sequences, version @value{VERSION}
@author CismonX

@page
@vskip 0pt plus 1filll
@insertcopying

@end titlepage


@summarycontents
@contents

@ifnottex
@node Top
@top ctlseqs

This manual is for ctlseqs, a helper library for control sequences.

Permission is granted to copy, distribute and/or modify this document under the
terms of the @pxref{GNU Free Documentation License}, Version 1.3 or any later
version published by the Free Software Foundation; with no Invariant Sections,
with no Front-Cover Texts, and with no Back-Cover Texts.

ctlseqs is free software. You can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
@end ifnottex


@menu
* Overview::                   Brief overview of ctlseqs.
* Control Sequence Matching::  Using ctlseqs for matching control sequences.
* Control Sequence Reading::   Using ctlseqs for reading control sequences.
* Tips::                       Tips & hints for using ctlseqs.
* Example Programs::           Example programs using ctlseqs.

Appendices

* API Reference::                   C API reference for ctlseqs.
* GNU Free Documentation License::  Copying conditions of this manual.

@end menu


@node Overview
@chapter Overview of ctlseqs

The name ``ctlseqs'' is an abbreviation of ``control sequences'', as defined
in section 5.4 of ECMA-48.

As the name suggests, this library focuses on handling control sequences.
However, it only cares about the bit combinations, while the actual meaning
and implementation of a control sequence is up to the user.

The C API provided by ctlseqs is composed of three major parts: The helper
macros, the control sequence matcher, and the control sequence reader. Any of
them can be used separatedly or combined.

@menu
* Contributing::   Contributing to ctlseqs.
* Use Scenarios::  When to use ctlseqs.
@end menu


@node Contributing
@section Contributing

We welcome any form of contribution to ctlseqs (as well as this manual),
including bug reports, patches, etc.

As ctlseqs is primarily @url{https://sv.gnu.org/p/ctlseqs, hosted on Savannah},
it is recommended to contribute using the bug tracker and patch manager.
Sending an email to @email{bug-report@@cismon.net} is also a viable option.

@cindex Checklist for bug reports
An effective bug report should contain enough information to reproduce the bug,
which may contain:

@itemize @bullet
@item The version number of ctlseqs involved.
@item A minimal code snippet to reproduce the bug.
@item Expected and actual behaviour of the program.
@item A core file for the crashed program.
@item Name of the operating system and hardware.
@end itemize

@cindex Checklist for patch submission
Before you submit a patch for ctlseqs, it is recommended to:

@itemize @bullet
@item Follow the existing coding style.
@item Discuss with the community about new features or breaking changes.
@item Write test cases, documentation and changelogs for your code.
@end itemize


@node Use Scenarios
@section Use Scenarios of ctlseqs

Control sequences, as well as other control functions, were once commonly used
in computer terminals. Terminals exchange control information with the host
regarding colors, font styles, cursor position, etc., using control functions
embedded in normal text. Such physical terminals are no longer used today,
however, popular ones like DEC VT100 are widely emulated by modern terminal
emulators.

The primary purpose of the ctlseqs library is to provide developers with a set
of simple and easy-to-use API for handling control functions, when working on
terminal emulators and text-based programs.

However, while there is no de facto standard, control functions used in
terminals are largely vendor-specific, and terminal emulators like to add their
own private controls. That makes ctlseqs not suitable for writing text-based
programs which intend to be portable. Instead of raw control codes, the
developer should stick to ncurses or terminfo.

@cindex List of common use cases of ctlseqs
There are still cases when dealing with raw escape sequences is inevitable, and
ctlseqs may come in handy:

@itemize @bullet
@item Development of text-based programs which rely heavily on special control
sequences, which is not supported by libraries like ncurses.
@item Implementing a terminal emulator.
@item Experimenting or debugging the features of text-based programs or
terminal emulators.
@end itemize


@node Control Sequence Matching
@chapter Control Sequence Matching


@node Control Sequence Reading
@chapter Control Sequence Reading


@node Tips
@chapter Tips & Hints


@node Example Programs
@chapter Example Programs


@node API Reference
@appendix API Reference


@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi


@bye