#
# $RCSfile: todo.txt,v $
#
# This file lists so-called "TODO" items, in other words open tasks
# to be worked on in the future.
#
# http://www.cybop.net
# - Cybernetics Oriented Programming -
#
# @version $Revision: 1.118 $ $Date: 2009-10-06 21:25:26 $ $Author: christian $
# @author Christian Heller <christian.heller@tuxtax.de>
#

        * Implement in this order: comparator, finder, retriever (getter), replacer, appender
        * Continue then with "part_replacer.c"
        * Provide modifier functions for "part" that expect just one pointer with count and size
            and not as many parameters as was the case up to now
        * Replace old functions named "append_part..." with new "append" or "replace"
        * Provide modifier functions for "compound"
        * Replace old functions named "append_compound..." with new "append" or "replace"
        * Rename "model" (containing count and size) to "attribute"

        * CONTINUE WITH: container functions as described in file "todo_cyboi_java_comparison.txt"
        * Adjust destination's count and size automatically, like a "wrapper" function;
            examples: "wide_character_vector_accessor.c", "executor/accessor/setter.c", "set_compound_element_by_name"
        * Possible Bug? in function "set_compound_element_by_index":
            set_array_elements(*n, p3, (void*) &p4, (void*) NUMBER_1_INTEGER_MEMORY_MODEL, (void*) POINTER_ARRAY_MEMORY_ABSTRACTION);
            --> the "(void*) &p4" does possibly lead to errors, since a reference to the
                local variable p4 is stored, which gets destroyed as soon as the function is left
        * Remove model and details content of receiving compound for each new http request;
            otherwise, new commands are just added to the "action" part entry in "receive_socket.c";
            this fixes the errors caused by using "append" instead the "replace" function
            (e.g. html file http response was generated twice as long as wanted;
            only first action was received and added properly to uri internal model,
            all following actions were appended but only the first is considered)

        * Continue with example application "presence"

        * Replace temporary workaround in file "percent_encoding_decoder.c" with proper decoder file
        * Figure out necessary LIMITATION of the socket receive buffer in function "communicate_receiving_socket" to 1024!
        * See: http://www.w3.org/TR/html5/urls.html#urls
        * See also file "resmedicinae/apps/residenz/logic/handler/handle_www_service.cybol"

        * Create three different sockets (local, inet, inet6)? distinguish at socket startup?
            and store as different entries in internal memory?
        * move and rename "set_new_signal_identification" to e.g. /globals/references/integer_references.c
            and name function e.g. "get_integer_reference"
        * Implement session on application level (Res Medicinae)

        * It was decided that "send" operations do NOT run in an own thread (for now and the near future, at least),
            also if querying a server via http, since this would mix up the signal handling mechanism

        * Add new cybol function "convert" or "translate"
        * Simplify send/receive functions by factoring out translation to steps before
        * Hand over already translated message to send/receive
        * Enable multiple abstractions like "character|UTF-32|gzip", separated by
            a "pipe" character and processed one-by-one, in the given order?
            --> not necessary, if all translation is done transparently in cybol models

        * Add one file with prefix "cyboi_" in parallel to each file containing
            standard xDT constants in directory "constant/name/xdt/" and below;
            e.g. a file "cyboi_field_xdt_name.c" with constants a la "CYBOI_KBV_TEST_NUMBER_FIELD_XDT_NAME"
            in addition to the file "field_xdt_name.c" with standard format constants a la "KBV_TEST_NUMBER_FIELD_XDT_NAME";
        * Merge all files using old naming schemes like "memory", "model", "compound" into new format
        * Rename old files "field_xdt_model_name.c" etc. to "cyboi_*"

        * Adapt "*_assigner.c" modules to new primitive types/ type sizes
        * Leave abstractions to only provide basic types like: character, integral, real, pointer
            and map these to the corresponding basic standard type, i.e.: wchar_t, signed int, double, void*
            (so that special types like "unsigned short int" are only used cyboi-internally, but not in cybol)
        * Adapt file "primitive_memory_abstraction.c" to actually necessary types
        * Adapt source code by using memory-efficient types wherever possible,
            e.g. "signed short int" instead of just "int" (as done up to now)
            or "signed char" for simple flags used for just two values

        * Adapt all places in source code where reallocation is used to new
            reallocation factor handling and also shrink memory structures appropriately

        * Rename several things in CYBOL files and CYBOI:
            --> rename "abstraction" attribute to "language" for all CYBOL tags?!
            --> rename "model" attribute to "message" for all CYBOL tags?!

        * TUI: Check why the escape code sequence (e.g. ESC[B for arrow left) is added to the
            knowledge tree TEST_SHUTDOWN, instead of the decoded string "arrow_left"
        * stop thread if irq has already been set to 1; only continue sensing if irq is 0,
            e.g. in function "sense_gnu_linux_console"
        * possibly also wait some time while irq is 0, not only while irq is 1

        * Set "receive" model in internal memory to NULL in "interrupt" (stop sensing) function,
            but do NOT destroy, since it belongs to the knowledge model tree

        * Does the logger need an own mutex? ... because it is accessed by all threads!
            Alternative: Do NOT use the logger in sensing threads at all

        * Include the sources of all documents into the distributable tarball cybop-0.12.0/
            --> really? This will grow it up to 500 MB in size due to the images
        * Write an actual manual that is updated as necessary to reflect the current
            state of cybop; brief overview which ones should be read first
            if someone was trying to use the system

        * Search for "??" (places that are left TODO) and clean up source code

        * Check out handling of "super" property. Is it necessary at all?
            ==> use "prototype programming" paradigm-like behaviour, i.e.:
                templates are just templates for initial creation of a model at runtime;
                later on, each model has to keep ALL its parts with properties itself/ alone
            ==> therefore, multiple template inheritance should be possible, too
                (which would enable splitting of aspects like logging etc.)
                because runtime models do NOT reference their original template anymore,
                so that conflicts due to inter-dependencies as in OOP may not occur
            --> if parts exist, then a new part with the same name (stemming from the same
                model or its super category) must NOT be created!
            --> prevent this in CYBOI, using conditions
            --> only one (super) category makes sense, because templates/ models
                belong to a certain dimension like: TUI, GUI, WUI, domain model;
                so the upper-most category for a tui model may be one that
                provides ALL essential properties like "shape", "border", "background" etc.

        Q: Why should a tui knowledge template NOT be implemented with properties of abstraction "knowledge" or "encapsulated", as follows:

            <part name="apw_entry" channel="inline" abstraction="character" model="a - Starte Arztpraxis Wiegand (APW) im DOS Emulator (DOSemu)">
                <property name="position" channel="inline" abstraction="integer" model="1,3,0"/>
                <property name="size" channel="inline" abstraction="integer" model="68,1,1"/>
                <property name="shape" channel="inline" abstraction="knowledge" model=".revue.settings.tui.shape"/>
                <property name="layout" channel="inline" abstraction="knowledge" model=".revue.settings.tui.layout"/>
                <property name="background" channel="inline" abstraction="knowledge" model=".revue.settings.tui.menu_item_background"/>
                <property name="foreground" channel="inline" abstraction="knowledge" model=".revue.settings.tui.menu_item_foreground"/>
                <property name="bold" channel="inline" abstraction="knowledge" model=".revue.settings.tui.bold"/>
                <property name="previous" channel="inline" abstraction="character" model=".revue.tui.main_window.menu.exit_entry"/>
                <property name="next" channel="inline" abstraction="character" model=".revue.tui.main_window.menu.backup_entry"/>
                <property name="button_press_action" channel="inline" abstraction="character" model=".revue.logic.functionality.start_apw"/>
            </part>

        A1: Because the user interface logic "select_next_part.cybol" and "select_previous_part.cybol",
            and potentially other logic templates do access the properties, in order to set their value, for example:

            <part name="assemble_current_element_background" channel="inline" abstraction="operation" model="add">
                <property name="summand_1" channel="inline" abstraction="knowledge" model=".revue.tui.main_window.menu#focus"/>
                <property name="summand_2" channel="inline" abstraction="character" model="#background"/>
                <property name="sum" channel="inline" abstraction="knowledge" model=".revue.temporary.character"/>
                <property name="abstraction" channel="inline" abstraction="character" model="character"/>
            </part>
            <part name="unfocus_background" channel="inline" abstraction="operation" model="copy">
                <property name="source" channel="inline" abstraction="knowledge" model=".revue.settings.tui.menu_item_background"/>
                <property name="destination" channel="inline" abstraction="encapsulated" model=".revue.temporary.character"/>
                <property name="abstraction" channel="inline" abstraction="character" model="character"/>
            </part>

            This copies a new background colour value from ".revue.settings.tui.menu_item_background" to the
            destination element's property "#background", which is stored in ".revue.temporary.character".
            But by copying the colour value to the "#background" property, that property does not contain
            a knowledge path of the kind ".revue.settings.tui.menu_item_background" anymore, but rather
            a simple colour value like "blue". At that time, the abstraction "knowledge" would NOT be
            correct anymore, because the simple colour value is of abstraction "character" instead.

        A2: Even if CYBOI-internal procedures implemented a mechanism that tried to retrieve the
            real model that a knowledge model path pointed to, this would NOT solve the problem!
            The reason is that then not the actual value of the property would be set, but rather
            the value of the standard setting (!) that the knowledge path pointed to.

            --> RULE to avoid the problems described in A1 and A2:
            Single properties of a textual user interface (tui) should not be stored as knowledge path
            of abstraction "knowledge" or "encapsulated", but always as primitive values.
            To ease application development, however, there is the possibility to use the "super" property,
            which permits the inheritance of properties like colours etc. Following an example:

            <part name="main_window" channel="file" abstraction="compound" model="revue/tui/main_window/window.cybol">
                <property name="super" channel="inline" abstraction="knowledge" model=".revue.settings.tui.window"/>
                <property name="position" channel="inline" abstraction="integer" model="0,0,0"/>
                <property name="size" channel="inline" abstraction="integer" model="80,24,1"/>
            </part>

            A corresponding settings file may look like this:

            <model>
                <part name="shape" channel="inline" abstraction="character" model="rectangle"/>
                <part name="layout" channel="inline" abstraction="character" model="coordinates"/>
                <part name="background" channel="inline" abstraction="character" model="blue"/>
                <part name="foreground" channel="inline" abstraction="character" model="white"/>
                <part name="bold" channel="inline" abstraction="boolean" model="true"/>
            </model>

            CAUTION! The solution proposed above does not (yet) work satisfyingly.
            Only real properties of a knowledge template are created, but NOT those of a super model.
            In other words, a created runtime knowledge model that links to a super model does not
            own the properties of the super model itself. This causes a problem because logic templates
            like "select_next_part.cybol" try to access the properties of a model DIRECTLY, for example
            for setting a colour. But if the property does not exist in the model and only in its
            super model, then it cannot be set.

            --> TODO: For later versions of CYBOI, the super templates/ models must be handled better, either:
            1 at creation time in form of a super template whose properties would get instantiated for the model containing the super property
                it is important that the super template should only deliver the properties for the current template,
                but not be created (instantiated) itself (handle this in CYBOL parser or XML translator)
            2 at runtime, as it is done now in the tui, which gets the properties of a super model at runtime
                the problem here is that the model does not really itself contain the properties of its super model,
                as described above
            ==> solution 1 seems desirable, but would need some thinking on how to implement this in CYBOI;
                this is a kind of "prototype programming"-like approach
            ==> for now, as temporary solution, the properties are stored redundantly (twice) in the template
                that needs them (for example "menu_item" entries in the resmedicinae-revue menu) and in its super template

        * Implement an own solution for character set conversion, since the
            three function sets of the gnu C library all have their drawbacks
            (see comment at beginning of file "utf_8_unicode_character_converter.c")
