diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi index 7494c7f..b252185 100644 --- a/doc/ctlseqs.texi +++ b/doc/ctlseqs.texi @@ -13,12 +13,11 @@ This manual is for ctlseqs, a helper library for control sequences. Copyright @copyright{} 2021 CismonX @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