185 lines
5.5 KiB
Plaintext
185 lines
5.5 KiB
Plaintext
\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
|