.Dd 2020-10-22
.Dt gemtext 3
.Os
.Sh NAME
.Nm gemtext_encode ,
.Nm gemtext_encode_fd ,
.Nm gemtext_encode_file ,
.Nm gemtext_list_encode ,
.Nm gemtext_list_encode_fd ,
.Nm gemtext_list_encode_file
.Nd Gemini text encoding functions
.Sh SYNOPSIS
.In gemtext.h
.Ft int
.Fo gemtext_encode
.Fa "struct gemtext *line"
.Fa "char **textptr"
.Fa "size_t *lenptr"
.Fc
.Ft int
.Fo gemtext_encode_fd
.Fa "struct gemtext *line"
.Fa "int fd"
.Fc
.Ft int
.Fo gemtext_encode_file
.Fa "struct gemtext *line"
.Fa "consr char *path"
.Fc
.Ft int
.Fo gemtext_list_encode
.Fa "struct gemtext **list"
.Fa "char **textptr"
.Fa "size_t *lenptr"
.Fc
.Ft int
.Fo gemtext_list_encode_fd
.Fa "struct gemtext **list"
.Fa "int fd"
.Fc
.Ft int
.Fo gemtext_list_encode_file
.Fa "struct gemtext **list"
.Fa "const char *path"
.Fc
.Ft int
.Fo gemtext_list_encode_to_html
.Fa "struct gemtext **list"
.Fa "char **textptr"
.Fa "size_t *lenptr"
.Fc
.Ft int
.Fo gemtext_list_encode_to_html_fd
.Fa "struct gemtext **list"
.Fa "int fd"
.Fc
.Ft int
.Fo gemtext_list_encode_to_html_file
.Fa "struct gemtext **list"
.Fa "const char *path"
.Fc
.Sh DESCRIPTION
.Fn gemtext_encode
encodes
.Em line
to
.Nm text/gemini
and sets pointer pointed to by
.Em textptr
to the encoded text and sets
.Em size_t
pointed to by
.Em lenptr
to the size of the encoded text excluding terminating NULL byte, this can be discarded by setting
.Em lenptr
to NULL.
.Pp
Upon success, pointer set at
.Em *textptr
should be passed to
.Fn free 3
after use.
.Pp
.Fn gemtext_encode_fd
and
.Fn gemtext_encode_file
are wrappers for
.Fn gemtext_encode
where
.Fn gemtext_encode_fd
writes the output to file descriptor specified in
.Em fd
and
.Fn gemtext_encode_file
writes the output to a file within the file system, specified in
.Em path .
.Pp
.Fn gemtext_list_encode ,
.Fn gemtext_list_encode_fd
and
.Fn gemtext_list_encode_file
behave the same as the
.Fn gemtext_encode
family of functions, except they operate on a list of
.Em struct gemtext*
terminated by a NULL pointer.
.Pp
.Fn gemtext_list_encode_to_html ,
.Fn gemtext_list_encode_to_html_fd
and
.Fn gemtext_list_encode_to_html_file
behave the same as the
.Fn gemtext_list_encode
family of functions, except the output provided in
.Em textptr
is formatted in HTML instead of gemtext.
.Sh RETURN VALUES
.Fn gemtext_encode ,
.Fn gemtext_encode_fd ,
.Fn gemtext_encode_file ,
.Fn gemtext_list_encode ,
.Fn gemtext_list_encode_fd ,
.Fn gemtext_list_encode_file ,
.Fn gemtext_list_encode_to_html ,
.Fn gemtext_list_encode_to_html_fd
and
.Fn gemtext_list_encode_to_html_file
all return
.Em 0
on success or
.Em -1
on error.
.Sh CAVEATS
Text encoded using
.Fn gemtext_encode ,
.Fn gemtext_encode_fd
and
.Fn gemtext_encode_file
will not include terminating
.Em LF
character while
.Fn gemtext_list_encode ,
.Fn gemtext_list_encode_fd
and
.Fn gemtext_list_encode_file
will append
.Em LF
character after each object in the list, including the last.
.Pp
.Fn gemtext_list_encode_to_html ,
.Fn gemtext_list_encode_to_html_fd
and
.Fn gemtext_list_encode_to_html_file
will only convert each gemtext line to the corresponding HTML tag, output could be modified later to add opening and closing
.Em html
and
.Em body
tags along with other metadata.
.Sh SEE ALSO
.Xr gemtext_decode 3 ,
.Xr gemtext_text_new 3 ,
.Xr gemtext_type 3 ,
.Xr gemtext_text_string 3 ,
.Xr gemtext_text_strlen 3 ,
.Xr gemtext_list_append 3 ,
.Xr gemtext_free 3
.Sh AUTHORS
.An Ali Fardan Aq Mt raiz@stellarbound.space