documentation for extended capability stuff

doc/unibi_add_ext_bool.pod

@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+unibi_add_ext_bool, unibi_add_ext_num, unibi_add_ext_str - add extended capabilities to a terminal object
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ size_t unibi_add_ext_bool(unibi_term *ut, const char *t, int b);
+ size_t unibi_add_ext_num(unibi_term *ut, const char *t, short v);
+ size_t unibi_add_ext_str(unibi_term *ut, const char *t, const char *s);
+
+=head1 DESCRIPTION
+
+Add an extended boolean, numeric, or string capability with the specified
+name and value.
+
+Note that these functions simply store any pointers they are given. They will
+not free I<t> or I<s> or copy any strings.
+
+=head1 RETURN VALUE
+
+The return value is the index of the new capability, which can be used in
+L<unibi_get_ext_bool(3)>, L<unibi_set_ext_bool(3)>, etc. If an error occurs,
+C<SIZE_MAX> is returned.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>,
+L<unibi_del_ext_bool(3)>,
+L<unibi_del_ext_num(3)>,
+L<unibi_del_ext_str(3)>
+
+=cut

doc/unibi_add_ext_num.pod

@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+unibi_add_ext_bool, unibi_add_ext_num, unibi_add_ext_str - add extended capabilities to a terminal object
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ size_t unibi_add_ext_bool(unibi_term *ut, const char *t, int b);
+ size_t unibi_add_ext_num(unibi_term *ut, const char *t, short v);
+ size_t unibi_add_ext_str(unibi_term *ut, const char *t, const char *s);
+
+=head1 DESCRIPTION
+
+Add an extended boolean, numeric, or string capability with the specified
+name and value.
+
+Note that these functions simply store any pointers they are given. They will
+not free I<t> or I<s> or copy any strings.
+
+=head1 RETURN VALUE
+
+The return value is the index of the new capability, which can be used in
+L<unibi_get_ext_bool(3)>, L<unibi_set_ext_bool(3)>, etc. If an error occurs,
+C<SIZE_MAX> is returned.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>,
+L<unibi_del_ext_bool(3)>,
+L<unibi_del_ext_num(3)>,
+L<unibi_del_ext_str(3)>
+
+=cut

doc/unibi_add_ext_str.pod

@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+unibi_add_ext_bool, unibi_add_ext_num, unibi_add_ext_str - add extended capabilities to a terminal object
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ size_t unibi_add_ext_bool(unibi_term *ut, const char *t, int b);
+ size_t unibi_add_ext_num(unibi_term *ut, const char *t, short v);
+ size_t unibi_add_ext_str(unibi_term *ut, const char *t, const char *s);
+
+=head1 DESCRIPTION
+
+Add an extended boolean, numeric, or string capability with the specified
+name and value.
+
+Note that these functions simply store any pointers they are given. They will
+not free I<t> or I<s> or copy any strings.
+
+=head1 RETURN VALUE
+
+The return value is the index of the new capability, which can be used in
+L<unibi_get_ext_bool(3)>, L<unibi_set_ext_bool(3)>, etc. If an error occurs,
+C<SIZE_MAX> is returned.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>,
+L<unibi_del_ext_bool(3)>,
+L<unibi_del_ext_num(3)>,
+L<unibi_del_ext_str(3)>
+
+=cut

doc/unibi_count_ext_bool.pod

@@ -0,0 +1,28 @@
+=pod
+
+=head1 NAME
+
+unibi_count_ext_bool, unibi_count_ext_num, unibi_count_ext_str - count extended terminal capabilities
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ size_t unibi_count_ext_bool(const unibi_term *ut);
+ size_t unibi_count_ext_num(const unibi_term *ut);
+ size_t unibi_count_ext_str(const unibi_term *ut);
+
+=head1 DESCRIPTION
+
+These functions count the number of extended (i.e. user specified)
+capabilities of the respective type in I<ut>.
+
+=head1 RETURN VALUE
+
+The number of extended capabilities.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>
+
+=cut

doc/unibi_count_ext_num.pod

@@ -0,0 +1,28 @@
+=pod
+
+=head1 NAME
+
+unibi_count_ext_bool, unibi_count_ext_num, unibi_count_ext_str - count extended terminal capabilities
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ size_t unibi_count_ext_bool(const unibi_term *ut);
+ size_t unibi_count_ext_num(const unibi_term *ut);
+ size_t unibi_count_ext_str(const unibi_term *ut);
+
+=head1 DESCRIPTION
+
+These functions count the number of extended (i.e. user specified)
+capabilities of the respective type in I<ut>.
+
+=head1 RETURN VALUE
+
+The number of extended capabilities.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>
+
+=cut

