From 019426ecacf4c85936acafb7e5494b29f9e0d4c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 10 Oct 2023 00:16:27 +0200 Subject: Include calp documentation. A bad gitignore ignored much more than it should have. Now updated to only ignore top level binary. --- doc/ref/calp/error.texi | 55 ++++++++++++++++++++ doc/ref/calp/other.texi | 113 ++++++++++++++++++++++++++++++++++++++++++ doc/ref/calp/translation.texi | 31 ++++++++++++ 3 files changed, 199 insertions(+) create mode 100644 doc/ref/calp/error.texi create mode 100644 doc/ref/calp/other.texi create mode 100644 doc/ref/calp/translation.texi (limited to 'doc') diff --git a/doc/ref/calp/error.texi b/doc/ref/calp/error.texi new file mode 100644 index 00000000..a8937b84 --- /dev/null +++ b/doc/ref/calp/error.texi @@ -0,0 +1,55 @@ +@node Errors and Conditions +@section Errors and Conditions + +@subsection ``Special'' Errors + +@deftp{Error type} return +Thrown in some sub-mains to quickly return from the sub-function. +Should possibly be replaced by an explicit return-continuation. +@end deftp + +@deftp{Error type} warning fmt args +Thrown when @code{warnings-are-errors} is true. + +@ref{warning} for more information. +@end deftp + +@deftp{Error type} max-page page-number +@end deftp + +@subsection ``Regular'' Errors +All below mentioned error types behave as expected, e.g., they are +produced through @code{scm-error}. + +@deftp{Error Type} configuration-error +Thrown by (calp util config), in some scenarios. +@TODO{Better documentation} +@end deftp + +@deftp{Error Type} c-parse-error +Errors thrown by our make-shift C parser. +@end deftp + +@deftp{Error Type} decoding-error +thrown by base64 in some cases +@end deftp + +@deftp{Error Type} parse-error +Thrown by some things related to parsing, but not all. +@TODO{normalize parsing errors further} +@end deftp + +@deftp{Error Type} graph-error +The first element of data is guaranteed to be the graph which caused +the error. +@end deftp + +@deftp{Error Type} missing-helper +A helper program we wanted was missing, could be resolved by somehow +downloading it into one of the searched locations. + +@example +data : (program-name : string) + , (searched-locations : (list string)) +@end example +@end deftp diff --git a/doc/ref/calp/other.texi b/doc/ref/calp/other.texi new file mode 100644 index 00000000..443f68d0 --- /dev/null +++ b/doc/ref/calp/other.texi @@ -0,0 +1,113 @@ +@node Other +@section Other + +@c TODO most of this text is surpassed by data formats and data stores. + +@defun get-parser type +@example +get-parser ∷ type-name → hash-table x string → any +type = 'BINARY | 'BOOLEAN | 'CAL-ADDRES | 'DATE | 'DATE-TIME + | 'DURATION | 'FLOAT | 'INTEGER | 'PERIOD | 'RECUR + | 'TEXT | 'TIME | 'URI | 'UTC-OFFSET +@end example + +@ref{ical-get-writer} +@end defun + +@subsection formats ical +@subsubsection output + +@defun component->ical-string component +@end defun + +@defun print-components-with-fake-parent events +@end defun + +@defun print-all-events +@end defun + +@defun print-events-in-interval start end +@end defun + +@subsubsection parse + +@defun parse-calendar port +@end defun + +@subsubsection types + +@defun escape-chars str +Escape @code{,}, @code{;} and @code{\} with a +backslash, and encode newlines as @code{\n}. +@end defun + +@defun get-writer type +@anchor{ical-get-writer} +@example +get-writer ∷ type-name → hash-table x value → string +type = 'BINARY | 'BOOLEAN | 'CAL-ADDRES | 'DATE | 'DATE-TIME + | 'DURATION | 'FLOAT | 'INTEGER | 'PERIOD | 'RECUR + | 'TEXT | 'TIME | 'URI | 'UTC-OFFSET +@end example +@end defun + +@subsection formats vdir +@subsubsection parse + +@defun parse-vdir path +@end defun + +@subsubsection save-delete + +@defun save-event event +@end defun + +@defun remove-event event +@end defun + +@subsection formats xcal +@subsubsection output + +@defun vcomponent->sxcal component +@end defun + +@defun ns-wrap +@lisp +(define (ns-wrap sxml) + `(icalendar (@@ (xmlns "urn:ietf:params:xml:ns:icalendar-2.0")) + ,sxml)) +@end lisp +Where @var{sxml} is expected to be the output of @var{vcomponent->sxcal}. +@end defun + +@subsubsection parse +@defun sxcal->vcomponent sxcal +Parses a vcomponent in sxcal format. Requires that the vcomponent is +the root of the document (fragment), so wrapping icalendar-tags or +similar @emph{must} be removed. + +@example +(vcalendar + (properties ...) + (components ...)) +@end example +@end defun + +@subsubsection types +@defun get-writer type +@ref{ical-get-writer} +@end defun + + +@c -------------------------------------------------- + +@c TODO +This chapter will probably in the future be replaced by a proper +system overview in the future. + +@c module (vcomponent control) + +@defmac with-replaced-properties (component (key value) ...) body ... +Through the extent of @var{body} each @var{key}'s value in +@var{component} is replaced by its repspective @var{value}. +@end defmac diff --git a/doc/ref/calp/translation.texi b/doc/ref/calp/translation.texi new file mode 100644 index 00000000..0e710c47 --- /dev/null +++ b/doc/ref/calp/translation.texi @@ -0,0 +1,31 @@ +@node Translation +@section Translation + +Base for string translation in the application. Calp uses Guile's +built in gettext bindings. The text domain used is ``calp''. + +@defun translate str +@anchor{translate} +Translate a string from english into an (through enviroment) specified +target language. All newlines in the source string will be changed to +spaces. + +This procedure is both used as the ``backend'' for @ref{G_}, but also +for non-literal strings which should be translated. +@end defun + +@defun G_ msg ... +@anchor{G_} +The ``global'' binding indicating a string to be translated. + +All arguments must be strings, and will be concatenated before being +passed to @ref{translate} (meaning newlines will be ignored). +@end defun + +@defun yes-no-check string [locale=%global-locale] +Checks @var{string} if it's a yes or no response in the given +@var{locale}. + +Returns @code{'yes} or @code{'no}, or @code{#f} if the string couldn't +be parsed as a yes/no predicate in the current locale. +@end defun -- cgit v1.2.3