Update erlide.org docs (erlang#354)

Update user and developer documentation,
including some backporting of missing changes
only available in the `erlide/erlide.github.io` repo.

Makefile

@@ -1,7 +1,21 @@
-.PHONY: build deploy
+.PHONY: build publish publish-docs
+
+DOCS_REPO?=erlide/erlide.github.io
+DOCS_DIR=plugins/org.erlide.help/target/$(DOCS_REPO)
 
 build:
 	./mvnw -B -U enforcer:display-info clean verify -Phelp
 
-deploy:
+# Publish a release to update site https://erlide.org/update/
+publish:
 	./mvnw -B -U deploy -P help,release-composite
+
+# Publish documentation to https://erlide.org
+publish-docs:
+	rm -rf $(DOCS_DIR)
+	git clone --depth 1 [email protected]:$(DOCS_REPO) -b master $(DOCS_DIR)
+	cp -r plugins/org.erlide.help/articles/* $(DOCS_DIR)/articles/
+	cd $(DOCS_DIR) && \
+		git add . && \
+		git commit -a -m 'Publish erlide_eclipse docs' && \
+		git push origin master

plugins/org.erlide.help/articles/eclipse/110_Features.md

@@ -4,7 +4,7 @@ title: Features
 part: Getting started
 ---
 
-# Features 
+# Features
 
 ## Wizards
 
@@ -40,7 +40,7 @@ function call
 * Automatic completion of erlang modules, functions and records:
 **Ctrl+Space**. The list with proposals is also shown when entering **:**
 (colon).
-* Go to declaration of function, macro or record: F3 when the cursor is
+* Go to declaration of function, macro or record: **F3** when the cursor is
 inside that element's name.
 * Show declaration of macros and records as a hover window
 * Bracket matching: the peer of the bracket at the cursor is highlighted.
@@ -50,8 +50,8 @@ inside that element's name.
 ## Builder
 
 
-Building is automatic whenever a file is saved (if `Project -> Build`
-automatically is enabled) and the modified module is also reloaded in any
+Building is automatic whenever a file is saved (if `Project -> Build
+automatically` is enabled) and the modified module is also reloaded in any
 Erlang backend that is linked to that project.
 
 ## Outline view
@@ -103,7 +103,7 @@ shown in a hover window, when the mouse cursor is above a function call.
 
 The OTP documentation is shown, if installed on your system. Also, if the
 project contains HTML documentation that is located in an OTP-like location
-(i.e. in a `doc/html` directory in the project ), then this documentation is
+(i.e. in a `doc/html` directory in the project), then this documentation is
 also shown.
 
 ## Debugger

plugins/org.erlide.help/articles/eclipse/120_Installing-and-updating.md

@@ -6,8 +6,8 @@ part: Getting started
 
 # Installing and updating
 
-* Install Erlang __R23__ or later, if it isn't already present on your system. On Windows systems, use a path with no spaces in it.
-* Install Eclipse. We target primarily version __4.8__, later versions work just as well. __Java 8__ is required.
+* Install a supported Erlang version like __Erlang/OTP 23__, if it isn't already present on your system. On Windows systems, use a path with no spaces in it.
+* Install Eclipse. __Java 8__ is required.
 * If your network uses a proxy to connect to the internet, fill in the appropriate data in `Window -> Preferences -> Install/Update -> Proxy settings`
 * Install Erlide by going to `Help -> Software Updates -> Find` and `Install... -> Search for new features to install`.
 * In the dialog, choose New remote site and enter `Erlide` as name and `https://erlide.org/update` as URL.

plugins/org.erlide.help/articles/eclipse/140_Tutorial-Quick-Start.md

@@ -10,31 +10,31 @@ part: Getting started
 1. Start eclipse
 2. If it prompts you to choose workspace, select the folder you want to work in. For this tutorial you might want to use a fresh one.
 3. On the menu bar, Choose `Help -> Software Updates...`
-4. Select the Installed Software tab. If "Erlang IDE" appears under name, then go to 17.
+4. Select the Installed Software tab. If "Erlang IDE" appears under name, then go to [17](#17).
 5. Select the Available Software tab.
 6. Click the `Add Site...` button on the right.
-7. In the Location field, enter `http://erlide.org/update`
+7. In the Location field, enter `https://erlide.org/update`
 8. Click OK
-9. Check the box left of http://erlide.org/update
+9. Check the box left of https://erlide.org/update
 10. Check the box left of Unstable builds
 11. Click the `Install...` button on the right
 12. When the Install dialog pops, click on the Next button
 13. Accept the terms of the license agreement.
 14. Click Finish.
 15. Click Yes to restart.
-16. Go to 20 below
-17. Select (click on) Erlang IDE
+16. Go to step [20](#20) below
+17. <a name="17"/> Select (click on) Erlang IDE
 18. Click on the Update button on the right
 19. Follow the directions to update and restart Eclipse.
-20. Click on the Workbench icon on the right side of the main eclipse window
-21. On menu bar, choose `Windows -> Preferences -> Erlang -> Install runtimes`
-22. See if there is a runtime listed in the drop down field called Runtime used by Erlide itself (restart is required). If there is something there, hit Cancel and go on to [28](#5).
+20. <a name="20"/> Click on the Workbench icon on the right side of the main Eclipse window
+21. On menu bar, choose `Windows -> Preferences -> Erlang -> Installed runtimes`
+22. See if there is a runtime indicated to be used by Erlide itself (restart is required). If there is something there, hit Cancel and go on to [28](#28).
 23. Click on the Add... button.
-24. In the Runtime name field, enter `erl5.6.4`.
-25. In the Location field, browse to the very top level folder of the Erlang tree. This should be a folder called "erl5.6.4" or something like that.
-26. Click OK. Then Click Apply and OK in the Install runtimes pane.
+24. In the Runtime name field, enter `23.3`.
+25. In the Location field, browse to the very top level folder of the Erlang tree. This should be a folder called "erl23xs" or something like that.
+26. Click OK. Then Click Apply and OK in the `Installed runtimes` pane.
 27. On menu bar, choose `File -> Restart`
-28. <a name="5"/> On menu bar, chose `Windows -> Open Perspective -> Other... -> Erlang`. Click OK.
+28. <a name="28"/> On menu bar, chose `Windows -> Open Perspective -> Other... -> Erlang`. Click OK.
 29. On menu bar, chose `File -> New -> Project...`
 30. In wizard, chose `Erlang -> Erlang Project` and click Next
 31. In Project name field, type `HelloWorldProject`
@@ -47,10 +47,10 @@ part: Getting started
 38. Select the "Erlang application"
 39. Click the New Launch configuration button (left side above the field with "type filter text")
 40. Select the "New configuration"
-41. Select the "Main tab" in the right pane
+41. Select the "Erlang" tab in the right pane
 42. Check the box left of the HelloWorldProject
-43. Select the "Runtimes" tab in the right pane
-44. In the filed titled Node name, enter `erlide`
+43. Select the "Runtime" tab in the right pane
+44. In the field titled Node name, enter `erlide`
 45. In some environments, Java and Erlang look for the default `.erlang.cookie` file in different places, and if you get connection problems you should enter some value for the Cookie field. If the node is already running, you have to use the same cookie value; otherwise, any string will do.
 46. Check the box to the left of "Start the Erlang node if not running presently"
 47. Click "Apply" and "Run"
@@ -65,4 +65,4 @@ part: Getting started
 53. Click OK. The file `hello.erl` is saved in the src directory and automatically built.
 54. The lower pane has a number of tabs. Select the "Console" tab.
 55. In the console pane, enter the following command `hello:hello().` and hit return. The output from the program will appear.
-56. To exit, in the menu bar, choose `File -> Close`, and then `File -> Exit`
+56. To exit, in the menu bar, choose `File -> Close`, and then `File -> Exit`.

plugins/org.erlide.help/articles/eclipse/150_Tutorial-Hello-World.md

@@ -11,12 +11,16 @@ title: "Tutorial: Hello, world!"
 ## Install Erlang/OTP (if you have not already)
 
 * _Ubuntu Linux_: run the following in Terminal:
-        sudo apt-get update
-        sudo apt-get install erlang
+  ```shell
+  sudo apt-get update
+  sudo apt-get install erlang
+  ```
 * _Windows_: run the Windows Installer for Erlang
 * _Mac OS X_: install MacPorts and then run the following in Terminal:
-        sudo port selfupdate
-        sudo port install erlang
+  ```shell
+  sudo port selfupdate
+  sudo port install erlang
+  ```
 
 ## Install Eclipse and ErlIDE
 
@@ -26,9 +30,9 @@ title: "Tutorial: Hello, world!"
 or Eclipse (Mac) in the eclipse folder
   4. Select Help (menu) -> Software Updates... (a dialog will appear)
   5. Click Add Site...(another dialog will appear)
-  6. Enter http://erlide.erlide.org/update into the Location field, then
+  6. Enter `https://erlide.org/update` into the Location field, then
 click OK (dialog will close)
-  7. Select the checkbox by `http://erlide.org/update` and click
+  7. Select the checkbox by `https://erlide.org/update` and click
 Install... (another dialog will appear)
   8. Select Next
   9. Select I accept ... radio button and click Finish (a progress dialog will

plugins/org.erlide.help/articles/eclipse/170_FAQ.md

@@ -11,7 +11,7 @@ part: Getting started
 ## I can't write comments or strings in Chinese (or other non-latin language)!
 <a name='faq1'/>
 
-This has been fixed for R1603+. We use the right default encoding according to the runtima and we detect the `coding` comments at the top of a file and use the right encoding for it. There might be issues if you have multiple projects in the workspace targeting different Erlang versions, use `coding` to fix them.
+We use the right default encoding according to the runtime and we detect the [`coding`](https://www.erlang.org/doc/reference_manual/character_set.html#source-file-encoding) comments at the top of a file and use the right encoding for it.
 
 [Top](170_FAQ.html)
 

plugins/org.erlide.help/articles/eclipse/220_Creating-a-project.md

@@ -8,12 +8,12 @@ part: Reference
 
 To create a project:
 
-1. Click File -> New -> Other... -> Erlang Project or use the context menu
-in the navigator, right-clicking and choosing New -> Erlang Project
+1. Click `File -> New -> Other... -> Erlang Project` or use the context menu
+in the navigator, right-clicking and choosing `New -> Erlang Project`.
 
   ![File menu](images/file_menu.png){: .frame }
 
-2. In the New Erlang Project wizard, enter the project name and if needed
+2. In the `New Erlang Project` wizard, enter the project name and if needed
 choose the project's desired location. If you already have code in that location, it will be recognized and imported.
 
   !['New Project' wizard](images/new_project_wizard.png){: .frame }

plugins/org.erlide.help/articles/eclipse/cover/410_Cover-plugin.md

@@ -7,9 +7,9 @@ part: Cover plugin
 
 Cover plugin is an integration of Erlang cover tool with ErlIde. It provides a friendly graphical user interface that helps configuring and viewing coverage analysis for your project. That is how it simplifies a process of testing Erlang projects developed with ErlIde.
 
-To learn more about cover click the following link [http://www.erlang.org/doc/apps/tools/cover_chapter.html](http://www.erlang.org/doc/apps/tools/cover_chapter.html). Cover reference manual can be found here [http://www.erlang.org/doc/man/cover.html](http://www.erlang.org/doc/man/cover.html).
+To learn more about cover click the following link [https://www.erlang.org/doc/apps/tools/cover_chapter.html](https://www.erlang.org/doc/apps/tools/cover_chapter.html). Cover reference manual can be found here [https://www.erlang.org/doc/man/cover.html](https://www.erlang.org/doc/man/cover.html).
 
-Cover plugin was developed as a part of [ProTest project ]( http://www.protest-project.eu/)  by [Erlang Solutions ]( http://www.erlang-solutions.com/) .
+Cover plugin was developed as a part of [ProTest project ](https://www.protest-project.eu/)  by [Erlang Solutions ](https://www.erlang-solutions.com/) .
 
 ## Features
 *  Providing coverage statistics (coverage ratio per function, module, source folder, project) 
@@ -28,8 +28,3 @@ If you want to understand the source code go [here](430_Cover-plugin-implementat
 ## Examples
 
 You can find examples how to use this plugin [here](420_Cover-plugin-example.html)
-
-
-
-
-

plugins/org.erlide.help/articles/eclipse/developer/310_Tools-and-requirements.md

@@ -11,17 +11,17 @@ title: Tools and requirements
 * The issue manager is at <https://github.com/erlang/erlide_eclipse/issues>.
 * It would be highly recommended to have some background with Java and Eclipse development, the learning curve can be quite steep. You probably won't start by implementing a new plug-in from scratch, but it helps to know how things are working and where to look. Some suggestions for tutorials/articles/books:
   * the eclipse documentation, of course
-  * <http://www.vogella.com/articles/EclipsePlugIn/article.html>
-  * <http://www.amazon.com/Eclipse-Plug-ins-Edition-Eric-Clayberg/dp/0321553462>
+  * <https://www.vogella.com/articles/EclipsePlugIn/article.html>
+  * <https://www.amazon.com/Eclipse-Plug-ins-Edition-Eric-Clayberg/dp/0321553462>
 
 ## Tools
 
-* Download and install Eclipse 4.4, which will serve as a target for development.
+* Download and install Eclipse 4.4 or later, which will serve as a target for development.
 * You can use Eclipse 4.4 for development too, but the newer Java tools are much better. I always the latest Eclipse for developing.
-* The debugger support code has different projects for R15, R16, 17 and 18, due to changes to the compiler and/or runtime. You need all these versions installed if you make changes to the debugger.
+* The debugger support code has different projects for each supported OTP version. When building erlide the tool `kerl` will be downloaded and install required OTP versions to `~/erlide_tools/`.
 * In your development Eclipse, install a Java 1.8 JDK and the _EGit_, _Erlide_ and _Xtend_ plugins.
 * Other recommended plugins: AnyEdit.
-* A note about using more recent versions of Java/Eclipse/Erlang: they should work, but if the target is not 1.8/4.4/R16B, then you might use things that are not available in the base configuration or have changed since and then there will be errors (at compile-time or run-time).
+* A note about using more recent versions of Java/Eclipse/Erlang: they should work, but if the target is not 1.8/4.4/23, then you might use things that are not available in the base configuration or have changed since and then there will be errors (at compile-time or run-time).
 
 ## Setup
 

plugins/org.erlide.help/articles/eclipse/developer/320_Accessing-the-code.md

@@ -9,9 +9,9 @@ Well, if you made it to this wiki, you probably know how to fork the code reposi
 
 > **Important note:** There is no stable API yet, this is the reason why the version number is still starting with a zero. We are currently working at creating an API, but we prioritize regular development (unless you, the would-be extenders, will start asking for the API)
 
-## Working on the core erlide 
+## Working on the core erlide
 
-The "core erlide" is the basic erlide functionality. There are two eclipse feature projects for it, `org.erlide.headless` and `org.erlide`. The headless part is needed so that we can use erlide to compiler Erlang projects in Eclipse without having to start the UI (with Buckminster, we use it to build erlide itself).
+The "core erlide" is the basic erlide functionality. There are two eclipse feature projects for it, `org.erlide.headless` and `org.erlide`. The headless part is needed so that we can use erlide to compile Erlang projects in Eclipse without having to start the UI.
 
 ### Project descriptions
 

plugins/org.erlide.help/articles/eclipse/developer/330_Branches.md

@@ -7,60 +7,24 @@ part: Developer's guide
 
 See also [Release process](3d0_Release-process.html) for details about the release process.
 
-## Main branches
-
-The branches from the main erlide repository.
-
-### `master`
-
-This branch points to the latest stable released version of erlide. It
-will never be rebased.
+The `master` branch points to the latest changes that will be included in the next release.
+It will never be rebased.
 
 All new feature branches should be branched from `master`.
 
-### `pu`
-
-This is the current development branch. It includes all fixes and new
-features that we plan to include in the next release.
-
-Here we gather all the proposed updates, so that they can be tested and
-evaluated before they are include in `master`. It may be rebased, don’t
-base any topic branches on it unless you need fixes/features that aren’t
-present in `master` yet.
-
-### `release`
-
-This is a temporary branch that is used to prepare a release. It is then
-merged into `master` and deleted.
-
-## Local bugfix branches
-
-These branches are those in your repository where the work is done and
-where the result can be merged into the main branches.
-
-Branches that fix a bug that has an issue on the ticket tracker should
-have a name that starts with that bug’s id and an underscore. We would
-like that the rest of the name describes the issue. This helps a lot
-with having updated changelogs.
-
 ## Working on erlide
 
 Creating new feature for erlide usually means that you will spend some
 time working on it. When your job is done you will have to ask to merge
 it into erlide’s repository. So here is how you should start:
 
-- Branch from `next`. See above for when it is a good idea to use `pu`
-instead.
+- Branch from `master`.
 - Develop your feature in your own branch
 - Send a pull request and we will review it
 - Delete your branch when the branch is merged
 
 While developing your feature you should keep up-to-date with erlide’s
 code (there maybe some changes which will impact your code or make it
-very difficult to merge into `pu` when your work is done). This can be
-done by merging `master` or `next`. Please don’t merge `pu` repeatedly,
-as it may get rebased. Merging `pu` (or rebasing on top of it) should be
-done only when you are done with your feature and want to make sure the
-merge to upstream will be painless (for which I will be very grateful!).
+very difficult to merge when your work is done).
 
 The same workflow applies for bugfixes too.

plugins/org.erlide.help/articles/eclipse/developer/340_Submitting-patches.md

@@ -23,10 +23,6 @@ Create a new branch starting from `master`. Each branch should contain
 logically related commits (for example the implementation of a single
 feature), not a mixed bag of random changes.
 
-If your change is depending on some other fix or feature that is not in
-`master` yet, you may start from `next`, but be aware that there is a
-small risk that the branch will be rebased.
-
 Committing the patch
 --------------------
 
@@ -77,7 +73,7 @@ When we receive your patch, we will do one of the following:
     providing more information in the commit message instead of in the
     email), we may ask you to do that.
 -   Otherwise, if your patch is not obviously wrong or inappropriate, we
-    will merge it to the `pu` (“proposed updates”) branch.
+    will merge it.
 -   Otherwise, if it is obviously wrong or inappropriate, we will tell
     you so. Reasons for immediate rejections include (but are not
     limited to):
@@ -89,26 +85,6 @@ When we receive your patch, we will do one of the following:
     separate the changes into separate commits and/or branches and not
     change indentation of unchanged code.
 
-You should **not** base any branches on `pu` branch, as it will be
-rewinded (rebuilt from scratch) frequently.
-
-Cooking
--------
-
-Patches will “cook” in the `pu` branch until they graduate or are
-dropped.
-
-The following may happen to a patch (one or more times):
-
--   If build problems are found or there are many failing test cases not
-    found before it was been included in `pu`, it may be removed from
-    `pu` until the problems have been fixed.
--   Anyone can criticize, suggest improvements, or report that a patch
-    breaks existing applications. If the serious problems remain, and no
-    good way of fixing them can be found, the patch may be dropped.
--   Patches with known issues that have been inactive for a long time
-    (several months) will be dropped.
-
 > This page is adapted from the similar page from the erlang/otp wiki,
 > but any errors are entirely ours.
 

plugins/org.erlide.help/articles/eclipse/developer/350_Git-Tools-and-Hacks.md

@@ -24,5 +24,5 @@ Which means if you have this version of git or newer when you checkout, all of t
 
 ## Shell Prompt
 
-See this [guide](http://github.com/guides/put-your-git-branch-name-in-your-shell-prompt) to make git repo information show in your shell prompt.
+See this [guide](https://github.com/guides/put-your-git-branch-name-in-your-shell-prompt) to make git repo information show in your shell prompt.