doc/unibi_count_ext_str.pod

@@ -0,0 +1,28 @@
+=pod
+
+=head1 NAME
+
+unibi_count_ext_bool, unibi_count_ext_num, unibi_count_ext_str - count extended terminal capabilities
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ size_t unibi_count_ext_bool(const unibi_term *ut);
+ size_t unibi_count_ext_num(const unibi_term *ut);
+ size_t unibi_count_ext_str(const unibi_term *ut);
+
+=head1 DESCRIPTION
+
+These functions count the number of extended (i.e. user specified)
+capabilities of the respective type in I<ut>.
+
+=head1 RETURN VALUE
+
+The number of extended capabilities.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>
+
+=cut

doc/unibi_del_ext_bool.pod

@@ -0,0 +1,29 @@
+=pod
+
+=head1 NAME
+
+unibi_del_ext_bool, unibi_del_ext_num, unibi_del_ext_str - remove extended capabilities from a terminal object
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ void unibi_del_ext_bool(unibi_term *ut, size_t i);
+ void unibi_del_ext_num(unibi_term *ut, size_t i);
+ void unibi_del_ext_str(unibi_term *ut, size_t i);
+
+=head1 DESCRIPTION
+
+Remove an extended boolean, numeric, or string capability.
+I<i> is the index of the extended capability to act on; it must be less than
+C<unibi_count_ext_bool(ut)>, C<unibi_count_ext_num(ut)>, or
+C<unibi_count_ext_str(ut)>, respectively.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>,
+L<unibi_add_ext_bool(3)>,
+L<unibi_add_ext_num(3)>,
+L<unibi_add_ext_str(3)>
+
+=cut

doc/unibi_dump.pod

@@ -19,8 +19,8 @@ written to I<p>, which must have room for at least I<n> bytes.
 
 C<unibi_dump> returns the number of bytes required to store the terminfo data.
 If this exceeds I<n>, nothing is written to I<p>. If the terminal object can't
-be represented in terminfo format (string table too large), the return value is
-C<SIZE_MAX>.
+be represented in terminfo format (e.g. because the string table would be too
+large), the return value is C<SIZE_MAX>.
 
 =head1 ERRORS
 

doc/unibi_from_mem.pod

@@ -12,11 +12,14 @@ unibi_from_mem - construct a terminal object from a compiled terminfo entry
 
 =head1 DESCRIPTION
 
-This function parses a compiled terminfo entry that starts at I<p> and is I<n> bytes long and constructs a C<unibi_term> object from it. When you're done with it, you should call C<unibi_destroy> to free it.
+This function parses a compiled terminfo entry that starts at I<p> and is I<n>
+bytes long and constructs a C<unibi_term> object from it. When you're done with
+it, you should call C<unibi_destroy> to free it.
 
 =head1 RETURN VALUE
 
-A pointer to a new C<unibi_term>. In case of failure, C<NULL> is returned and C<errno> is set.
+A pointer to a new C<unibi_term>. In case of failure, C<NULL> is returned and
+C<errno> is set.
 
 =head1 ERRORS
 

doc/unibi_get_ext_bool.pod

@@ -0,0 +1,33 @@
+=pod
+
+=head1 NAME
+
+unibi_get_ext_bool, unibi_set_ext_bool, unibi_get_ext_num, unibi_set_ext_num, unibi_get_ext_str, unibi_set_ext_str - access the extended capabilities of a terminal object
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ int unibi_get_ext_bool(const unibi_term *ut, size_t i);
+ short unibi_get_ext_num(const unibi_term *ut, size_t i);
+ const char *unibi_get_ext_str(const unibi_term *ut, size_t i);
+
+ void unibi_set_ext_bool(unibi_term *ut, size_t i, int b);
+ void unibi_set_ext_num(unibi_term *ut, size_t i, short v);
+ void unibi_set_ext_str(unibi_term *ut, size_t i, const char *s);
+
+=head1 DESCRIPTION
+
+Get/set extended boolean, numeric, and string capabilities.
+I<i> is the index of the extended capability to act on; it must be less than
+C<unibi_count_ext_bool(ut)>, C<unibi_count_ext_num(ut)>, or
+C<unibi_count_ext_str(ut)>, respectively.
+
+Note that C<unibi_set_ext_str> simply stores the pointer it is given; it will
+not free I<s> or make a copy of the string.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>
+
+=cut

