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
GPG Key ID:
3094873E29A482FB
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>
|
||||
|
||||
@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''.
|
||||
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
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
* 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.
|
||||
* API Reference:: C API reference for ctlseqs.
|
||||
* GNU Free Documentation License:: Copying conditions of this manual.
|
||||
|
||||
@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
|
||||
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.
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue