make instructions more nice

- use english consequently (this avoid umlauts...)
- adapt better to markdown syntax

instructions_specifications.md

@@ -1,134 +1,145 @@
 # Installation
 
-python virtual env machen:
+create python virtual env (you might choose another name than 'myenv'):
 
-> python3 -m venv myenv
+    python3 -m venv myenv
 
-aktivieren dieser venv (wiederholen bei jeder session):
+aktivate this venv (to be repeated for each session):
 
-> source myenv/activate
+    source myenv/activate
 
-seweb git repo klonen (token ist max. ein Jahr gueltig):
+close seweb git repository (token is valid for one year only):
 
-> git clone https://dm:krChVHhLuAntP-sG1T1g@gitlab.psi.ch/samenv/seweb.git
+    git clone https://dm:krChVHhLuAntP-sG1T1g@gitlab.psi.ch/samenv/seweb.git
+    cd seweb
 
-> cd seweb
+switch to your development branch:
 
-in deinen Entwicklungsbranch wechseln:
+    git switch daniel
 
-> git switch daniel
+instal needed packages (goes into myenv)
 
-noetige packages installieren (wird in myenv gepackt!)
-
-> pip3 install -r requirements.txt
+    pip3 install -r requirements.txt
 
 # First Run
 
-demo frappy server starten
+start demo frappy server
 
-> frappy-server cryo,test -p 5000
+    frappy-server cryo,test -p 5000
 
-dieses Terminal offen lassen, neues Terminal starten
+this terminal should stay open, now open another terminal and type:
 
-> source myenv/activate
-> cd seweb
+    source myenv/activate
+    cd seweb
 
-dummy webserver starten, verbindet mit obigem frappy server
+start dummy webserver, connects with above frappy server
 
-> ./dummy-webserver port=8888 instrument=test hostport=localhost:5000
+    ./dummy-webserver port=8888 instrument=test hostport=localhost:5000
 
-webclient im browser starten mit http://localhost:8888/
+start webclient in browser with http://localhost:8888/
 
 # git
 
-Branches anzeigen:
+show branches:
 
-> git branch
+    git branch
 
-In deinen Branch gehen, wenn nicht schon da:
+switch to your branch, if not yet there:
 
-> git switch daniel
+    git switch daniel
 
 ## Aenderungen pushen
 
-fuer jede thematisch zusammenhaenge Aenderung einen Commit machen:
+make a commit for each batch of coherent code changes:
 
-> git add <new files>
-> git commit -a -m "repalce icons by nicer ones"
+    git add <new files>
+    git commit -a -m "replace icons by nicer ones"
 
-Wenn Du den teil beginnend mit -m weglaesst, oeffnet sich der default Editor,
-dann kannst Du auch mehrzeilige Kommentare machen. 1. Zeile: Titel, 2. Zeile leer
-ab 3. Zeile: Text, nicht breiter als ca. 72 Zeichen
+If the part starting by '-m' is omitted, the default editor opens,
+this is helpful for create an extended commit message.
+Keep the following format: first line summary, empty 2nd line,
+then more lines may follow. Keep witdh within about 72 chars.
 
-> git push
+    git push
 
-## Aenderungen vom repo uebernehmen
+## Merge changes from other developers
 
-Wenn noch offene Aenderungen da sind, die Du noch nicht committen willst,
-kannst Du diese Aenderungen zwischenlagern (ist ein Stapel!)
+Assume there are some changes in branch 'master' you want to
+include in your branch.
+If you have uncommitted chanes you do not want to commit yet,
+you may save this changes temporarely on a stack:
 
-> git stash
+    git stash
 
-Zum master branch wechseln, und diesen runterziehen vom Repo:
+Change to master branch and pull the current version:
 
-> git switch master
-> git pull
+    git switch master
+    git pull
 
-Die Aenderungen vom master in Deinen branch uebernehmen:
+Take over these changes in your branch:
 
