Merge pull request #23 from RISC-OS-Community/develop

Develop

.gitattributes

@@ -1,23 +1,49 @@
-src/c/** gitlab-language=c linguist-language=c linguist-detectable=true
-src/h/** gitlab-language=c linguist-language=c linguist-detectable=true
-src/c++/** gitlab-language=cpp linguist-language=cpp linguist-detectable=true
-src/cpp/** gitlab-language=cpp linguist-language=cpp linguist-detectable=true
-src/bas/** gitlab-language=bbcbasic linguist-language=bbcbasic linguist-detectable=true
-src/s/** gitlab-language=armasm linguist-language=assembly linguist-detectable=true
-src/Hdr/** gitlab-language=armasm linguist-language=assembly linguist-detectable=true
-src/fth/** gitlab-language=forth linguist-language=forth linguist-detectable=true
-src/p/** gitlab-language=prolog linguist-language=prolog linguist-detectable=true
-tests/**/c/** gitlab-language=c linguist-language=c linguist-detectable=true
-tests/**/h/** gitlab-language=c linguist-language=c linguist-detectable=true
-tests/**/c++/** gitlab-language=cpp linguist-language=cpp linguist-detectable=true
-tests/**/cpp/** gitlab-language=cpp linguist-language=cpp linguist-detectable=true
-tests/**/bas/** gitlab-language=bbcbasic linguist-language=bbcbasic linguist-detectable=true
-tests/**/Hdr/** gitlab-language=armasm linguist-language=assembly linguist-detectable=true
-tests/**/s/** gitlab-language=armasm linguist-language=assembly linguist-detectable=true
-tests/**/fth/** gitlab-language=forth linguist-language=forth linguist-detectable=true
-tests/**/p/** gitlab-language=prolog linguist-language=prolog linguist-detectable=true
-**,fe1 gitlab-language=make linguist-language=makefile linguist-detectable=true
-**,fff gitlab-language=text linguist-language=text linguist-detectable=true
-**,ffb gitlab-language=bbcbasic linguist-language=bbcbasic linguist-detectable=true
-VersionNum gitlab-language=c linguist-language=c
+# THIS IS ONLY FOR THE gitattributes REPOSITORY.
+# Handle line endings automatically for files detected as text
+# and leave all files detected as binary untouched.
+#*               text=auto
 
+#
+# The above will handle all files NOT found below
+#
+# These files are text and should be normalized (Convert crlf => lf)
+*.gitattributes text linguist-language=gitattributes export-ignore
+.gitignore      text export-ignore
+*.md            text diff=markdown linguist-detectable
+*.txt           text diff=text linguist-detectable
+
+# Language attributes for RISC OS files:
+*.pdf	       -text
+
+doc/**         linguist-documentation
+
+*,102          text diff=perl linguist-language=perl
+*,a73          text diff=python linguist-language=python
+*,a74          text diff=python linguist-language=python 
+*,a75          text diff=python linguist-language=python
+*,18c          text diff=lua linguist-language=lua
+*,fe1          text diff=makefile linguist-language=makefile
+*,fff          text diff=text linguist-language=text
+*,ffb          text diff=bbcbasic linguist-language=bbcbasic 
+*,fd1          text diff=bbcbasic linguist-language=bbcbasic
+
+src/**/c/*     text diff=c linguist-language=c
+src/**/h/*     text diff=c linguist-language=c
+src/**/c++/*   text diff=cpp linguist-language=cpp
+src/**/cpp/*   text diff=cpp linguist-language=cpp 
+src/**/bas/*   text diff=bbcbasic  linguist-language=bbcbasic
+src/**/s/*     text diff=armasm linguist-language=assembly
+src/**/Hdr/*   text diff=armasm linguist-language=assembly
+src/**/fth/*   text diff=forth linguist-language=forth
+src/**/p/*     text diff=prolog linguist-language=prolog
+tests/**/c/*   text diff=c linguist-language=c
+tests/**/h/*   text diff=c linguist-language=c
+tests/**/c++/* text diff=cpp linguist-language=cpp
+tests/**/cpp/* text diff=cpp linguist-language=cpp
+tests/**/bas/* text diff=bbcbasic linguist-language=bbcbasic
+tests/**/Hdr/* text diff=armasm linguist-language=assembly
+tests/**/s/*   text diff=armasm linguist-language=assembly
+tests/**/fth/* text diff=forth linguist-language=forth
+tests/**/p/*   text diff=prolog linguist-language=prolog
+
+VersionNum     linguist-language=c gitlab-language=c

CONTRIBUTING.md

@@ -149,5 +149,11 @@ If you fear having to learn git or if you just want to help us with reviewing do
 The Android/Apple GitHub application makes it very easy to interact with us and provide your contribution without the need to learn git!
 Have a look in your device' on-line store for the GitHub application published by GitHub.
 
+# We now have a repo dedicated to Everything Coding on RISC OS
+
+The repo is maintained and updated to collect resources to help everyone (from absolute beginners till experienced developers) to learn and/or improve codign skills on RISC OS.
+
+You can find the repo [here](https://github.com/RISC-OS-Community/CodingOnRISC-OS)
+
 So no excuses! ;-)
 

doc/00DME0BRD.md

@@ -20,25 +20,27 @@ So we thought it would be very useful to introduce a way to allow such changes t
 At the same time such changes shall not be invasive and shall be kept optional for the userbase that prefers the original way RISC OS has to interact with the user.
 
 RISC OS Desktop and its users would benefit from:
+
 - A customizable desktop through the addition of a powerful and easy to use Theme Manager
 - More modern and useful functionalities like 
   - Introducing instant desktop notifications via a new configurable framework
   - Fast features access via a new global keyboard shortcuts framework
-  - Essential keyboard control of the mouse pointer (for those situations where the mouse may abbandon us!)
-  - and more 
+  - Essential keyboard control of the mouse pointer (for those situations where the mouse may abandon us!)
+  - and more
 
 ## Success factors
 
 We'd define as success factors for this project:
-- The possibility for a new user to define and use an environment and UI as close as possible to "the modern perceptions created by far more popular OS like MS Windows and Apple macOS". While users acustomed to the old UI shall be let free to keep using the OS as they liked it to be.
+
+- The possibility for a new user to define and use an environment and UI as close as possible to "the modern perceptions created by far more popular OS like MS Windows and Apple macOS". While users accustomed to the old UI shall be let free to keep using the OS as they liked it to be.
 - An extremely easy way to achieve their UI configuration goals that would require little to no knowledge of RISC OS for the new users and little to no knowledge of the new UI from experienced users.
-- All the changes and improvements would reside in a single and easy to install (and remove) "Package". 
+- All the changes and improvements would reside in a single and easy to install (and remove) "Package".
 
 ## Project Scope
 
-This project has no intention to modify the OS internals. In a first phase it should be limited to work to add the required tools to achieve the goals in the overview and, eventually, in a second phase it may be sligthely more *invasive*, but only from the UI (WIMP) point of view.
+This project has no intention to modify the OS internals. In a first phase it should be limited to work to add the required tools to achieve the goals in the overview and, eventually, in a second phase it may be slightly more *invasive*, but only from the UI (WIMP) point of view.
 
-Also we'd like to avoid "re-inventing the wheel" wherever possible and so we shall reuse (and improve) existsing tools to achieve the goals (where we'll be allowed by the original authors of such tools).
+Also we'd like to avoid "re-inventing the wheel" wherever possible and so we shall reuse (and improve) existing tools to achieve the goals (where we'll be allowed by the original authors of such tools).
 
 ## Project constraints
 
@@ -50,13 +52,12 @@ However the project is open and welcoming everyone that would like to join us an
 
 All DME components should be designed and developed having in mind the following requirements:
 
-- They should all work from an ARM3 + 8MB RAM RISC OS 3.10 system up to modern and latest RISC OS. The reason for this is it would be nice  to have an homogeneous approach on all my RISC OS systems and releases. This requirement is not absolute, if certain components can not be made for older RISC OS (or for the minimal platform), then this requirement should be considered optional. 
-- Everything has to be Open Source (possibly released under CDDL v1.1 license) and buildable with Open Source tools (but also buildable using DDE). Given that all the DME components are external, it's not mandatory to support ROOL Builder, but it is a nice to have. 
+- They should all work from an ARM3 + 8MB RAM RISC OS 3.10 system up to modern and latest RISC OS. The reason for this is it would be nice  to have an homogeneous approach on all my RISC OS systems and releases. This requirement is not absolute, if certain components can not be made for older RISC OS (or for the minimal platform), then this requirement should be considered optional.
+- Everything has to be Open Source (possibly released under CDDL v1.1 license) and "build-able" with Open Source tools (but also using DDE). Given that all the DME components are external, it's not mandatory to support ROOL Builder, but it is a nice to have.
 - Everything must support proper application window updates using NULL events and simulate as much as possible a preemptive system. 
 - Everything must interact (where needed) with other DME components and RISC OS itself, integration is key for this project.
 - Code should be designed to be as performant as possible and support all the Theming (so no assumptions shall be made on backgrounds and colour schemes)
 
 ## Quality control measures
 
 As a fully Open Source project and given the constraints above the quality control measures, this project relies on code reviews and community testing and problem reporting using our Issues Modules (on GitHub).
-

doc/00DME0MRD.md

@@ -1 +1,3 @@
-# Marketing Requirements Document
+# Marketing Requirements Document
+
+RISC OS at the moment does not appear to have an actual Market, so there is no need for such type of analysis.

doc/00DME0PRD.md

@@ -1,30 +1,32 @@
 # Product Requirements Document
 
-## As a RISC OS user I would like that:
+## As a RISC OS user I would like that
 
 *RU0001*
 
 The DME-Core Engine should be able to set:
-- Theme preferences
-- Windowing Configurations (Windows FLags)
-- Load user activated Global Controls
-- Load user activated Desktop Gadgets
+
+* Theme preferences
+* Windowing Configurations (Windows FLags)
+* Load user activated Global Controls
+* Load user activated Desktop Gadgets
 
 ------
 
 *RU0002*
 
 To fulfill RU0001 it should read a configuration file that can be modified by the user using the DME ConfigTools.
 The configuration file:
-- Should reside in !Boot:Choices.DME
-- Should be either a set of configurations files or just a single file
-- It should be following a well define configuration protocol ([see here for more details](02DMEConfigFileP.md))
+
+* Should reside in !Boot:Choices.DME
+* Should be either a set of configurations files or just a single file
+* It should be following a well define configuration protocol ([see here for more details](02DMEConfigFileP.md))
 
 ------
 
 *RU0003*
 
-Every add-on (Global Controls, Theme, Gadget) should be enabbled or disabled via an option on the Configuration UI.
+Every add-on (Global Controls, Theme, Gadget) should be enabled or disabled via an option on the Configuration UI.
 
 ------
 
@@ -34,7 +36,7 @@ For new users there should be an "Initial Configuration" available as a "Wizard
 
 ------
 
-## As a RISC OS Vendor I would like that:
+## As a RISC OS Vendor I would like that
 
 *RV0001*
 
@@ -49,6 +51,7 @@ I would like to be able to control the "Initial Configuration Process" by settin
 ------
 
 ## As a RISC OS Developer/Theme Creator I would like that
+
 *RD0001*
 
 I can use some Wimp Tool to be able to create a Theme instead of having to do everything manually
@@ -66,4 +69,3 @@ I would like to have an easy way to distribute my Theme and for the users to ins
 I would like that the Theme System would work on as many RISC OS devices and RISC OS releases as possible in order to maximise the distribution of my work. Possibly the Theme System should recognise each release of RISC OS and apply my Theme in a way that makes it compatible with the specific version.
 
 ------
-

doc/00DME0TRD.md

@@ -1 +1,51 @@
 # DME Technical Requirements Document
+
+## General requirements
+
+1. DME should be designed and developed supporting the following RISC OS releases:
+
+        OS Release                    |  ARM Arch
+        ----------------------------- | -----------
+        From RISC OS 3.10 to 3.71     | (26 bit)
+        From RISC OS 4.02 TO 4.39     | (26 bit)
+        RISC OS 6.10                  | (26/32 bit)
+        From RISC OS 5.28 onward      | (32 bit)
+
+2. Code should be written in a high level programming language as C, BBC BASIC, Lua etc. giving priority to languages that are fully supported on RISC OS and possibly executable on all supported RISC OS versions.
+
+3. Code should be written to be testable and tests (where applicable) should be included with the code.
+
+4. Code should be written to be "build-able" on a 3rd party RISC OS device, in other words, no customizations of build environment should be done and the build should be designed so it can be executed also on GitHub pipelines.
+
+5. For compiled code, it should be built so that it can work on all releases of RISC OS mentioned at point 1.
+
+6. While it would be great if every single components of the DME would run on all RISC OS versions and all the old platforms, the developer should always consider that features and code stability come first, so when something cannot be made for older versions of RISC OS or old platforms in order to achieve better functionalities and stability then such code should be designed focusing on the modern platforms only.
+
+7. Each component should be always designed having in mind the following parts:
+
+        Part                      |  Description
+        ------------------------- | ----------------------------------------
+        Provide useful features   |  Each component should always provide
+                                  |  useful features to the end user, the
+                                  |  hardware vendor, other developers.
+        ------------------------- | ----------------------------------------
+        Extend OS functionalities |  Each component should always extend
+                                  |  the OS functionality through an API.
+                                  |  Such API should be provided either
+                                  |  as an SWI set (if the component is
+                                  |  executable as a single task element)
+                                  |  OR via WIMP Messages (if the component
+                                  |  is executable ONLY in the WIMP).
+        ------------------------- | ----------------------------------------
+        Follow the RISC OS Style  |  Each component should be designed 
+        Guide                     |  following the RISC OS Style Guide rules
+                                  |  where applicable and define new rules
+                                  |  where the Style guide lack such or is
+                                  |  confusing on the specifics.
+        ------------------------- | ----------------------------------------
+        Integrate with other DME  |  Where applicable, each DME component
+        Components                |  should be designed to integrate with
+                                  |  other DME components and the existing
+                                  |  one on the OS. This in order to avoid
+                                  |  duplication of logic.
+        ------------------------- | ----------------------------------------

doc/01DMEDesign.md

@@ -1,24 +1,45 @@
 # DME-Core
+
 The DME-Core is a RISC OS App that contains both logic and resources to achieve the requirement goals.
 
 DME-Core Directory structure:
-```
-!DMECore
+
+```shell
+!DeskRes
 ├── Resources
-│   └── UK
-└── Store
-    ├── Controls
-    ├── Gadgets
-    └── Themes
+│   └── UK
+├── DME
+│   ├── Components
+│   ├── Gadgets
+│   └── Plugins
+├── Scripts
+│   ├── Autostart
+│   └── Setup
+.
+.
+.
 ```
-The Resources directory is the standard RISC OS repository for territory and messages as well as app templates (if neeved)
 
-The Store directory contains all the Global Controls, Gadgets and Themes repositories.
+The Resources directory is a standard RISC OS repository for territory and messages as well as app templates (if needed)
+
+The DME directory contains all the Global Components, Gadgets and Plugins repositories.
+
+A Component in the DME can be an applications, module or task-module that provides a well defined functionality from the list of macro functionalities defined by the DME architecture.
+
+A Gadget if an Application that uses directly such functionalities to provide a WIMP user-interface to access and use one or more components, if a components doesn't provides a direct UI (User Interface).
+
+A Plugin is generally an piece of software that uses Acorn Plugin protocol to extend the functionalities of either a COmponent or a Gadget.
+
+A Dependency is a pieces of software (generally either a Module or a software Library) required by one or more of the above components.
+
+The !DeskRes app contains a !RunImage file which, when executed, will read:
 
-The !DMECore app contains a !RunImage file which, when executed, will read:
 * The Operating System version
 * The Window Module version
 * The Main Configuration file stored in Boot:Choices.DME [more details about it here](02DMEConfigFileP.md) 
-And it will apply all the changes accordingly (in the futures it may also apply RISC OS Patches required by advnaced functionalities).
 
-The !DMECore should be capable of applying the above on demand and without the need to reboot the system.
+And it will apply all the changes accordingly (in the futures it may also apply RISC OS Patches required by advanced functionalities).
+
+!DeskRes also provides a way to "Autostart" a user selected set of Components and Gadgets (and their dependencies)
+
+The !DeskRes should be capable of applying the above on demand and without the need to reboot the system (where possible).

doc/02DMEConfigFileP.md

@@ -3,18 +3,19 @@ This page describes the DME-Core main configuration file protocol. This file all
 
 Each DME-Core add-ons may have its own configuration file.
 
-Essencially the file format is *key* *value*.
+Essentially the file format is *key* *value*.
 
-Each Keyword (token) in the configuration file is case insenitive, while their values are case sensitive.
+Each Keyword (token) in the configuration file is NOT case sensitive, while their values are case sensitive.
 Each keyword, when parsed, will be trimmed of spaces surrounding it, but no internal spaces will be touched.
 Each keyword value, when parsed, will have surrounding spaces trimmed, but no internal spaces will be touched.
 
 Each line that begins with a "#" symbol is considered a comment and will be ignored.
 
 Protocol example:
-```
+
+```shell
 # DME Section
-# This section provides info for the DME-Core Engine to understadn properly the configuration file
+# This section provides info for the DME-Core Engine to understand properly the configuration file
 # This is useful across different releases of the DME-Core engine
 DMEVer: <version of the DME required to process this file> (required)