[dia/neduard/update_dev_docs: 13/17] #30 Move what was in README to HACKING & Update README.

[Eduard <neduard src gnome org>]

commit 65abece69b0cbca6dfb66ff5099f3b3c05728379
Author: Eduard Nicodei <eddnicodei gmail com>
Date:   Wed Jan 30 15:06:23 2019 +0000

    #30 Move what was in README to HACKING & Update README.
    
      - Reference https://gitlab.gnome.org/GNOME/dia/issues as main webpage
      - Add contact information: mailing list & IRC
      - Also use markdown for the files.

 HACKING              | 19 ----------
 README => HACKING.md | 97 +++++++++++++++++++++++++---------------------------
 README.md            | 41 ++++++++++++++++++++++
 3 files changed, 88 insertions(+), 69 deletions(-)
---
diff --git a/README b/HACKING.md
similarity index 64%
rename from README
rename to HACKING.md
index e2156d2b..76ee96ea 100644
--- a/README
+++ b/HACKING.md
@@ -1,56 +1,52 @@
-Dia is a program for drawing structured diagrams.
+# Intro
+Feel free to hack away at dia, but you're advised to contact
+the dia maintainers and/or the mailing list if you do any
+larger work --- this is in everyone's interest so that work is
+not duplicated.
 
-Dia is a GNU program, and is Free Software.  See the COPYING file for
-the licence.
+For more information on the authors, maintainers, etc., of dia,
+please see the file AUTHORS (dynamically generated).
 
-Documentation is a bit sparse at the moment.  Some info can be
-found in the doc/ directory.
+Visit the dia webpage at https://gitlab.gnome.org/GNOME/dia 
+for more information on the dia mailing list and many other
+dia-related things.
 
---
+If you need to alter the list of contributors, documentors,
+etc., the authoritative list is in app/authors.h.
 
-I haven't had time to write anything here yet.
-Read INSTALL for some brief installation instructions.
 
-Homepage for Dia is at:
- https://wiki.gnome.org/Apps/Dia
-
-Some comments about the source:
--------------------------------
-
- Everything on the screen 'inherits' from the structure Object 
+# Some comments about the source
+Everything on the screen 'inherits' from the structure Object
 in lib/object.h. (ps. this is a nice place to start reading the code.).
-Inherits in C means (as in gtk) that it begins with a copy of that structure. 
-Some base classes exists in lib/, like element.h (for doing 'box-like' 
-objects), connection.h (for doing 'line-like' objects), orth_conn.h (for doing 
-connections with orthogonal lines, like the uml-stuff) and render_object.h 
-(for doing picture-like objects). These base classes are then subclassed in 
-the different object in the object-libraries like objects/standard object/UML 
+Inherits in C means (as in gtk) that it begins with a copy of that structure.
+Some base classes exists in lib/, like element.h (for doing 'box-like'
+objects), connection.h (for doing 'line-like' objects), orth_conn.h (for doing
+connections with orthogonal lines, like the uml-stuff) and render_object.h
+(for doing picture-like objects). These base classes are then subclassed in
+the different object in the object-libraries like objects/standard object/UML
 and object/network.
 