-> git switch daniel
-> git rebase
+    git switch daniel
+    git rebase
 
-Falls Konflikte entstehen, bekommst Du eine entsprechende Meldung
+If conflicts arise, read carefully the instructions and follow them.
 
-Wenn diese geloest sind, Deine vorher zwischengespeicherten offenen Aenderungen zurueckholen
+After this, in case you did the git stash command above, you want get back your current modifications now:
 
-> git stash pop
+    git stash pop
 
 
+# Specifications
+
 ## Tile Layout
 
 4 types of blocks/tiles:
-graphics
-moduleblock (list of modules with main values), (goodie: foldable groups)
-parblock (editable list of parameters) (goodie: foldable groups)
-logblock (log messages) placed in right bottom quarter
+- graphics
+- moduleblock (list of modules with main values),
+  (goodie: foldable groups, may need some changes in the server code)
+- parblock (editable list of parameters) (goodie: foldable groups)
+- logblock (log messages) placed in right bottom quarter
 
 console is no longer used!
 
 (x) means a button in the top right corner
 
 for narrow windows < 2w:
-show moduleblock by default
-(x) on graphics: go to moduleblock
-(x) on modules: go to graphics
-clicking on moduleblock: open parblock
-(x) on parblock: go to moduleblock
-logblock is shown by clicking on right bottom icon (not available with graphics) and hidden with (x)
-allow to swipe when touch device is available (do we need this?)
+
+- show moduleblock by default
+- (x) on graphics: go to moduleblock
+- (x) on modules: go to graphics
+- clicking on moduleblock: open parblock
+- (x) on parblock: go to moduleblock
+- logblock is shown by clicking on right bottom icon
+  (not available with graphics) and hidden with (x)
+- allow to swipe when touch device is available (do we need this?)
 
 for broader windows:
-show graphics + moduleblock by default
-(x) not shown on graphics by default
-(x) on modules: full screen graphics
-click on a module row (or a 'details' icon): add parblock, do not overwrite moduleblock when window is broad 
-enough (width > 3.5w)
-(x) on parblock (close parblock and reveal moduleblock if hidden)
-logblock is shown by clicking on right bottom icon and hidden with (x) 
-swipe not possible
+
+- show graphics + moduleblock by default
+- (x) not shown on graphics by default
+- (x) on modules: full screen graphics
+- click on a module row (or a 'details' icon): add parblock,
+  do not overwrite moduleblock when window is broad enough (width > 3.5w)
+- (x) on parblock (close parblock and reveal moduleblock if hidden)
+- logblock is shown by clicking on right bottom icon and hidden with (x) 
+- swipe not possible
 
 ## moduleblocks
 
-  on each row:
-colored indicator depending on status (yellow: driving, orange: warn, red: error)
-red also when value is in error
-edit icon for changing the target parameter of the module, if available
-'details' icon for open the corresponding parblock
+on each row:
+- colored indicator depending on status
+  (yellow: busy, orange: warn, red: error)
+- red also when value is in error
+- edit icon for changing the target parameter of the module,
+  if available
+- 'details' icon for open the corresponding parblock
+  (instead or in addittion to link on name)
 
 ## parblocks
 
-orange when parameter is in error (update message with error instead of value: show a little icon with hover 
-revealing error text)
+orange when parameter is in error (update message with error
+instead of value: show a little icon with hover revealing error text)
 
 ## logging
 
@@ -136,8 +147,7 @@ use logging feature of SECoP - needs some work on the server (Markus)
 
 ## resizing window
 
-hide parameters when size < 3.5w
-hide graphics when size  < 2w
-show graphics when size > 2w
-it is not needed to show the parblock again when increasing width
-nderungen wieder zur
+- hide parameters when size < 3.5w
+- hide graphics when size  < 2w
+- show graphics when size > 2w
+- it is not needed to show the parblock again when width is increased