Many changes, mainly to content, in preparation for version 1.0.0

project.clj

@@ -3,43 +3,32 @@
   :url "https://github.com/simon-brooke/smeagol"
   :license {:name "GNU General Public License,version 2.0 or (at your option) any later version"
             :url "https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html"}
-
+  :dependencies [[clj-jgit "0.8.9"]
-  :dependencies [[org.clojure/clojure "1.8.0"]
-                 [org.clojure/core.memoize "0.5.9"]
-                 [org.clojure/data.json "0.2.6"]
-                 [org.clojure/tools.logging "0.4.0"]
-                 [org.clojars.simon_brooke/internationalisation "1.0.3"]
-                 [clj-jgit "0.8.9"]
                  [clj-yaml "0.4.0"]
                  [com.cemerick/url "0.1.1"]
                  [com.fzakaria/slf4j-timbre "0.3.7"]
                  [com.taoensso/encore "2.91.1"]
-                 [lib-noir "0.9.9" :exclusions [org.clojure/tools.reader]]
                  [com.cemerick/url "0.1.1"]
-                 [ring/ring-anti-forgery "1.1.0"]
-                 [ring-server "0.4.0"]
-                 [selmer "1.10.9"]
-                 [org.clojure/tools.logging "0.4.0"]
                  [com.taoensso/timbre "4.10.0"]
                  [com.fzakaria/slf4j-timbre "0.3.7"]
-                 [org.slf4j/slf4j-api "1.7.25"]
-                 [org.slf4j/log4j-over-slf4j "1.7.25"]
-                 [org.slf4j/jul-to-slf4j "1.7.25"]
-                 [org.slf4j/jcl-over-slf4j "1.7.25"]
                  [com.taoensso/tower "3.0.2" :exclusions [com.taoensso/encore]]
-                 [markdown-clj "0.9.99" :exclusions [com.keminglabs/cljx]]
                  [crypto-password "0.2.0"]
-                 [clj-jgit "0.8.9"]
                  [environ "1.1.0"]
                  [im.chit/cronj "1.4.4"]
                  [lib-noir "0.9.9" :exclusions [org.clojure/tools.reader]]
                  [markdown-clj "0.9.99" :exclusions [com.keminglabs/cljx]]
                  [noir-exception "0.2.5"]
+                 [org.clojars.simon_brooke/internationalisation "1.0.3"]
+                 [org.clojure/clojure "1.8.0"]
+                 [org.clojure/core.memoize "0.5.9"]
+                 [org.clojure/data.json "0.2.6"]
+                 [org.clojure/tools.logging "0.4.0"]
                  [org.slf4j/slf4j-api "1.7.25"]
                  [org.slf4j/log4j-over-slf4j "1.7.25"]
                  [org.slf4j/jul-to-slf4j "1.7.25"]
                  [org.slf4j/jcl-over-slf4j "1.7.25"]
                  [prone "1.1.4"]
+                 [ring/ring-anti-forgery "1.1.0"]
                  [ring-server "0.4.0"]
                  [selmer "1.11.0"]]
 

resources/public/content/Deploying Smeagol.md

@@ -0,0 +1,52 @@
+## Deploying as a stand-alone application
+To deploy Smeagol as a stand-alone application, either download the jar file for the release you want to deploy, or clone the source and compile it with:
+
+    lein bower install
+    lein ring uberjar
+		
+This will create a jar file in the `target` directory, named `smeagol-`*VERSION*`-standalone.jar`. 
+
+Smeagol cannot access either its configuration or its content from the jar file. Consequently you should set up three environment variables:
+
+1. **SMEAGOL_CONFIG** should be the full or relative pathname of a Smeagol [[Configuration]] file;
+2. **SMEAGOL\_CONTENT\_DIR** should be the full or relative pathname of the directory from which Smeagol should serve content (which may initially be empty, but must be writable by the process which runs Smeagol)'
+3. **SMEAGOL_PASSWD** should be the full or relative pathname of a Smeagol Passwd file - see [[Security and authentication]]. This file must contain an entry for at least your initial user, and, if you want to administer users through the user interface, must be writable by the process which runs Smeagol);
+
+You can run the jar file with:
+
+    java -jar smeagol-VERSION-standalone.jar
+		
+## Deploying within a servlet container
+To deploy Smeagol within a servlet container, either download the jar file for the release you want to deploy, or clone the source and compile it with:
+
+    lein bower install
+    lein ring uberwar
+		
+This will create a war file in the `target` directory, named `smeagol-`*VERSION*`-standalone.war`.  Deploy this to your servlet container in the normal way; details will depend on your container. Instructions for Tomcat are [here](https://tomcat.apache.org/tomcat-8.0-doc/deployer-howto.html).
+
+The problem with this is that unless the environment variables (see above) were already set up in the environment of the servlet container at the time when the servlet container were launched, Smeagol will run with its built-in defaults. This will run perfectly satisfactorily provided your servlet container is configured to unpack war files, which most are.
+
+## Experimental Docker image
+
+You can now run Smeagol as a [Docker](http://www.docker.com) image. Read more about [[Using the Docker Image]].
+
+To run my Docker image, use
+
+    docker run simonbrooke/smeagol
+
+Smeagol will run, obviously, on the IP address of your Docker image, on port 8080. To find the IP address, start the image using the command above and then use
+
+    docker inspect --format '{{ .NetworkSettings.IPAddress }}' $(docker ps -q)
+
+Suppose this prints '10.10.10.10', then the URL to browse to will be http://10.10.10.10:8080/smeagol/
+
+This image is _experimental_, but it does seem to work fairly well. What it does **not** yet do, however, is push the git repository to a remote location, so when you tear the Docker image down your edits will be lost. My next objective for this image is for it to have a cammand line parameter being the git address of a repository from which it can initialise the Wiki content, and to which it will periodically push local changes to the Wiki content.
+
+To build your own Docker image, run:
+
+    lein clean
+    lein bower install
+    lein ring uberwar
+    lein docker build
+
+This will build a new Docker image locally; you can, obviously, push it to your own Docker repository if you wish.

resources/public/content/Developing Smeagol.md

@@ -4,60 +4,21 @@ You will need [Leiningen](https://github.com/technomancy/leiningen) 2.0 or above
 
 You will need [node](https://nodejs.org/en/) and [bower](https://bower.io/) installed.
 
-## Running
+## Running in development
-### In development
 To start a web server for the application during development, run:
 
     lein bower install
     lein ring server
 		
-### In production
+This should start a development server, and open a new window or tab in your default browser with the default page of the wiki loaded into it.
-To deploy Smeagol as a stand-alone application, compile it with:
 
-    lein bower install
+## Editing
-    lein uberjar
+I generally use [LightTable]() as my `Clojure` editor, but it doesn't really matter what you use; if you run Smeagol as described above, then all changes you make in the code (and save) will instantly be applied to the running system. This makes for a productive development environment.
 
-This will create a jar file in the `target` directory, named `smeagol-`*VERSION*`-standalone.jar`. 
+## Documentation
+It is my intention that the code should be sufficiently well documented to be easy to understand. Documentation may be generated from the code by running
 
-Smeagol cannot access either its configuration or its content from the jar file. Consequently you should set up two environment variables:
+    lein codox
 
-1. **SMEAGOL_CONFIG** should be the full or relative pathname of a Smeagol [[Configuration]] file;
+## Contributing
-2. **SMEAGOL_CONTENT_DIR** should be the full or relative pathname of the directory from which Smeagol should serve content (which may initially be empty, but must be writable by the process which runs Smeagol)'
+If you make changes to Smeagol which you think are useful, please contribute them in the form of a [pull request on github](https://help.github.com/articles/creating-a-pull-request/).
-
-You can run the jar file with:
-
-    java -jar smeagol-VERSION-standalone.jar
-		
-**NOTE** that there are still problems with deploying a jar file: although I do intend to support this, it does not yet work. Outstanding problems are the password file and the internationalisation files. The password file must certainly be outside the jar file, but it seems to me the internationalisation files should not need to be.
-
-Alternatively, if you want to deploy to a servlet container (which I would strongly recommend), the simplest thing is to run:
-
-    lein bower install
-    lein ring uberwar
-
-(a command which I'm sure Smeagol would entirely appreciate) and deploy the resulting war file. **NOTE** that if your Servlet container is configured to unpack war files you do not need to supply the environment variables specified above, but if it does not you must do so.
-
-## Experimental Docker image
-
-You can now run Smeagol as a [Docker](http://www.docker.com) image. Read more about [[Using the Docker Image]].
-
-To run my Docker image, use
-
-    docker run simonbrooke/smeagol
-
-Smeagol will run, obviously, on the IP address of your Docker image, on port 8080. To find the IP address, start the image using the command above and then use
-
-    docker inspect --format '{{ .NetworkSettings.IPAddress }}' $(docker ps -q)
-
-Suppose this prints '10.10.10.10', then the URL to browse to will be http://10.10.10.10:8080/smeagol/
-
-This image is _experimental_, but it does seem to work fairly well. What it does **not** yet do, however, is push the git repository to a remote location, so when you tear the Docker image down your edits will be lost. My next objective for this image is for it to have a cammand line parameter being the git address of a repository from which it can initialise the Wiki content, and to which it will periodically push local changes to the Wiki content.
-
-To build your own Docker image, run:
-
-    lein clean
-    lein bower install
-    lein ring uberwar
-    lein docker build
-
-This will build a new Docker image locally; you can, obviously, push it to your own Docker repository if you wish.

resources/public/content/Introduction.md

@@ -23,7 +23,7 @@ You can (if you're logged in) upload files, including images, using the **Upload
 ![Smeagol](http://vignette3.wikia.nocookie.net/lotr/images/e/e1/Gollum_Render.png/revision/latest?cb=20141218075509)
 
 ## Running Smeagol
-You can run Smeagol from the [[Docker Image]]; alternatively you can run it from an executable jar file or as a war file in a servlet container. Read how in [[Developing Smeagol]].
+You can run Smeagol from the [[Docker Image]]; alternatively you can run it from an executable jar file or as a war file in a servlet container. Read how in [[Deploying Smeagol]].
 
 ## Developing Smeagol
 Smeagol is an open source project; you're entitled to make changes yourself. Read more about [[Developing Smeagol]].

resources/public/content/Security and authentication.md

@@ -1,6 +1,18 @@
-Security is now greatly improved. There is a file called *passwd* in the *resources* directory, which contains a clojure map which maps usernames to maps with plain-text passwords and emails thus:
+Security is now greatly improved over earlier releases of Smeagol. There is a file called `passwd` which by default is in the `resources` directory, which contains a [`Clojure` map](https://clojure.org/reference/data_structures#Maps) which maps usernames to maps with plain-text passwords and emails thus:
 
     {:admin {:password "admin" :email "admin@localhost" :admin true}
      :adam {:password "secret" :email "adam@localhost"}}
 
-that is to say, the username is a keyword and the corresponding password is a string. However, since version 0.5.0, users can now change their own passwords, and when the user changes their password their new password is encrypted using the [scrypt](http://www.tarsnap.com/scrypt.html) one-way encryption scheme. The password file is now no longer either in the *resources/public* directory so cannot be downloaded through the browser, nor in the git archive to which the Wiki content is stored, so that even if that git archive is remotely clonable an attacker cannot get the password file that way.
+that is to say, the username is a keyword and the corresponding password is a string. However, since version 0.5.0, users can now change their own passwords, and when the user changes their password their new password is encrypted using the [scrypt](http://www.tarsnap.com/scrypt.html) one-way encryption scheme. The password file is now no longer either in the `resources/public` directory so cannot be downloaded through the browser, nor in the git archive to which the Wiki content is stored, so that even if that git archive is remotely clonable an attacker cannot get the password file that way.
+
+## Fields in the user record
+Keys and their associated values in the individual user's record are as follows:
+
+* `:password`  The user's password, which can be plain text (if set via the user interface, an encrypted password is stored)
+* `:email`  The user's email address (not currently used; may be used in future for sending password reset messages)
+* `:admin`  If present and set to `true`, the user has access to the user administration functions.
+
+## Maintaining the passwd file outside the Smeagol deployment
+You may set an environment variable, `SMEAGOL_PASSWD`, to indicate a `passwd` file anywhere you like on the file system provided the process running Smeagol can read it; but unless the file is writable by the process which Smeagol runs as you will not be able to administer users through the user interface.
+
+Of course, it is possible to edit the file using a text editor and maintain the list of allowed users in that way.

resources/public/content/_header.md

@@ -1 +1,2 @@
-This is the header. There isn't yet much in it. You could [edit](edit?page=_header) it to provide internal navigation or branding.
+[[Introduction]] | [[User Documentation]] | [[Deploying Smeagol]] | [[Developing Smeagol]] || 
+This is the header. You could [edit](edit?page=_header) it to provide internal navigation or branding.

resources/public/content/_side-bar.md

@@ -1,3 +1,10 @@
-This is the side bar. There's nothing in it yet. You could [edit](edit?page=_side-bar) it to provide internal navigation or branding.
+* [[Introduction]]
+* [[User Documentation]]
+* [[Deploying Smeagol]]
+* [[Developing Smeagol]]
+
+<hr/>
+
+This is the side bar. You could [edit](edit?page=_side-bar) it to provide internal navigation or branding.
 
 If you don't like it on the left, float it to the right (or do something entirely different) by editing the [stylesheet](edit-css?page=stylesheet).

resources/public/content/stylesheet.css

@@ -83,6 +83,15 @@ header h1 {
   margin-top: 0;
 }
 
+header a {
+  font-weight: bold;
+  color: white;
+}
+
+header a:hover {
+  color: darkgray;
+}
+
 img {
   border: 0;
   padding: 0;

resources/templates/edit.html

@@ -22,6 +22,22 @@
             </form>
         </div>
         <script>
-          var simplemde = new SimpleMDE();
+          var simplemde = new SimpleMDE({
+            autosave: {
+              enabled: true,
+              uniqueId: "Smeagol-{{page}}",
+              delay: 1000,
+            },
+            indentWithTabs: true,
+            insertTexts: {
+              horizontalRule: ["", "\n\n-----\n\n"],
+              image: ["![](http://", ")"],
+              link: ["[", "](http://)"],
+              table: ["", "\n\n| Column 1 | Column 2 | Column 3 |\n| -------- | -------- | -------- |\n| Text     | Text      | Text     |\n\n"],
+            },
+            showIcons: ["code"], //, "table"], - sadly, markdown-clj does not support tables
+	          spellChecker: true,
+	          status: ["autosave", "lines", "words", "cursor"]
+          });
         </script>
 {% endblock %}