[gtksourceview/wip/lang-ref: 2/2] lang-reference: merge content of Apps/Gedit/NewLanguage wiki page (wip)

[Sébastien Wilmet <swilmet src gnome org>]

commit 3db76aea520af17042bcdd347d976aa6b24f5cb8
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri Mar 6 14:22:19 2015 +0100

    lang-reference: merge content of Apps/Gedit/NewLanguage wiki page (wip)
    
    It's better to have the whole documentation in one place.

 docs/reference/lang-reference.xml |   38 +++++++++++++++++++++++++++++++++++++
 1 files changed, 38 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/lang-reference.xml b/docs/reference/lang-reference.xml
index da419cd..5f10694 100644
--- a/docs/reference/lang-reference.xml
+++ b/docs/reference/lang-reference.xml
@@ -30,6 +30,44 @@ should be installed on your system in the directory
 <filename>${PREFIX}</filename> can be <filename>/usr/</filename> or
 <filename>/usr/local/</filename> if you have installed from source.
 </para>
+
+<para>
+The preinstalled language files are located in
+<filename>${PREFIX}/share/gtksourceview-3.0/language-specs/</filename>. Custom
+user languages are usually placed in
+<filename>~/.local/share/gtksourceview-3.0/language-specs/</filename>. Note:
+replace 3 with 2 in the path for GtkSourceView version 2.
+</para>
+</refsect1>
+
+<refsect1>
+<title>Some advices</title>
+
+<para>
+The easiest way to start a new language definition is to copy a preinstalled
+language definition from a language that has similar constructs as the one you
+want to write a specification for. You can copy and rename a file from the
+systems directory to the local user one (create the directory if it doesn't
+exist yet) and edit the file accordingly.
+</para>
+
+<para>
+The important thing you need to change are the <code>id</code> and
+<code>name</code> of the language and the metadata properties
+<code>mimetypes</code> and <code>globs</code> in the language spec. These
+should resemble your new language. It might be that your files do not have an
+appropriate mimetype associated yet. You can either in that case leave it
+empty, or add a new mimetype (see below).
+</para>
+
+<para>
+If for some reason your language spec doesn't show up in an application like
+gedit, it might be a good idea to start the application from a terminal window
+and see if any errors/warnings appear for your language file. This usually
+gives good clues what's wrong with the specification. Note that you need to
+restart the application to take into account changes in a language definition
+file.
+</para>
 </refsect1>
 
 <refsect1>