From c6d48c57f649c78f605c26db0587e28e84f98d00 Mon Sep 17 00:00:00 2001
From: Filip Gralinski <filipg@amu.edu.pl>
Date: Sat, 1 Sep 2018 16:39:00 +0200
Subject: [PATCH] improve documentation on geval --submit

---
 README.md                  | 37 ++++++++++++++++++++++++++++++++++---
 src/GEval/OptionsParser.hs |  2 +-
 src/GEval/Submit.hs        |  3 ++-
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index ff38b79..428a3d9 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ have a look at the first 5 items:
 Now let's try to evaluate some solution to this challenge. Let's fetch it:
 
     git fetch git://gonito.net/sentiment-by-emoticons submission-01865
-    git reset --hard FECH_HEAD
+    git reset --hard FETCH_HEAD
 
 and now run geval:
 
@@ -203,7 +203,38 @@ be nice and commit also your source codes.
     git commit -m 'my solution to the challenge'
     git push mine master
 
-Then let Gonito pull them and evaluate your results.
+Then let Gonito pull them and evaluate your results, either manually clicking
+"submit" at the Gonito web site or using `--submit` option (see below).
+
+### Submitting a solution to a Gonito platform with GEval
+
+A solution to a machine learning challenge can be submitted with the
+special `--submit` option:
+
+    geval --submit --host HOST --token TOKEN
+
+where:
+
+* _HOST_ is the name of the host with a Gonito platform
+* _TOKEN_ is a special per-user authorisation token (can be copied
+  from "your account" page)
+
+_HOST_ must be given when `--submit` is used (unless the creator of the challenge
+put `--host` option in the `config.txt` file, note that in such a case using
+`--host` option will result in an error).
+
+If _TOKEN_ was not given, GEval attempts to read it from the `.token`
+file, and if the `.token` file does not exist, the user is asked to
+type it (and then the token is cached in `.token` file).
+
+GEval with `--submit` does not commit or push changes, this needs to
+be done before running `geval --submit`. On the other hand, GEval will
+check whether the changes were committed and pushed.
+
+Note that using `--submit` option for the main instance at
+<https://gonito.net> is usually **NOT** needed, as the git
+repositories are configured there in such a way that an evaluation is
+triggered with each push anyway.
 
 ## `geval` options
 
@@ -246,7 +277,7 @@ Available options:
                            (separated by spaces) on the standard output. rather
                            than do any evaluation. The --tokenizer option must
                            be given.
-  -S,--submit              Submit current solution for evalution to an external
+  -S,--submit              Submit current solution for evaluation to an external
                            Gonito instance specified with --gonito-host option.
                            Optionally, specify --token.
   -s,--sort                When in line-by-line or diff mode, sort the results
diff --git a/src/GEval/OptionsParser.hs b/src/GEval/OptionsParser.hs
index 6d76fe7..ad22bdd 100644
--- a/src/GEval/OptionsParser.hs
+++ b/src/GEval/OptionsParser.hs
@@ -74,7 +74,7 @@ optionsParser = GEvalOptions
                 (flag' Submit
                     ( long "submit"
                       <> short 'S'
-                      <> help "Submit current solution for evalution to an external Gonito instance specified with --gonito-host option. Optionally, specify --token."))
+                      <> help "Submit current solution for evaluation to an external Gonito instance specified with --gonito-host option. Optionally, specify --token."))
                 )
 
    <*> ((flag' FirstTheWorst
diff --git a/src/GEval/Submit.hs b/src/GEval/Submit.hs
index aab4703..1ff6f9b 100644
--- a/src/GEval/Submit.hs
+++ b/src/GEval/Submit.hs
@@ -50,7 +50,8 @@ submit (Just host) tok = do
 
 trigger :: String -> String -> String -> String -> String -> IO ()
 trigger host token branch challengeId repoUrl = do
-    putStrLn $ "triggering: " ++ url
+    putStrLn $ "Triggering: " ++ url
+    putStrLn "Please wait, it may take some time"
     req <- parseRequest url
     let params = map (\(pname, pval) -> (BS.pack $ pname, BS.pack $ pval)) [
           ("challenge", challengeId),