Update documentation.
continuous-integration/drone/push Build is passing
Details
continuous-integration/drone/push Build is passing
Details
This commit is contained in:
parent
99ee98fc23
commit
164b3601a3
118
doc/ctlseqs.texi
118
doc/ctlseqs.texi
|
@ -13,12 +13,11 @@ This manual is for ctlseqs, a helper library for control sequences.
|
||||||
Copyright @copyright{} 2021 CismonX <admin@@cismon.net>
|
Copyright @copyright{} 2021 CismonX <admin@@cismon.net>
|
||||||
|
|
||||||
@quotation
|
@quotation
|
||||||
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document under
|
||||||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
the terms of the GNU Free Documentation License, Version 1.3 or any later
|
||||||
any later version published by the Free Software Foundation; with no
|
version published by the Free Software Foundation; with no Invariant Sections,
|
||||||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the
|
||||||
Texts. A copy of the license is included in the section entitled
|
license is included in the section entitled ``GNU Free Documentation License''.
|
||||||
``GNU Free Documentation License''.
|
|
||||||
@end quotation
|
@end quotation
|
||||||
@end copying
|
@end copying
|
||||||
|
|
||||||
|
@ -44,30 +43,29 @@ Texts. A copy of the license is included in the section entitled
|
||||||
|
|
||||||
This manual is for ctlseqs, a helper library for control sequences.
|
This manual is for ctlseqs, a helper library for control sequences.
|
||||||
|
|
||||||
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document under the
|
||||||
under the terms of the @pxref{GNU Free Documentation License}, Version 1.3 or
|
terms of the @pxref{GNU Free Documentation License}, Version 1.3 or any later
|
||||||
any later version published by the Free Software Foundation; with no
|
version published by the Free Software Foundation; with no Invariant Sections,
|
||||||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
with no Front-Cover Texts, and with no Back-Cover Texts.
|
||||||
Texts.
|
|
||||||
|
|
||||||
ctlseqs is free software. You can redistribute it and/or modify it under
|
ctlseqs is free software. You can redistribute it and/or modify it under the
|
||||||
the terms of the GNU General Public License as published by the
|
terms of the GNU General Public License as published by the Free Software
|
||||||
Free Software Foundation, either version 3 of the License, or (at your option)
|
Foundation, either version 3 of the License, or (at your option) any later
|
||||||
any later version.
|
version.
|
||||||
@end ifnottex
|
@end ifnottex
|
||||||
|
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Overview:: Brief overview of ctlseqs.
|
* Overview:: Brief overview of ctlseqs.
|
||||||
* Control Sequence Matching:: Using ctlseqs for matching control sequences.
|
* Control Sequence Matching:: Using ctlseqs for matching control sequences.
|
||||||
* Control Sequence Reading:: Using ctlseqs for reading control sequences.
|
* Control Sequence Reading:: Using ctlseqs for reading control sequences.
|
||||||
* Tips:: Tips & hints for using ctlseqs.
|
* Tips:: Tips & hints for using ctlseqs.
|
||||||
* Example Programs:: Example programs using ctlseqs.
|
* Example Programs:: Example programs using ctlseqs.
|
||||||
|
|
||||||
Appendices
|
Appendices
|
||||||
|
|
||||||
* API Reference:: C API reference for ctlseqs.
|
* API Reference:: C API reference for ctlseqs.
|
||||||
* GNU Free Documentation License:: Copying conditions of this manual.
|
* GNU Free Documentation License:: Copying conditions of this manual.
|
||||||
|
|
||||||
@end menu
|
@end menu
|
||||||
|
|
||||||
|
@ -82,9 +80,79 @@ As the name suggests, this library focuses on handling control sequences.
|
||||||
However, it only cares about the bit combinations, while the actual meaning
|
However, it only cares about the bit combinations, while the actual meaning
|
||||||
and implementation of a control sequence is up to the user.
|
and implementation of a control sequence is up to the user.
|
||||||
|
|
||||||
The C API provided by ctlseqs is composed of three major parts: The
|
The C API provided by ctlseqs is composed of three major parts: The helper
|
||||||
helper macros, the control sequence matcher, and the control sequence reader.
|
macros, the control sequence matcher, and the control sequence reader. Any of
|
||||||
Any of them can be used separatedly or combined.
|
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
|
@node Control Sequence Matching
|
||||||
|
|
Loading…
Reference in New Issue