- The objects work by filling out two structures that the main program (app/*) 
-uses to handle the objects. The ObjectType structure which consists of some 
-info and a pointer to the type-operations (create+load+save). There's one 
-ObjectType per object type currently loaded. Then the Object structure, there 
-exists a copy of this for each object of the kind on screen (and in 
-copy-buffers). This contains some info like: type, bounding_box, position, 
-handles (the rectangles you move with the mouse) and connections. It also 
-contains a pointer to the object-operations. These are called from the main 
-program when if wants the object to do something. All ops take an Object as 
-the first argument. This is usually casted to the subtype in the function 
-headed (gives all those pita warnings) so that you directly can use the info 
-stored in the subclasses. Most ops are quite self-describing, and the code can 
-be copy-pasted from an object like the one you're doing. Rendering to 
-screen/postscript is done through a 'Renderer' abstraction that can be found 
+The objects work by filling out two structures that the main program (app/*)
+uses to handle the objects. The ObjectType structure which consists of some
+info and a pointer to the type-operations (create+load+save). There's one
+ObjectType per object type currently loaded. Then the Object structure, there
+exists a copy of this for each object of the kind on screen (and in
+copy-buffers). This contains some info like: type, bounding_box, position,
+handles (the rectangles you move with the mouse) and connections. It also
+contains a pointer to the object-operations. These are called from the main
+program when if wants the object to do something. All ops take an Object as
+the first argument. This is usually casted to the subtype in the function
+headed (gives all those pita warnings) so that you directly can use the info
+stored in the subclasses. Most ops are quite self-describing, and the code can
+be copy-pasted from an object like the one you're doing. Rendering to
+screen/postscript is done through a 'Renderer' abstraction that can be found
 in lib/render.h.
- 
-XML based objects:
-------------------
+
+## XML based objects
 You can (from version 0.80) create new objects using a SVG like XML languange.
 The file doc/custom-shapes has more information about this.
- 
-Note on handles and connection points:
---------------------------------------
 
+## Note on handles and connection points:
 An object has handles to resize it. A handle can be moved either because
 the user dragged it with the mouse, or the handle is attached to another
 object, which moved itself. The handles are diplayed as little squares
@@ -72,17 +68,18 @@ the connectionpoint is saved as the index of the connectionpoint. So make
 sure the order of the connectionpoints is the same when loading the saved
 object.
 
-Notes on static analysis
-------------------------
-Some of the recent changes (log message starting with [scan-build] are suggested
-by static source analysis, see http://clang-analyzer.llvm.org/scan-build
+# Notes on static analysis
+Some of the recent changes (log message starting with `scan-build` are suggested
+by static source analysis, see http://clang-analyzer.llvm.org/scan-build )
+
 To use it just run ./configure and make through the scan-build script, like:
 
-PATH=/mnt/Home/from-svn/llvm/Release/bin:$PATH 
/mnt/Home/from-svn/llvm/tools/clang/tools/scan-build/scan-build ./configure --prefix=/opt --enable-debug=yes
-  and
-PATH=/mnt/Home/from-svn/llvm/Release/bin:$PATH 
/mnt/Home/from-svn/llvm/tools/clang/tools/scan-build/scan-build -v -v make -j3
-  view with
-PATH=/mnt/Home/from-svn/llvm/Release/bin:$PATH /mnt/Home/from-svn/llvm/tools/clang/tools/scan-view/scan-view
+```
+export PATH=/mnt/Home/from-svn/llvm/Release/bin:$PATH
+/mnt/Home/from-svn/llvm/tools/clang/tools/scan-build/scan-build ./configure --prefix=/opt --enable-debug=yes
+/mnt/Home/from-svn/llvm/tools/clang/tools/scan-build/scan-build -v -v make -j3
+/mnt/Home/from-svn/llvm/tools/clang/tools/scan-view/scan-view
+```
 
 (given an uninstalled checkout of llvm to /mnt/Home/from-svn/llvm)
 
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..8056b5ab
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# About
+
+Dia is a program for drawing structured diagrams.
+
+Dia is a GNU program, and is Free Software.  See the COPYING file for the licence.
+
+The current homepage for Dia is https://gitlab.gnome.org/GNOME/dia.  This however
+is fairly new and does not contain a lot of background information.  The previous
+homepage was at https://wiki.gnome.org/Apps/Dia.  Over there you will find a lot
+more information about Dia's history, features, screenshots, GSoC ideas, etc.
+Please have a look at both.
+
+General documentation can be found in the [doc/](doc/) directory.
+
+If you are thinking of contributing (either code or diagrams), please see
+[HACKING](HACKING.md).
+
+For compilation and installation instructions please see [INSTALL](INSTALL).
+
+# Bug reporting
+
+Please use the issue tracker on the GitLab page:
+https://gitlab.gnome.org/GNOME/dia/issues
+
+First, have a look at both the existing open & closed issues: maybe somebody has
+noticed the issues as well, or maybe it's included in a new version.
+
+If the issue is not there, please report it.  Otherwise, give it a "thumbs-up".
+This will us prioritise them.
+
+# Contacting us
+
+If you use Dia, we would love to hear from you!
+
+Please feel free to send us comments/feedback/questions on our mailing list:
+https://mail.gnome.org/mailman/listinfo/dia-list
+
+If you don't want to send a full email or just want to say "Hi!", we also hang
+out on IRC on GimpNet [irc.gimp.org](irc://irc.gimp.org) on `#dia-editor`
+channel.  Dia has been inactive for a few years now so it is always nice to hear
+from people (still) using it.