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 ++++++++++++++++++++++++++++++++++++++++++++ doc/ref/calp.texi | 5 +- doc/ref/general.texi | 15 ++++ doc/ref/guile.texi | 193 ------------------------------------------------ doc/ref/guile/util.texi | 11 +-- doc/ref/vcomponent.texi | 4 + doc/ref/web.texi | 4 + 7 files changed, 210 insertions(+), 201 deletions(-) create mode 100644 doc/ref/calp-prime.texi create mode 100644 doc/ref/general.texi delete mode 100644 doc/ref/guile.texi create mode 100644 doc/ref/vcomponent.texi create mode 100644 doc/ref/web.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 + diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index b9e8723d..c0a7f3cd 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -64,8 +64,11 @@ text @footnote{Improvements welcome} @c * Index:: @c @end menu -@include guile.texi +@include calp-prime.texi @include entry-points.texi +@include general.texi +@include vcomponent.texi +@include web.texi @include text.texi @include vulgar.texi diff --git a/doc/ref/general.texi b/doc/ref/general.texi new file mode 100644 index 00000000..0b54205a --- /dev/null +++ b/doc/ref/general.texi @@ -0,0 +1,15 @@ +@node Generally Useful Utilities +@chapter Generally Useful Utilities + +@include guile/datetime.texi +@include guile/zic.texi +@include guile/srfi-41.texi +@include guile/util.texi +@include guile/util-path.texi +@include guile/util-config.texi +@include guile/util-exceptions.texi +@include guile/base64.texi +@include guile/xdg-basedir.texi +@include guile/glob.texi +@include guile/graphviz.texi +@include guile/crypto.texi diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi deleted file mode 100644 index 1e8d44fd..00000000 --- a/doc/ref/guile.texi +++ /dev/null @@ -1,193 +0,0 @@ -@node Guile -@chapter Guile - -@include guile/datetime.texi -@include guile/zic.texi -@include guile/srfi-41.texi -@include guile/util.texi -@include guile/util-path.texi -@include guile/util-config.texi -@include guile/util-exceptions.texi -@include guile/base64.texi -@include guile/xdg-basedir.texi -@include guile/web.texi -@include guile/vcomponent.texi -@include guile/translation.texi -@include guile/glob.texi -@include guile/graphviz.texi -@include guile/crypto.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 - diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi index e7accf90..d4dce3a6 100644 --- a/doc/ref/guile/util.texi +++ b/doc/ref/guile/util.texi @@ -1,8 +1,5 @@ -@node General Utilities -@section General Utilities - @node Miscellaneous utilities -@subsection Miscellaneous utilities +@section Miscellaneous utilities Provided by the module @code{(hnh util)}. @@ -362,7 +359,7 @@ last. @end defmac @node UUIDs -@subsection UUID generation +@section UUID generation Provided by module @code{(hnh util uuid)}. @@ -380,7 +377,7 @@ this module. Only set this when you want non-random randomness. @end deftp @node IO operations -@subsection IO +@section IO Provided by module @code{(hnh util io)}. @@ -412,7 +409,7 @@ Open file at path, and return its content as a string. @end defun @node Binary Search Tree -@subsection Binary Search Tree +@section Binary Search Tree A simple ``read only'' binary search tree. diff --git a/doc/ref/vcomponent.texi b/doc/ref/vcomponent.texi new file mode 100644 index 00000000..0aa7806c --- /dev/null +++ b/doc/ref/vcomponent.texi @@ -0,0 +1,4 @@ +@node VComponents +@chapter VComponents + +@include guile/vcomponent.texi diff --git a/doc/ref/web.texi b/doc/ref/web.texi new file mode 100644 index 00000000..342b6852 --- /dev/null +++ b/doc/ref/web.texi @@ -0,0 +1,4 @@ +@node Webservers and -Clients +@chapter Webservers and -Clients + +@include guile/web.texi -- cgit v1.2.3