Merge pull request #110 from rbmk-plus/master

add ctags, fix dead links, and other minor fixes

.gitignore

@@ -11,6 +11,7 @@
 /*.sym
 /*.asm
 /*.mod
+/Errors.Txt
 /Errors.txt
 /olang
 /src/test/**/*.exe
@@ -20,9 +21,11 @@
 /src/test/**/*.obj
 /src/test/**/*.sym
 **/*.stackdump
+!/src/test/confidence/**/expected
 /src/test/confidence/**/input
 /src/test/confidence/**/result
 /src/test/confidence/**/result-*
+/src/test/confidence/**/*[^.]*
 /src/test/confidence/**/*.asm
 /src/test/confidence/**/*.s
 /src/test/confidence/**/*.map
@@ -39,3 +42,5 @@
 /triage/BasicTypeSize.md
 /triage/Roadmap.md
 triage/system/*
+tags
+voc

ReadMe.md

@@ -2,7 +2,7 @@
 
 # Ѵishap Oberon
 
-[Ѵishap Oberon](http://oberon.vishap.am) is a free and open source (GPLv3)
+[Ѵishap Oberon](https://vishap.oberon.am/) is a free and open source (GPLv3)
 implementation of the Oberon-2 language and libraries for use on
 conventional operating systems such as Linux, BSD, Android, Mac and Windows.
 
@@ -278,13 +278,13 @@ Also, Vishaps are known in tales, fiction. [This page](http://blog.fogus.me/2015
 ###### Oberon
  - [The History of Modula-2 and Oberon](http://people.inf.ethz.ch/wirth/Articles/Modula-Oberon-June.pdf)
  - [The Programming Language Oberon](https://www.inf.ethz.ch/personal/wirth/Oberon/Oberon.Report.pdf)
- - [Project Oberon: The Design of an Operating System and Compiler ](http://www.ethoberon.ethz.ch/WirthPubl/ProjectOberon.pdf)
- - [Oberon - the Overlooked Jewel](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.90.7173&rep=rep1&type=pdf)
+ - [Project Oberon: The Design of an Operating System and Compiler ](https://people.inf.ethz.ch/wirth/ProjectOberon1992.pdf)
+ - [Oberon - the Overlooked Jewel](http://pascal.hansotten.com/uploads/oberonpi/Oberon%20article.pdf)
 
 ###### Oberon 2
- - [Differences between Oberon and Oberon-2](http://members.home.nl/jmr272/Oberon/Oberon2.Differences.pdf)
+ - [Differences between Oberon and Oberon-2](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=89e5bd3cf006bde4821599cdc57a37de5dc84bcd)
  - [The Programming Language Oberon-2](http://www.ssw.uni-linz.ac.at/Research/Papers/Oberon2.pdf)
- - [Programming in Oberon. Steps beyond Pascal and Modula](http://www.ethoberon.ethz.ch/WirthPubl/ProgInOberonWR.pdf)
+ - [Programming in Oberon. Steps beyond Pascal and Modula](https://people.inf.ethz.ch/wirth/ProgInOberonWR.pdf)
  - [The Oakwood Guidelines for Oberon-2 Compiler Developers](http://www.math.bas.bg/bantchev/place/oberon/oakwood-guidelines.pdf)
 
 ###### Oberon 07
@@ -294,10 +294,10 @@ Also, Vishaps are known in tales, fiction. [This page](http://blog.fogus.me/2015
 
 ###### Links
  - [Niklaus Wirth's personal page at ETH Zurich](https://www.inf.ethz.ch/personal/wirth/)
- - [ETH Zurich's Wirth publications page](http://www.ethoberon.ethz.ch/WirthPubl/)
- - [Joseph Templ's ofront on github](https://hithub.com/jtempl/ofront)
+ - [Selected articles by Niklaus Wirth](https://people.inf.ethz.ch/wirth/SelectedArticles.pdf)
+ - [ETH Oberon publications page](https://web.archive.org/web/20191207155011/http://www.ethoberon.ethz.ch/books.html)
+ - [Joseph Templ's ofront on github](https://github.com/jtempl/ofront)
  - [Software Templ OG](http://www.software-templ.com)
- - [Oberon: Steps beyond Pascal and Modula](http://fruttenboel.verhoeven272.nl/Oberon/)
 
 
 ## History

doc/ctags.md

@@ -0,0 +1,82 @@
+## Code navigation with ctags
+
+[`ctags`](https://github.com/universal-ctags/ctags) is a tool that creates an index file for names in various programming langauges, which helps code comprehension by giving information to text editors to search, locate, and interactively suggest names, identifiers, symbols etc. Particularly for Oberon, the `oberon.ctags` file, located in the project root, contains definitions for Oberon modules and procedures (but not receiver procedures). 
+
+Below you can find installation instructions and usage examples for `ctags` to navigate Oberon source code, in particular, using the universal tags implementation (not tested with other implementations), with `vim` (you can find or add guides for your text editor). 
+
+## Install universal tags
+
+#### Use your package manager
+
+`pacman -S ctags` (arch linux)  
+`apt install universal-ctags` (debian, ubuntu)  
+`brew install universal-ctags` (macOS)  
+...
+
+#### Compile from source 
+
+`git clone https://github.com/universal-ctags/ctags.git`  
+follow [build instructions](https://github.com/universal-ctags/ctags/blob/master/README.md#how-to-build-and-install)  
+
+## Using ctags with vim and Oberon
+
+the following instructions are for POSIX systems, but can be easily adapted to other systems
+
+#### Configuration
+
+First, generate tags in project root  
+`make tags`
+
+When you add or change names in source files, you have to regenerate the `tags` file. That can be done by running `make tags` again. Optionally, use a `vim` plugin such as [vim-gutentags](https://github.com/ludovicchabant/vim-gutentags) to automate this process. Install it (or skip this step):
+
+`git clone https://github.com/ludovicchabant/vim-gutentags ~/.vim/plugin/`  
+
+or wherever your vim global plugin directory is specified in `:h plugin`. 
+
+Add this to your `~/.vimrc`
+```
+" search upwards for tags file until home directory
+set tags=./tags;~
+" qualified name metadata for plugin
+let g:gutentags_ctags_extra_args = ['--extras=+q']
+```
+
+To use `oberon.ctags` with a plugin or for Oberon language detection outside its directory:   
+`cp oberon.ctags ~/.config/ctags/`  
+or  
+`cp oberon.ctags $XDG_CONFIG_HOME/ctags/`  
+
+#### Usage examples
+
+tags documentation is in vim
+`:h tags`
+
+some examples:
+```
+vim -t "Compiler"
+vim -t "OPS.Get"
+vim -c ":ts Platform.Read"
+vim -c ":ta BrowserCmd.ShowDef"
+```
+
+Inside vim when you have cursor on the first letter `M` of `Module.Procedure`, do this to jump to procedure definition:  
+`v 3e <C-]>`    *(visually select the fully qualified name)*  
+module definition:  
+`<C-]>`  
+To come back:  
+`<C-o>`
+
+Putting cursor on `P` of `Module.Procedure` is not guaranteed to resolve correctly to the correct module, so choose the fully qualified name. This is a [known limitation](https://docs.ctags.io/en/latest/man/ctags-faq.7.html#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name) of `ctags` (any suggestions for handling this better are welcome).
+
+To address this, you can visually select as in the above examples, or resolve ambiguities interactively:  
+`g <C-]>`  
+`:ts Write`  
+`:ts Platform.Write`  
+or make vim see the qualified name as a complete keyword:  
+`iskeyword+=.`  
+in `.vimrc`  
+`autocmd FileType oberon,modula2 setlocal iskeyword+=.`  
+
+**TODO**  
+There is some auto-completion, but it doesn't work well. One idea is to define a custom `omnifunc` that suggests only exported symbols (`*`) from a file (module scope is file), so that when you type `OPS.` and press `<C-P>` you can have useful suggestions (similar to `showdef`).
+

makefile

@@ -91,8 +91,11 @@ usage:
 	@echo "  make bootstrap       - Update bootstrap C source directories."
 	@echo "  make revertbootstrap - Use git checkout to restore bootstrap C source directories"
 
-
-
+# Code navigation helper
+# doc/ctags.md
+.PHONY: tags
+tags: 
+	ctags -R --options=oberon.ctags --extras=+q
 
 # Generate config files Configuration.Make and Configuration.Mod
 FORCE:

oberon.ctags

@@ -0,0 +1,14 @@
+# universal tags
+# ctags -R --options=oberon.ctags --extras=+q
+
+--langdef=Oberon{_autoFQTag}
+
+--map-Oberon=+.mod
+--map-Oberon=+.Mod
+
+--kinddef-Oberon=m,module,modules
+--kinddef-Oberon=p,procedure,procedures
+
+--regex-Oberon=/^\s*MODULE\s+([a-zA-Z][a-zA-Z0-9]*)\s*;/\1/m/{scope=push}
+--regex-Oberon=/^\s*PROCEDURE\s*(\^|-)?\s*([a-zA-Z][a-zA-Z0-9]*)/\2/p/{scope=ref}
+

src/tools/make/configure.c

@@ -125,19 +125,22 @@ void determineOS() {
 }
 
 #define optimize "" // " -O1"
+// FIXME ignoring warning floods that possibly are problems
+#define ignore_gcc_warning_flood " -Wno-stringop-overflow"
+#define ignore_clang_warning_flood " -Wno-deprecated-non-prototype"
 
 void determineCCompiler() {
   snprintf(libspec, sizeof(libspec), " -l%s", oname);
   #if defined(__MINGW32__)
     compiler = "mingw";
     if (sizeof (void*) == 4) {
-      cc = "i686-w64-mingw32-gcc -g" optimize;
+      cc = "i686-w64-mingw32-gcc -g" ignore_gcc_warning_flood optimize;
     } else {
-      cc = "x86_64-w64-mingw32-gcc -g" optimize;
+      cc = "x86_64-w64-mingw32-gcc -g" ignore_gcc_warning_flood optimize;
     }
   #elif defined(__clang__)
     compiler = "clang";
-    cc       = "clang -fPIC -g" optimize;
+    cc       = "clang -fPIC -g" ignore_clang_warning_flood optimize;
   #elif defined(__TINYC__)
     compiler = "tcc";
     cc       = "tcc -g";
@@ -146,9 +149,9 @@ void determineCCompiler() {
     compiler = "gcc";
     if (strncasecmp(os, "cygwin",  6) == 0) {
       // Avoid cygwin specific warning that -fPIC is ignored.
-      cc = "gcc -g" optimize;
+      cc = "gcc -g" ignore_gcc_warning_flood optimize;
     } else {
-      cc = "gcc -fPIC -g" optimize;
+      cc = "gcc -fPIC -g" ignore_gcc_warning_flood optimize;
     }
   #elif defined(_MSC_VER)
     compiler  = "msc";

src/tools/make/sourcechanges.sh

@@ -14,8 +14,8 @@
 changes="0"
 find "$1" -type f -print0 | while IFS= read -r -d '' f; do
   fn=$(basename "$f")
-  egrep -v -f ../../src/tools/make/ignore "$f"  >$fn.old
-  egrep -v -f ../../src/tools/make/ignore $fn >$fn.new
+  grep -E -v -f ../../src/tools/make/ignore "$f"  >$fn.old
+  grep -E -v -f ../../src/tools/make/ignore $fn >$fn.new
   if ! diff -U 2 -b $fn.old $fn.new >$fn.diff; then
     echo ""
     echo ""