doc/unibi_get_ext_bool_name.pod

@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+unibi_get_ext_bool_name, unibi_set_ext_bool_name, unibi_get_ext_num_name, unibi_set_ext_num_name, unibi_get_ext_str_name, unibi_set_ext_str_name - access the names of extended capabilities of a terminal object
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ const char *unibi_get_ext_bool_name(const unibi_term *ut, size_t i);
+ const char *unibi_get_ext_num_name(const unibi_term *ut, size_t i);
+ const char *unibi_get_ext_str_name(const unibi_term *ut, size_t i);
+
+ void unibi_set_ext_bool_name(unibi_term *ut, size_t i, const char *s);
+ void unibi_set_ext_num_name(unibi_term *ut, size_t i, const char *s);
+ void unibi_set_ext_str_name(unibi_term *ut, size_t i, const char *s);
+
+=head1 DESCRIPTION
+
+Get/set the names of extended boolean, numeric, and string capabilities.
+I<i> is the index of the extended capability to act on; it must be less than
+C<unibi_count_ext_bool(ut)>, C<unibi_count_ext_num(ut)>, or
+C<unibi_count_ext_str(ut)>, respectively.
+
+Note that
+C<unibi_set_ext_bool_name>/C<unibi_set_ext_num_name>/C<unibi_set_ext_str_name>
+simply store the pointer they are given; they will not free I<s> or make a
+copy of the string.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>
+
+=cut
+

doc/unibi_get_ext_num.pod

@@ -0,0 +1,33 @@
+=pod
+
+=head1 NAME
+
+unibi_get_ext_bool, unibi_set_ext_bool, unibi_get_ext_num, unibi_set_ext_num, unibi_get_ext_str, unibi_set_ext_str - access the extended capabilities of a terminal object
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ int unibi_get_ext_bool(const unibi_term *ut, size_t i);
+ short unibi_get_ext_num(const unibi_term *ut, size_t i);
+ const char *unibi_get_ext_str(const unibi_term *ut, size_t i);
+
+ void unibi_set_ext_bool(unibi_term *ut, size_t i, int b);
+ void unibi_set_ext_num(unibi_term *ut, size_t i, short v);
+ void unibi_set_ext_str(unibi_term *ut, size_t i, const char *s);
+
+=head1 DESCRIPTION
+
+Get/set extended boolean, numeric, and string capabilities.
+I<i> is the index of the extended capability to act on; it must be less than
+C<unibi_count_ext_bool(ut)>, C<unibi_count_ext_num(ut)>, or
+C<unibi_count_ext_str(ut)>, respectively.
+
+Note that C<unibi_set_ext_str> simply stores the pointer it is given; it will
+not free I<s> or make a copy of the string.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>
+
+=cut

doc/unibi_get_ext_num_name.pod

@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+unibi_get_ext_bool_name, unibi_set_ext_bool_name, unibi_get_ext_num_name, unibi_set_ext_num_name, unibi_get_ext_str_name, unibi_set_ext_str_name - access the names of extended capabilities of a terminal object
+
+=head1 SYNOPSIS
+
+ #include "unibilium.h"
+
+ const char *unibi_get_ext_bool_name(const unibi_term *ut, size_t i);
+ const char *unibi_get_ext_num_name(const unibi_term *ut, size_t i);
+ const char *unibi_get_ext_str_name(const unibi_term *ut, size_t i);
+
+ void unibi_set_ext_bool_name(unibi_term *ut, size_t i, const char *s);
+ void unibi_set_ext_num_name(unibi_term *ut, size_t i, const char *s);
+ void unibi_set_ext_str_name(unibi_term *ut, size_t i, const char *s);
+
+=head1 DESCRIPTION
+
+Get/set the names of extended boolean, numeric, and string capabilities.
+I<i> is the index of the extended capability to act on; it must be less than
+C<unibi_count_ext_bool(ut)>, C<unibi_count_ext_num(ut)>, or
+C<unibi_count_ext_str(ut)>, respectively.
+
+Note that
+C<unibi_set_ext_bool_name>/C<unibi_set_ext_num_name>/C<unibi_set_ext_str_name>
+simply store the pointer they are given; they will not free I<s> or make a
+copy of the string.
+
+=head1 SEE ALSO
+
+L<unibilium.h(3)>
+
+=cut
+