From df9b6b429bc1f04c57c0944a7118d62f895457f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 5 Jan 2021 23:59:07 +0100 Subject: Start on propper documentation (of js so far). --- doc/ref/Makefile | 6 ++ doc/ref/calp.texi | 49 +++++++++ doc/ref/javascript.texi | 276 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 331 insertions(+) create mode 100644 doc/ref/Makefile create mode 100644 doc/ref/calp.texi create mode 100644 doc/ref/javascript.texi (limited to 'doc') diff --git a/doc/ref/Makefile b/doc/ref/Makefile new file mode 100644 index 00000000..2da2dd43 --- /dev/null +++ b/doc/ref/Makefile @@ -0,0 +1,6 @@ +TEXI_FILES := $(wildcard *.texi) + +all: calp.info + +calp.info: $(TEXI_FILES) + makeinfo calp.texi diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi new file mode 100644 index 00000000..a2408f89 --- /dev/null +++ b/doc/ref/calp.texi @@ -0,0 +1,49 @@ +\input texinfo +@settitle Calp + +@copying +Copyright @copyright{} 2020 Hugo Hörnquist +@end copying + +@c Borrowed from guile.texi +@c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be used +@c when the quotes that @code{} gives in info aren't wanted, but the +@c fontification in tex or html is wanted. @alias is used rather +@c than @macro because backslashes don't work properly in an @macro. +@ifinfo +@alias nicode=asis +@end ifinfo +@ifnotinfo +@alias nicode=code +@end ifnotinfo + +@titlepage +@title Calp +@author Hugo Hörnquist + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Calp +@end ifnottex + +@c @menu +@c * Index:: +@c @end menu + +@include javascript.texi + +@node Index +@unnumbered Index +@printindex cp +@printindex fn +@printindex tp +@printindex vr + +@bye diff --git a/doc/ref/javascript.texi b/doc/ref/javascript.texi new file mode 100644 index 00000000..e2049a77 --- /dev/null +++ b/doc/ref/javascript.texi @@ -0,0 +1,276 @@ +@node Javascript +@chapter Javascript + + +@node arbitary_kv +@section arbitary_kv.js + +@node binders +@section binders.js + +@node clock +@section clock.js + +@node date_time +@section date_time.js + +@node dragable +@section dragable.js + +@node input_list +@section input_list.js + +@node jcal +@section jcal.js + +@node lib +@section lib.js + +General procedures which in theory could be used anywhere. + +@defvar xcal +The xml namespace name for xcalendar, which is +``urn:ietf:params:xml:ns:icalendar-2.0''. +@end defvar + + +@node Default prototype extensions +@subsection Default prototype extensions + +HTMLElement extensions + +@defmethod HTMLElement addEventListener name proc +Replace the default @code{addEventListener} with a version that stores +all listeners in the dictionary @var{listeners}. +@end defmethod + +@defivar HTMLElement listeners +Dictionary of all registered listeners to this element. +Keys are taken from @code{addEventListener}. +@end defivar + +@defmethod DOMTokenList find regexp +Finds the first element of the DOMTokenList whichs value matches +the supplied regexp. Returns a pair of the index and the value. +@end defmethod + +@defmethod Object format args ... +Returns a string representation of the given object. +Allows extending for custom types, +@ref{date-format} +@end defmethod + +@node General +@subsection General + +@defun zip args ... +Takes a list of lists, and returns a single list of tuples. +@example +» zip([1,2,3,4,5], "Hello") +← [[1,'H'],[2,'e'],[3,'l'],[4,'l'],[5,'o']] +@end example +@end defun + +@defun makeElement name [attr=@{@}] +Creates a new DOM element of type @var{name}, with all keys in +@var{attr} transfered to it. For example, the equivalent of +@example + +@end example +would be +@verbatim +values.push(makeElement('input', { + type: 'number', +})); +@end verbatim +. +@end defun + +@defun round_time time fraction +TODO +@end defun + +@defun date_to_percent date +Retuns how far along the date specified by @var{date} is, between 0 +and 100, where 00:00 maps to 0, and 23:59 to ~100. +@end defun + +@defun gensym [pxrefix='gensym'] +Generates a new string which is (hopefully) globally unique. +Compare with @code{gensym} from Lisp. +@end defun + +@defun setVar str val +Set the CSS var @var{str} to @var{val} on the root element. +@end defun + +@defun asList thing +Ensures that @var{thing} is a list. Returning it outright if it +already is one, otherwise wrapping it in a list. +@end defun + +@node Date +@subsection Date + +Some extensions to the builtin class ``Date'' is made. + +@defivar Date utc +Boolean indicating if the given timestamp is in UTC or local time. +true means UTC. +@end defivar + +@defivar Date dateonly +Boolean indicating if the time component of the Date object should be disregarded. +@end defivar + +@defun parseDate str +Takes a string @var{str}, which should be in ISO-8601 date-format, and +returns a javascript Date object. +@end defun + +@defun copyDate date +Creates a new instance of the given Date @var{date}, also transfers my +custom fields. +@end defun + +@defun to_local date +@anchor{to_local} +Returns a Date object (which may be new) which is guaranteed in local +time. +This means that the @var{utc} field is @code{false}, and that +@code{to_local(current_time())} should show what your wall-clock shows. +@end defun + +@defmethod Date format str args ... +@anchor{date-format} +Formats a Date object according to the format specification @var{str}. +Keeping with Guile each format specifier starts with a ~. + +@c table formatting borrowed from Gulie Reference (SRFI-19 Date to string) +@multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{~~} @tab literal ~ +@c Almost all fields are left padded. How do I signify this +@c with a single footnote? +@item @nicode{~Y} @tab year, left-padding with zeroes. +@item @nicode{~m} @tab month number, left padded with zeroes. +@item @nicode{~d} @tab day of month. +@item @nicode{~H} @tab hour +@item @nicode{~M} @tab minute +@item @nicode{~S} @tab second +@item @nicode{~Z} @tab 'Z' if Date is UTC, otherwise nothing + +@item @nicode{~L} @tab Converts the date to local time +(@pxref{to_local}) (doesn't modify source object). Outputs nothing +@end multitable +@end defmethod + +@defun format_date date str +Equivalent to @code{(@var{date}).format(@var{str})}. +@c TODO link +@end defun + + +@node popup +@section popup.js + +@node rrule +@section rrule.js + +@node script +@section script.js + +@dfn{Main} for my javascript, and also currently dumping ground for stuff. + +@deftp {class} EventCreator + +@defmethod EventCreator create_empty_event +@end defmethod + +@defmethod EventCreator create_event_down intended_target +@end defmethod + +@defmethod EventCreator create_event_move pos_in [round=1] [wide_element=false] +@end defmethod + +@defmethod EventCreator create_event_finisher callback +@end defmethod + +@end deftp + +@defun place_in_edit_mode event +@end defun + +@c window.onload is here in source file + +@defun get_property event field default_value +Returns the @emph{value} slot of given field in @var{event}, creating it if needed. + +@itemize +@item +@var{el}: the event to work on + +@item +@var{field}: name of the field + +@item +@var{default_value}: default value when creating + +@item +@var{bind_to_ical} should this property be added to the icalendar subtree? +@end itemize +@end defun + +@defun bind_properties el [wide_event=false] + Properties are icalendar properties. + + p['name'] to get and set value (also updates any connected slots) + + p['_value_name'] for raw value + p['_slot_name'] for connected slots, Vector of pairs, where the + car should be a reference to the slot, and the + cdr a procedure which takes a slot and a value + and binds the value to the slot. +@end defun + +@node server_connect +@section server_connect.js + +@node types +@section types.js + +Collection of type information for calendar data. + +@defvar all_types +Name of all valid icalendar types. + + text, uri, binary, float, integer, date-time, date, duration, + period, utc-offset, cal-address, recur, boolean, +@end defvar + +@defvar property_names +All known names properties (top level keys) can have. +Such as ``calscale'', ``dtstart'', ... +@end defvar + +@defvar valid_fields +Which property fields each component can hold. + +@verbatim +{ 'VCALENDAR': ['PRODID', 'VERSION', 'CALSCALE', 'METHOD'], + ... +} +@end verbatim +@end defvar + +@defvar valid_input_types +Which types are valid to store under each property. +If multiple values are an option for that property, then +the list of possibilities will contain a sub-list (see example). + +@verbatim +{ 'DTSTART': ['date', 'date-time'], + 'CATEGORIES': [['text']], + ... +} +@end verbatim +@end defvar -- cgit v1.2.3 From 34c12d524d3a9238e174864220ab04adaf0cd7d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Wed, 6 Jan 2021 01:16:11 +0100 Subject: Split javascript doc into multiple files. --- doc/ref/Makefile | 3 +- doc/ref/javascript.texi | 286 ++------------------------------- doc/ref/javascript/arbitary_kv.texi | 3 + doc/ref/javascript/binders.texi | 4 + doc/ref/javascript/clock.texi | 4 + doc/ref/javascript/date_time.texi | 4 + doc/ref/javascript/draggable.texi | 4 + doc/ref/javascript/input_list.texi | 4 + doc/ref/javascript/jcal.texi | 4 + doc/ref/javascript/lib.texi | 147 +++++++++++++++++ doc/ref/javascript/popup.texi | 5 + doc/ref/javascript/rrule.texi | 4 + doc/ref/javascript/script.texi | 58 +++++++ doc/ref/javascript/server_connect.texi | 2 + doc/ref/javascript/types.texi | 39 +++++ 15 files changed, 297 insertions(+), 274 deletions(-) create mode 100644 doc/ref/javascript/arbitary_kv.texi create mode 100644 doc/ref/javascript/binders.texi create mode 100644 doc/ref/javascript/clock.texi create mode 100644 doc/ref/javascript/date_time.texi create mode 100644 doc/ref/javascript/draggable.texi create mode 100644 doc/ref/javascript/input_list.texi create mode 100644 doc/ref/javascript/jcal.texi create mode 100644 doc/ref/javascript/lib.texi create mode 100644 doc/ref/javascript/popup.texi create mode 100644 doc/ref/javascript/rrule.texi create mode 100644 doc/ref/javascript/script.texi create mode 100644 doc/ref/javascript/server_connect.texi create mode 100644 doc/ref/javascript/types.texi (limited to 'doc') diff --git a/doc/ref/Makefile b/doc/ref/Makefile index 2da2dd43..35dd6604 100644 --- a/doc/ref/Makefile +++ b/doc/ref/Makefile @@ -1,6 +1,7 @@ TEXI_FILES := $(wildcard *.texi) +INFOFLAGS := all: calp.info calp.info: $(TEXI_FILES) - makeinfo calp.texi + makeinfo $(INFOFLAGS) calp.texi diff --git a/doc/ref/javascript.texi b/doc/ref/javascript.texi index e2049a77..d53ce2d0 100644 --- a/doc/ref/javascript.texi +++ b/doc/ref/javascript.texi @@ -1,276 +1,16 @@ @node Javascript @chapter Javascript - -@node arbitary_kv -@section arbitary_kv.js - -@node binders -@section binders.js - -@node clock -@section clock.js - -@node date_time -@section date_time.js - -@node dragable -@section dragable.js - -@node input_list -@section input_list.js - -@node jcal -@section jcal.js - -@node lib -@section lib.js - -General procedures which in theory could be used anywhere. - -@defvar xcal -The xml namespace name for xcalendar, which is -``urn:ietf:params:xml:ns:icalendar-2.0''. -@end defvar - - -@node Default prototype extensions -@subsection Default prototype extensions - -HTMLElement extensions - -@defmethod HTMLElement addEventListener name proc -Replace the default @code{addEventListener} with a version that stores -all listeners in the dictionary @var{listeners}. -@end defmethod - -@defivar HTMLElement listeners -Dictionary of all registered listeners to this element. -Keys are taken from @code{addEventListener}. -@end defivar - -@defmethod DOMTokenList find regexp -Finds the first element of the DOMTokenList whichs value matches -the supplied regexp. Returns a pair of the index and the value. -@end defmethod - -@defmethod Object format args ... -Returns a string representation of the given object. -Allows extending for custom types, -@ref{date-format} -@end defmethod - -@node General -@subsection General - -@defun zip args ... -Takes a list of lists, and returns a single list of tuples. -@example -» zip([1,2,3,4,5], "Hello") -← [[1,'H'],[2,'e'],[3,'l'],[4,'l'],[5,'o']] -@end example -@end defun - -@defun makeElement name [attr=@{@}] -Creates a new DOM element of type @var{name}, with all keys in -@var{attr} transfered to it. For example, the equivalent of -@example - -@end example -would be -@verbatim -values.push(makeElement('input', { - type: 'number', -})); -@end verbatim -. -@end defun - -@defun round_time time fraction -TODO -@end defun - -@defun date_to_percent date -Retuns how far along the date specified by @var{date} is, between 0 -and 100, where 00:00 maps to 0, and 23:59 to ~100. -@end defun - -@defun gensym [pxrefix='gensym'] -Generates a new string which is (hopefully) globally unique. -Compare with @code{gensym} from Lisp. -@end defun - -@defun setVar str val -Set the CSS var @var{str} to @var{val} on the root element. -@end defun - -@defun asList thing -Ensures that @var{thing} is a list. Returning it outright if it -already is one, otherwise wrapping it in a list. -@end defun - -@node Date -@subsection Date - -Some extensions to the builtin class ``Date'' is made. - -@defivar Date utc -Boolean indicating if the given timestamp is in UTC or local time. -true means UTC. -@end defivar - -@defivar Date dateonly -Boolean indicating if the time component of the Date object should be disregarded. -@end defivar - -@defun parseDate str -Takes a string @var{str}, which should be in ISO-8601 date-format, and -returns a javascript Date object. -@end defun - -@defun copyDate date -Creates a new instance of the given Date @var{date}, also transfers my -custom fields. -@end defun - -@defun to_local date -@anchor{to_local} -Returns a Date object (which may be new) which is guaranteed in local -time. -This means that the @var{utc} field is @code{false}, and that -@code{to_local(current_time())} should show what your wall-clock shows. -@end defun - -@defmethod Date format str args ... -@anchor{date-format} -Formats a Date object according to the format specification @var{str}. -Keeping with Guile each format specifier starts with a ~. - -@c table formatting borrowed from Gulie Reference (SRFI-19 Date to string) -@multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} -@item @nicode{~~} @tab literal ~ -@c Almost all fields are left padded. How do I signify this -@c with a single footnote? -@item @nicode{~Y} @tab year, left-padding with zeroes. -@item @nicode{~m} @tab month number, left padded with zeroes. -@item @nicode{~d} @tab day of month. -@item @nicode{~H} @tab hour -@item @nicode{~M} @tab minute -@item @nicode{~S} @tab second -@item @nicode{~Z} @tab 'Z' if Date is UTC, otherwise nothing - -@item @nicode{~L} @tab Converts the date to local time -(@pxref{to_local}) (doesn't modify source object). Outputs nothing -@end multitable -@end defmethod - -@defun format_date date str -Equivalent to @code{(@var{date}).format(@var{str})}. -@c TODO link -@end defun - - -@node popup -@section popup.js - -@node rrule -@section rrule.js - -@node script -@section script.js - -@dfn{Main} for my javascript, and also currently dumping ground for stuff. - -@deftp {class} EventCreator - -@defmethod EventCreator create_empty_event -@end defmethod - -@defmethod EventCreator create_event_down intended_target -@end defmethod - -@defmethod EventCreator create_event_move pos_in [round=1] [wide_element=false] -@end defmethod - -@defmethod EventCreator create_event_finisher callback -@end defmethod - -@end deftp - -@defun place_in_edit_mode event -@end defun - -@c window.onload is here in source file - -@defun get_property event field default_value -Returns the @emph{value} slot of given field in @var{event}, creating it if needed. - -@itemize -@item -@var{el}: the event to work on - -@item -@var{field}: name of the field - -@item -@var{default_value}: default value when creating - -@item -@var{bind_to_ical} should this property be added to the icalendar subtree? -@end itemize -@end defun - -@defun bind_properties el [wide_event=false] - Properties are icalendar properties. - - p['name'] to get and set value (also updates any connected slots) - - p['_value_name'] for raw value - p['_slot_name'] for connected slots, Vector of pairs, where the - car should be a reference to the slot, and the - cdr a procedure which takes a slot and a value - and binds the value to the slot. -@end defun - -@node server_connect -@section server_connect.js - -@node types -@section types.js - -Collection of type information for calendar data. - -@defvar all_types -Name of all valid icalendar types. - - text, uri, binary, float, integer, date-time, date, duration, - period, utc-offset, cal-address, recur, boolean, -@end defvar - -@defvar property_names -All known names properties (top level keys) can have. -Such as ``calscale'', ``dtstart'', ... -@end defvar - -@defvar valid_fields -Which property fields each component can hold. - -@verbatim -{ 'VCALENDAR': ['PRODID', 'VERSION', 'CALSCALE', 'METHOD'], - ... -} -@end verbatim -@end defvar - -@defvar valid_input_types -Which types are valid to store under each property. -If multiple values are an option for that property, then -the list of possibilities will contain a sub-list (see example). - -@verbatim -{ 'DTSTART': ['date', 'date-time'], - 'CATEGORIES': [['text']], - ... -} -@end verbatim -@end defvar +@include javascript/arbitary_kv.texi +@include javascript/binders.texi +@include javascript/clock.texi +@include javascript/date_time.texi +@include javascript/draggable.texi +@include javascript/input_list.texi +@include javascript/jcal.texi +@include javascript/lib.texi +@include javascript/popup.texi +@include javascript/rrule.texi +@include javascript/script.texi +@include javascript/server_connect.texi +@include javascript/types.texi diff --git a/doc/ref/javascript/arbitary_kv.texi b/doc/ref/javascript/arbitary_kv.texi new file mode 100644 index 00000000..76e7230b --- /dev/null +++ b/doc/ref/javascript/arbitary_kv.texi @@ -0,0 +1,3 @@ +@node arbitary_kv +@section arbitary_kv.js + diff --git a/doc/ref/javascript/binders.texi b/doc/ref/javascript/binders.texi new file mode 100644 index 00000000..4e6da267 --- /dev/null +++ b/doc/ref/javascript/binders.texi @@ -0,0 +1,4 @@ + +@node binders +@section binders.js + diff --git a/doc/ref/javascript/clock.texi b/doc/ref/javascript/clock.texi new file mode 100644 index 00000000..1602e687 --- /dev/null +++ b/doc/ref/javascript/clock.texi @@ -0,0 +1,4 @@ + +@node clock +@section clock.js + diff --git a/doc/ref/javascript/date_time.texi b/doc/ref/javascript/date_time.texi new file mode 100644 index 00000000..7bc47625 --- /dev/null +++ b/doc/ref/javascript/date_time.texi @@ -0,0 +1,4 @@ + +@node date_time +@section date_time.js + diff --git a/doc/ref/javascript/draggable.texi b/doc/ref/javascript/draggable.texi new file mode 100644 index 00000000..e91d12f7 --- /dev/null +++ b/doc/ref/javascript/draggable.texi @@ -0,0 +1,4 @@ + +@node dragable +@section dragable.js + diff --git a/doc/ref/javascript/input_list.texi b/doc/ref/javascript/input_list.texi new file mode 100644 index 00000000..bda2de83 --- /dev/null +++ b/doc/ref/javascript/input_list.texi @@ -0,0 +1,4 @@ + +@node input_list +@section input_list.js + diff --git a/doc/ref/javascript/jcal.texi b/doc/ref/javascript/jcal.texi new file mode 100644 index 00000000..1352815d --- /dev/null +++ b/doc/ref/javascript/jcal.texi @@ -0,0 +1,4 @@ + +@node jcal +@section jcal.js + diff --git a/doc/ref/javascript/lib.texi b/doc/ref/javascript/lib.texi new file mode 100644 index 00000000..eda72ccf --- /dev/null +++ b/doc/ref/javascript/lib.texi @@ -0,0 +1,147 @@ + +@node lib +@section lib.js + +General procedures which in theory could be used anywhere. + +@defvar xcal +The xml namespace name for xcalendar, which is +``urn:ietf:params:xml:ns:icalendar-2.0''. +@end defvar + + +@node Default prototype extensions +@subsection Default prototype extensions + +HTMLElement extensions + +@defmethod HTMLElement addEventListener name proc +Replace the default @code{addEventListener} with a version that stores +all listeners in the dictionary @var{listeners}. +@end defmethod + +@defivar HTMLElement listeners +Dictionary of all registered listeners to this element. +Keys are taken from @code{addEventListener}. +@end defivar + +@defmethod DOMTokenList find regexp +Finds the first element of the DOMTokenList whichs value matches +the supplied regexp. Returns a pair of the index and the value. +@end defmethod + +@defmethod Object format args ... +Returns a string representation of the given object. +Allows extending for custom types, +@ref{date-format} +@end defmethod + +@node General +@subsection General + +@defun zip args ... +Takes a list of lists, and returns a single list of tuples. +@example +» zip([1,2,3,4,5], "Hello") +← [[1,'H'],[2,'e'],[3,'l'],[4,'l'],[5,'o']] +@end example +@end defun + +@defun makeElement name [attr=@{@}] +Creates a new DOM element of type @var{name}, with all keys in +@var{attr} transfered to it. For example, the equivalent of +@example + +@end example +would be +@verbatim +values.push(makeElement('input', { + type: 'number', +})); +@end verbatim +. +@end defun + +@defun round_time time fraction +TODO +@end defun + +@defun date_to_percent date +Retuns how far along the date specified by @var{date} is, between 0 +and 100, where 00:00 maps to 0, and 23:59 to ~100. +@end defun + +@defun gensym [pxrefix='gensym'] +Generates a new string which is (hopefully) globally unique. +Compare with @code{gensym} from Lisp. +@end defun + +@defun setVar str val +Set the CSS var @var{str} to @var{val} on the root element. +@end defun + +@defun asList thing +Ensures that @var{thing} is a list. Returning it outright if it +already is one, otherwise wrapping it in a list. +@end defun + +@node Date +@subsection Date + +Some extensions to the builtin class ``Date'' is made. + +@defivar Date utc +Boolean indicating if the given timestamp is in UTC or local time. +true means UTC. +@end defivar + +@defivar Date dateonly +Boolean indicating if the time component of the Date object should be disregarded. +@end defivar + +@defun parseDate str +Takes a string @var{str}, which should be in ISO-8601 date-format, and +returns a javascript Date object. +@end defun + +@defun copyDate date +Creates a new instance of the given Date @var{date}, also transfers my +custom fields. +@end defun + +@defun to_local date +@anchor{to_local} +Returns a Date object (which may be new) which is guaranteed in local +time. +This means that the @var{utc} field is @code{false}, and that +@code{to_local(current_time())} should show what your wall-clock shows. +@end defun + +@defmethod Date format str args ... +@anchor{date-format} +Formats a Date object according to the format specification @var{str}. +Keeping with Guile each format specifier starts with a ~. + +@c table formatting borrowed from Gulie Reference (SRFI-19 Date to string) +@multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{~~} @tab literal ~ +@c Almost all fields are left padded. How do I signify this +@c with a single footnote? +@item @nicode{~Y} @tab year, left-padding with zeroes. +@item @nicode{~m} @tab month number, left padded with zeroes. +@item @nicode{~d} @tab day of month. +@item @nicode{~H} @tab hour +@item @nicode{~M} @tab minute +@item @nicode{~S} @tab second +@item @nicode{~Z} @tab 'Z' if Date is UTC, otherwise nothing + +@item @nicode{~L} @tab Converts the date to local time +(@pxref{to_local}) (doesn't modify source object). Outputs nothing +@end multitable +@end defmethod + +@defun format_date date str +Equivalent to @code{(@var{date}).format(@var{str})}. +@c TODO link +@end defun + diff --git a/doc/ref/javascript/popup.texi b/doc/ref/javascript/popup.texi new file mode 100644 index 00000000..46ec476a --- /dev/null +++ b/doc/ref/javascript/popup.texi @@ -0,0 +1,5 @@ + + +@node popup +@section popup.js + diff --git a/doc/ref/javascript/rrule.texi b/doc/ref/javascript/rrule.texi new file mode 100644 index 00000000..61fa0eac --- /dev/null +++ b/doc/ref/javascript/rrule.texi @@ -0,0 +1,4 @@ + +@node rrule +@section rrule.js + diff --git a/doc/ref/javascript/script.texi b/doc/ref/javascript/script.texi new file mode 100644 index 00000000..ea3e93ce --- /dev/null +++ b/doc/ref/javascript/script.texi @@ -0,0 +1,58 @@ + +@node script +@section script.js + +@dfn{Main} for my javascript, and also currently dumping ground for stuff. + +@deftp {class} EventCreator + +@defmethod EventCreator create_empty_event +@end defmethod + +@defmethod EventCreator create_event_down intended_target +@end defmethod + +@defmethod EventCreator create_event_move pos_in [round=1] [wide_element=false] +@end defmethod + +@defmethod EventCreator create_event_finisher callback +@end defmethod + +@end deftp + +@defun place_in_edit_mode event +@end defun + +@c window.onload is here in source file + +@defun get_property event field default_value +Returns the @emph{value} slot of given field in @var{event}, creating it if needed. + +@itemize +@item +@var{el}: the event to work on + +@item +@var{field}: name of the field + +@item +@var{default_value}: default value when creating + +@item +@var{bind_to_ical} should this property be added to the icalendar subtree? +@end itemize +@end defun + +@defun bind_properties el [wide_event=false] + Properties are icalendar properties. + + p['name'] to get and set value (also updates any connected slots) + + p['_value_name'] for raw value + p['_slot_name'] for connected slots, Vector of pairs, where the + car should be a reference to the slot, and the + cdr a procedure which takes a slot and a value + and binds the value to the slot. +@end defun + + diff --git a/doc/ref/javascript/server_connect.texi b/doc/ref/javascript/server_connect.texi new file mode 100644 index 00000000..64afd776 --- /dev/null +++ b/doc/ref/javascript/server_connect.texi @@ -0,0 +1,2 @@ +@node server_connect +@section server_connect.js diff --git a/doc/ref/javascript/types.texi b/doc/ref/javascript/types.texi new file mode 100644 index 00000000..e57af4a2 --- /dev/null +++ b/doc/ref/javascript/types.texi @@ -0,0 +1,39 @@ +@node types +@section types.js + +Collection of type information for calendar data. + +@defvar all_types +Name of all valid icalendar types. + + text, uri, binary, float, integer, date-time, date, duration, + period, utc-offset, cal-address, recur, boolean, +@end defvar + +@defvar property_names +All known names properties (top level keys) can have. +Such as ``calscale'', ``dtstart'', ... +@end defvar + +@defvar valid_fields +Which property fields each component can hold. + +@verbatim +{ 'VCALENDAR': ['PRODID', 'VERSION', 'CALSCALE', 'METHOD'], + ... +} +@end verbatim +@end defvar + +@defvar valid_input_types +Which types are valid to store under each property. +If multiple values are an option for that property, then +the list of possibilities will contain a sub-list (see example). + +@verbatim +{ 'DTSTART': ['date', 'date-time'], + 'CATEGORIES': [['text']], + ... +} +@end verbatim +@end defvar -- cgit v1.2.3 From 341e5a65a7b36e1f70ed9e6c2ae4f5b18c083b5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Wed, 13 Jan 2021 22:47:46 +0100 Subject: Doc work. --- doc/frontend.org | 24 ----------- doc/ref/Makefile | 2 +- doc/ref/calp.texi | 21 ++++++++++ doc/ref/javascript/clock.texi | 82 +++++++++++++++++++++++++++++++++++++- doc/ref/javascript/date_time.texi | 37 ++++++++++++++++- doc/ref/javascript/draggable.texi | 22 +++++++++- doc/ref/javascript/input_list.texi | 49 ++++++++++++++++++++++- 7 files changed, 208 insertions(+), 29 deletions(-) (limited to 'doc') diff --git a/doc/frontend.org b/doc/frontend.org index 0b5725aa..63d6fe1f 100644 --- a/doc/frontend.org +++ b/doc/frontend.org @@ -1,29 +1,5 @@ ** Javascript "components" -*** input-list -file:../static/input_list.js - -All elements having 'input-list' ∈ =class= - -Direct children must all have 'unit' ∈ =class= -One direct child must have 'final' ∈ =class= - -binds =get_value= on instances, by default returning the value -of all == tags joined by =,=. This can be overwritten with -- =data-joinby= :: Alternative character to join by -- =data-bindby= :: replacement for get_value - -TODO: instead, override value? - -=addEventList('input',= is overwritten, registering the listener for all input -elements. - *** Popup Handles popup. Currently rather specific -*** Dragable -file:../static/dragable.js - -Manually apply =bind_popup_control= to the statusbar of a floating "window". -Nothing is required from the component, but the "window" must have -'popup-container' ∈ =class= diff --git a/doc/ref/Makefile b/doc/ref/Makefile index 35dd6604..2232a70e 100644 --- a/doc/ref/Makefile +++ b/doc/ref/Makefile @@ -1,4 +1,4 @@ -TEXI_FILES := $(wildcard *.texi) +TEXI_FILES := $(shell find . -type f -name \*.texi) INFOFLAGS := all: calp.info diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index a2408f89..e280a455 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -17,6 +17,27 @@ Copyright @copyright{} 2020 Hugo Hörnquist @alias nicode=code @end ifnotinfo +@c @ifinfo +@c @macro i{text} +@c \text\ +@c @end macro +@c @end ifinfo + +@c for use with deftp for extended classes +@macro extends{class} +@w{@i{extends} \class\} +@end macro + +@c For things that should be fixed in the (actual) code. +@c An ``invitation'' to the reader +@macro TODO{text} +text @footnote{Improvements welcome} +@end macro + +@macro githash{hash,path,line} +@url{https://git.hornquist.se/calp/tree/\path\?id=\hash\#n\line\,\hash\} +@end macro + @titlepage @title Calp @author Hugo Hörnquist diff --git a/doc/ref/javascript/clock.texi b/doc/ref/javascript/clock.texi index 1602e687..5f599c9b 100644 --- a/doc/ref/javascript/clock.texi +++ b/doc/ref/javascript/clock.texi @@ -1,4 +1,84 @@ - @node clock @section clock.js +@deftp {(abstract) class} Clock +Interface for ``things'' which wants to get updated on a human timescale. + +@defmethod Clock update now +Called every now and then, with @var{now} being the current time. +@end defmethod + +All instances are expected to implement @code{update}, but are free to +implement any other methods they see fit. +@end deftp + +Below, only the methods (including @code{constructor} and +@code{update} which do something of note (excluding the expected)) +are noted. + +@deftp {class} Timebar @extends{Clock} +The (blue) vertical line which show the current time in the current day. + +@c @defmethod Timebar constructor ∅ +@c @end defmethod +@c +@c @defmethod Timebar update now +@c @end defmethod +@end deftp + +@deftp {class} SmallcalCellHighlight @extends{Clock} +Highlights the current date in the small calendar to the side. +Currently directly sets a border +@TODO{but should preferably set a class instead}. + +@defmethod SmallcalCellHighlight constructor small_cal +@var{small_cal} is the DOM-node of the calendar. +(it should support querySelector). +@end defmethod + +@c @defmethod SmallcalCellHighlight update now +@c @end defmethod +@end deftp + +@deftp {class} ButtonUpdater @extends{Clock} +Updates the ``Today'' link in the side panel to point directly to the +correct web-address. The link works without JavaScript, but then +requires a redirect from the server. + +All actual updating logic is already abstracted away. It would be +desirable if something more was done with this. + +@defmethod ButtonUpdater el proc +Takes the element @var{el} to be updated, and the procedure @var{proc} +which will be called with the element, and the current time. +@end defmethod +@end deftp + + +As of commit +@githash{c9719ce7937f0f0f2aa371ced1d585f67af22457,static/script.js,231} +all objects required manual setup. See static/script.js: + +@verbatim + 231 let start_time = document.querySelector("meta[name='start-time']").content; + 232 let end_time = document.querySelector("meta[name='end-time']").content; + 233 + 234 const button_updater = new ButtonUpdater( + 235 document.getElementById("today-button"), + 236 (e, d) => e.href = d.format('~Y-~m-~d') + ".html" + 237 ); + 238 + 239 const sch = new SmallcalCellHighlight( + 240 document.querySelector('.small-calendar')) + 241 + 242 const timebar = new Timebar(start_time, end_time); + 243 + 244 timebar.update(new Date); + 245 window.setInterval(() => { + 246 let d = new Date; + 247 timebar.update(d); + 248 button_updater.update(d); + 249 sch.update(d); + 250 }, 1000 * 60); + 251 +@end verbatim diff --git a/doc/ref/javascript/date_time.texi b/doc/ref/javascript/date_time.texi index 7bc47625..1f62c72e 100644 --- a/doc/ref/javascript/date_time.texi +++ b/doc/ref/javascript/date_time.texi @@ -1,4 +1,39 @@ - @node date_time @section date_time.js +@defun init_date_time +@c possibly have special index for these +@cindex dummy component +Procedure which initializes the dummy component for date-time input. +When called, finds all elements with class ``date-time'', and makes +them date-time inputs. + +@c + +The expected HTML form is +@example +
+ + +
+@end example + +Each date-time gets the following fields: + +@defivar date_time value +The current date-time value as a string, +on the form @code{YYYY-mm-ddTHH:MM[:SS]} +(@code{SS} if the underlying time input has it). + +A new date-time can also be set to the field, the same format as above +is expected. +@end defivar + +@defivar date_time name +The ``name'' field of the date-time input. Since @code{name} note that +this is an addition, since name is actually invalid on non-input +components. We nevertheless use it here since we are emulating an +input element. +@end defivar + +@end defun diff --git a/doc/ref/javascript/draggable.texi b/doc/ref/javascript/draggable.texi index e91d12f7..689dd005 100644 --- a/doc/ref/javascript/draggable.texi +++ b/doc/ref/javascript/draggable.texi @@ -1,4 +1,24 @@ - @node dragable @section dragable.js +@c TODO This text is just yanked from the old org file, along with the +@c source codes header. It should probably be rewritten. + +Manually apply =bind_popup_control= to the statusbar of a floating +"window". Nothing is required from the component, but the "window" +must have 'popup-container' ∈ =class= + +@defun bind_popup_control nav +Apply to a given component to make it draggable. +Drag area (usually a title bar) should be be the only argument. +It is REQUIRED that the object which should be moved have the class +@code{popup-container}. + +@example +
+ ... +
+@end example +@end defun diff --git a/doc/ref/javascript/input_list.texi b/doc/ref/javascript/input_list.texi index bda2de83..e22d4c2b 100644 --- a/doc/ref/javascript/input_list.texi +++ b/doc/ref/javascript/input_list.texi @@ -1,4 +1,51 @@ - @node input_list @section input_list.js +@cindex dummy component + +All elements with the class @code{input-list} are treated as a +collection of input fields. Uses including setting tags on calendar +entries. + +All direct children of the ``input-list'' @emph{must} have the class +@code{unit}, and one direct child @code{unit} have the class @code{final}. + +@c All elements having 'input-list' ∈ =class= + +@c Direct children must all have 'unit' ∈ =class= +@c One direct child must have 'final' ∈ =class= + +@defmethod input_list get_value + +@example +querySelectorAll('input') + .map(x => x.value) + .join(@var{joinby}) +@end example +@end defmethod + +@defivar input_list [data-]joinby + Alternative character to join by +@end defivar + +@defivar input_list [data-]bindby + replacement for get_value +@end defivar + +binds =get_value= on instances, by default returning the value +of all == tags joined by =,=. This can be overwritten with + +TODO: instead, override value? + +=addEventList('input',= is overwritten, registering the listener for all input +elements. + + + ∀ children('.input-list') => 'unit' ∈ classList(child) + +
+
+
+
+@defun init_input_list +@end defun -- cgit v1.2.3 From 3683d80b25bcecb9fe72ba336fda5d3e98459993 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Sat, 9 Jan 2021 05:55:48 +0100 Subject: Move javascript doc down one level. --- doc/ref/javascript.texi | 5 +++++ doc/ref/javascript/arbitary_kv.texi | 2 +- doc/ref/javascript/binders.texi | 2 +- doc/ref/javascript/clock.texi | 2 +- doc/ref/javascript/date_time.texi | 2 +- doc/ref/javascript/draggable.texi | 2 +- doc/ref/javascript/input_list.texi | 2 +- doc/ref/javascript/jcal.texi | 2 +- doc/ref/javascript/lib.texi | 8 ++++---- doc/ref/javascript/popup.texi | 2 +- doc/ref/javascript/rrule.texi | 2 +- doc/ref/javascript/script.texi | 2 +- doc/ref/javascript/server_connect.texi | 2 +- doc/ref/javascript/types.texi | 2 +- 14 files changed, 21 insertions(+), 16 deletions(-) (limited to 'doc') diff --git a/doc/ref/javascript.texi b/doc/ref/javascript.texi index d53ce2d0..d6323b1d 100644 --- a/doc/ref/javascript.texi +++ b/doc/ref/javascript.texi @@ -1,6 +1,11 @@ @node Javascript @chapter Javascript +@node Concepts +@section Concepts + +@node Reference +@section Reference @include javascript/arbitary_kv.texi @include javascript/binders.texi @include javascript/clock.texi diff --git a/doc/ref/javascript/arbitary_kv.texi b/doc/ref/javascript/arbitary_kv.texi index 76e7230b..b28c8b92 100644 --- a/doc/ref/javascript/arbitary_kv.texi +++ b/doc/ref/javascript/arbitary_kv.texi @@ -1,3 +1,3 @@ @node arbitary_kv -@section arbitary_kv.js +@subsection arbitary_kv.js diff --git a/doc/ref/javascript/binders.texi b/doc/ref/javascript/binders.texi index 4e6da267..d3cd8802 100644 --- a/doc/ref/javascript/binders.texi +++ b/doc/ref/javascript/binders.texi @@ -1,4 +1,4 @@ @node binders -@section binders.js +@subsection binders.js diff --git a/doc/ref/javascript/clock.texi b/doc/ref/javascript/clock.texi index 5f599c9b..5c2bd954 100644 --- a/doc/ref/javascript/clock.texi +++ b/doc/ref/javascript/clock.texi @@ -1,5 +1,5 @@ @node clock -@section clock.js +@subsection clock.js @deftp {(abstract) class} Clock Interface for ``things'' which wants to get updated on a human timescale. diff --git a/doc/ref/javascript/date_time.texi b/doc/ref/javascript/date_time.texi index 1f62c72e..fb2563f1 100644 --- a/doc/ref/javascript/date_time.texi +++ b/doc/ref/javascript/date_time.texi @@ -1,5 +1,5 @@ @node date_time -@section date_time.js +@subsection date_time.js @defun init_date_time @c possibly have special index for these diff --git a/doc/ref/javascript/draggable.texi b/doc/ref/javascript/draggable.texi index 689dd005..d1851ec4 100644 --- a/doc/ref/javascript/draggable.texi +++ b/doc/ref/javascript/draggable.texi @@ -1,5 +1,5 @@ @node dragable -@section dragable.js +@subsection dragable.js @c TODO This text is just yanked from the old org file, along with the @c source codes header. It should probably be rewritten. diff --git a/doc/ref/javascript/input_list.texi b/doc/ref/javascript/input_list.texi index e22d4c2b..65db81a4 100644 --- a/doc/ref/javascript/input_list.texi +++ b/doc/ref/javascript/input_list.texi @@ -1,5 +1,5 @@ @node input_list -@section input_list.js +@subsection input_list.js @cindex dummy component All elements with the class @code{input-list} are treated as a diff --git a/doc/ref/javascript/jcal.texi b/doc/ref/javascript/jcal.texi index 1352815d..4be8d33b 100644 --- a/doc/ref/javascript/jcal.texi +++ b/doc/ref/javascript/jcal.texi @@ -1,4 +1,4 @@ @node jcal -@section jcal.js +@subsection jcal.js diff --git a/doc/ref/javascript/lib.texi b/doc/ref/javascript/lib.texi index eda72ccf..ec5d4450 100644 --- a/doc/ref/javascript/lib.texi +++ b/doc/ref/javascript/lib.texi @@ -1,6 +1,6 @@ @node lib -@section lib.js +@subsection lib.js General procedures which in theory could be used anywhere. @@ -11,7 +11,7 @@ The xml namespace name for xcalendar, which is @node Default prototype extensions -@subsection Default prototype extensions +@subsubsection Default prototype extensions HTMLElement extensions @@ -37,7 +37,7 @@ Allows extending for custom types, @end defmethod @node General -@subsection General +@subsubsection General @defun zip args ... Takes a list of lists, and returns a single list of tuples. @@ -86,7 +86,7 @@ already is one, otherwise wrapping it in a list. @end defun @node Date -@subsection Date +@subsubsection Date Some extensions to the builtin class ``Date'' is made. diff --git a/doc/ref/javascript/popup.texi b/doc/ref/javascript/popup.texi index 46ec476a..2dd8f48f 100644 --- a/doc/ref/javascript/popup.texi +++ b/doc/ref/javascript/popup.texi @@ -1,5 +1,5 @@ @node popup -@section popup.js +@subsection popup.js diff --git a/doc/ref/javascript/rrule.texi b/doc/ref/javascript/rrule.texi index 61fa0eac..5d7a7576 100644 --- a/doc/ref/javascript/rrule.texi +++ b/doc/ref/javascript/rrule.texi @@ -1,4 +1,4 @@ @node rrule -@section rrule.js +@subsection rrule.js diff --git a/doc/ref/javascript/script.texi b/doc/ref/javascript/script.texi index ea3e93ce..fbb8baa4 100644 --- a/doc/ref/javascript/script.texi +++ b/doc/ref/javascript/script.texi @@ -1,6 +1,6 @@ @node script -@section script.js +@subsection script.js @dfn{Main} for my javascript, and also currently dumping ground for stuff. diff --git a/doc/ref/javascript/server_connect.texi b/doc/ref/javascript/server_connect.texi index 64afd776..2f50f02d 100644 --- a/doc/ref/javascript/server_connect.texi +++ b/doc/ref/javascript/server_connect.texi @@ -1,2 +1,2 @@ @node server_connect -@section server_connect.js +@subsection server_connect.js diff --git a/doc/ref/javascript/types.texi b/doc/ref/javascript/types.texi index e57af4a2..73a58550 100644 --- a/doc/ref/javascript/types.texi +++ b/doc/ref/javascript/types.texi @@ -1,5 +1,5 @@ @node types -@section types.js +@subsection types.js Collection of type information for calendar data. -- cgit v1.2.3 From b3a44127f227d3b045fbeae7c571111be49b11c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 12 Jan 2021 01:14:44 +0100 Subject: Add subsection "Components". --- doc/ref/javascript.texi | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc') diff --git a/doc/ref/javascript.texi b/doc/ref/javascript.texi index d6323b1d..6fbd7cdc 100644 --- a/doc/ref/javascript.texi +++ b/doc/ref/javascript.texi @@ -4,6 +4,20 @@ @node Concepts @section Concepts +@subsection ``Componenents'' + +@deftp {} date_time +@cindex date-time + +@ref{date_time} +@end deftp + +@deftp {} draggable +@end deftp + +@deftp {} input_list +@end deftp + @node Reference @section Reference @include javascript/arbitary_kv.texi -- cgit v1.2.3 From e968ccd55b59a36d6f29eaa2beeee9ec8e3fdb7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Wed, 13 Jan 2021 01:26:06 +0100 Subject: Wrote binders.texi. --- doc/ref/javascript/binders.texi | 43 +++++++++++++++++++++++++++++++++++++++++ doc/ref/javascript/script.texi | 2 ++ 2 files changed, 45 insertions(+) (limited to 'doc') diff --git a/doc/ref/javascript/binders.texi b/doc/ref/javascript/binders.texi index d3cd8802..2b64b230 100644 --- a/doc/ref/javascript/binders.texi +++ b/doc/ref/javascript/binders.texi @@ -2,3 +2,46 @@ @node binders @subsection binders.js +The bind system allows HTML-elements to specify that they want to be +updated whenever its corresponding (vcalendar) object changes. +The bind system is currently set up in +@code{bind_properties} (@pxref{bind_properties}) +(which at the time of writing is (badly) located in @ref{script}). + +All (HTML) components with the class @code{bind} are bound. By default +the (HTML) attribute @code{data-property} is checked for a property +name, and @code{object.innerHTML} is set whenever that property field +changes. +Alternatively an (HTML) component may specify a specific binder +through the HTML attribute @code{data-bindby}, which should be the +name of a JavaScript function taking two arguments, an @TODO{event +component} +@footnote{Root ``root'' HTML component of a given calendar event +(something which @code{get_property} can be called on}, +and the component in question. + +@c Also sets up event listeners, which most doesn't do. + +Binder functions are generally placed in @file{binders.js}, and +shouldn't be called manually. + +@defun bind_recur el e +Handles recurrence rules. +Uses a sub-binder system on components with class containing +``bind-rr''. +@end defun + +@defun bind_edit el e +Cases for @code{input} and @code{textarea} elements @TODO{(should also +handle @code{select}s?)} +@end defun + +@defun bind_view el e +The same as the default binder???? +@end defun + +@defun bind_wholeday el e +Binder for the wholeday toggle button. +While CSS would suffice, this sets the disabled flags on the time +inputs, giving a better user experience. +@end defun diff --git a/doc/ref/javascript/script.texi b/doc/ref/javascript/script.texi index fbb8baa4..a60343e4 100644 --- a/doc/ref/javascript/script.texi +++ b/doc/ref/javascript/script.texi @@ -44,6 +44,8 @@ Returns the @emph{value} slot of given field in @var{event}, creating it if need @end defun @defun bind_properties el [wide_event=false] +@anchor{bind_properties} +@ref{binders} Properties are icalendar properties. p['name'] to get and set value (also updates any connected slots) -- cgit v1.2.3 From 719df1b4e8b0ad90159caeec6948402598076d88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Wed, 13 Jan 2021 22:45:11 +0100 Subject: Document (vcompenent control). --- doc/ref/calp.texi | 1 + doc/ref/guile.texi | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 doc/ref/guile.texi (limited to 'doc') diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index e280a455..e5c4baab 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -58,6 +58,7 @@ text @footnote{Improvements welcome} @c * Index:: @c @end menu +@include guile.texi @include javascript.texi @node Index diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi new file mode 100644 index 00000000..8468021e --- /dev/null +++ b/doc/ref/guile.texi @@ -0,0 +1,17 @@ +@node Guile +@chapter Guile + +@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