From 4d5d13b5e86dce1db72649204021882fbab668a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 12 Sep 2023 10:10:57 +0200 Subject: Change overarching structure of info document. --- doc/ref/calp-prime.texi | 179 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 doc/ref/calp-prime.texi (limited to 'doc/ref/calp-prime.texi') diff --git a/doc/ref/calp-prime.texi b/doc/ref/calp-prime.texi new file mode 100644 index 00000000..89decb1b --- /dev/null +++ b/doc/ref/calp-prime.texi @@ -0,0 +1,179 @@ +@node Calp as a Program +@chapter Calp as a Program + +@include guile/translation.texi + +@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 + + + +@node Other +@section Other + +@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}. + +Note that @var{body} is guarded through a dynamic-wind, meaning that +even non-local exits will restore @var{component} to its initial +state. +@end defmac + -- cgit v1.2.3 From 108a0454d05c744c4a05e298cfc8cbf157952414 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 12 Sep 2023 10:23:59 +0200 Subject: Rework file tree structure for info files. --- doc/ref/calp-prime.texi | 177 +----------------------------------------------- 1 file changed, 3 insertions(+), 174 deletions(-) (limited to 'doc/ref/calp-prime.texi') diff --git a/doc/ref/calp-prime.texi b/doc/ref/calp-prime.texi index 89decb1b..a13cbd0b 100644 --- a/doc/ref/calp-prime.texi +++ b/doc/ref/calp-prime.texi @@ -1,179 +1,8 @@ @node Calp as a Program @chapter Calp as a Program -@include guile/translation.texi +@include calp/translation.texi +@include calp/error.texi +@include calp/other.texi -@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 - - - -@node Other -@section Other - -@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}. - -Note that @var{body} is guarded through a dynamic-wind, meaning that -even non-local exits will restore @var{component} to its initial -state. -@end defmac -- cgit v1.2.3