Reformat HACKING as true reStructuredText.

Add 'make hacking-doc' target to generate hacking.html.


git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@3029 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -1,3 +1,10 @@
+2008-10-01  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
+
+ * HACKING, doc/Makefile.am:
+   Reformat HACKING as true reStructuredText.
+   Add 'make hacking-doc' target to generate hacking.html.
+
+
 2008-09-30  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>
 
  * src/project.c:

HACKING

@@ -1,23 +1,33 @@
+=============
+Hacking Geany
+=============
+.. contents::
+
+General
+=======
+
 About this file
 ---------------
 This file contains information for anyone wanting to work on the Geany
 codebase. You should be aware of the open source licenses used - see
-the README file or the documentation. It is pseudo-reStructuredText.
+the README file or the documentation. It is reStructuredText; the
+source file is HACKING. You can generate hacking.html by running ``make
+hacking-doc`` from the doc/ subdirectory.
 
 Writing plugins
 ---------------
-You should generate and read the plugin API documentation, see below.
+* src/plugindata.h contains the plugin API data types.
+* See plugins/demoplugin.c for a very basic example plugin.
+* src/plugins.c loads and unloads plugins (you shouldn't need to read
+  this really).
 
-src/plugindata.h contains the plugin API data types and some notes.
+You should generate and read the plugin API documentation, see below.
-See plugins/demoplugin.c for a very basic example plugin.
-src/plugins.c loads and unloads plugins (you shouldn't need to read
-this really).
 
 Plugin API documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^
 You can generate documentation for the plugin API using the doxygen
-tool. Run 'make api-doc' in the doc subdirectory. The documentation will
+tool. Run ``make api-doc`` in the doc subdirectory. The documentation
-be output to doc/reference/index.html.
+will be output to doc/reference/index.html.
 
 Patches
 -------
@@ -26,11 +36,13 @@ or mailing list whether a new feature is appropriate, and whether someone
 is already working on similar code.
 
 In general it's best to work from the current SVN, but we accept patches
-against other releases.
+against other releases::
-$ svn diff > fix-some-bug.patch
 
-If you're not using SVN, you can use the diff command:
+	$ svn diff > fix-some-bug.patch
-$ diff -u originalpath modifiedpath > new-feature.patch
+
+If you're not using SVN, you can use the diff command::
+
+	$ diff -u originalpath modifiedpath > new-feature.patch
 
 Please make sure patches follow the style of existing code - In
 particular, use tabs for indentation. See `Style`_ and `Coding`_.
@@ -44,30 +56,33 @@ File organization
 -----------------
 callbacks.c is just for Glade callbacks.
 Avoid adding code to geany.h if it will fit better elsewhere.
-See the top of each src/*.c file for a brief description of what it's for.
+See the top of each ``src/*.c`` file for a brief description of what
+it's for.
 
 Keeping the plugin ABI stable
 -----------------------------
 Please be aware that anything with a doc-comment (a comment with an
-extra asterix: '/**') is something in the plugin API. Things like enums
+extra asterix: ``/**``) is something in the plugin API. Things like
-and structs can usually still be appended to, ensuring that all the
+enums and structs can usually still be appended to, ensuring that all
-existing elements stay in place - this will keep the ABI stable.
+the existing elements stay in place - this will keep the ABI stable.
 
-Note: Some structs like KeyBindingGroup and GeanyCallback cannot be
+.. warning::
-appended to without breaking the ABI because they are used to declare
+
-structs by plugins, not just for accessing struct members through
+	Some structs like GeanyKeyGroup and GeanyCallback cannot be
-a pointer.
+	appended to without breaking the ABI because they are used to declare
+	structs by plugins, not just for accessing struct members through
+	a pointer.
 
 Before the 1.0 release series, the ABI can change when necessary, and
 even the API can change. An ABI change just means that all plugins will
-not load and they must be rebuilt.  An API change means that some plugins
+not load and they must be rebuilt. An API change means that some plugins
 might not build correctly.
 
-When reordering or changing existing elements of structs that are used as
+When reordering or changing existing elements of structs that are
-part of the plugin API, you should increment abi_version in plugindata.h.
+used as part of the plugin API, you should increment GEANY_ABI_VERSION
-This is not needed if you're just appending fields to structs. The
+in plugindata.h. This is usually not needed if you're just appending
-api_version value should be incremented for any changes to the plugin API,
+fields to structs. The GEANY_API_VERSION value should be incremented
-including appending elements.
+for any changes to the plugin API, including appending elements.
 
 If you're in any doubt when making changes to plugin API code, just ask us.
 
@@ -99,36 +114,38 @@ against GTK 2.6.
 
 Coding
 ------
-Don't write long functions with a lot of variables and/or scopes - break
+* Don't write long functions with a lot of variables and/or scopes - break
-them down into smaller static functions where possible. This makes code
+  them down into smaller static functions where possible. This makes code
-much easier to read and maintain.
+  much easier to read and maintain.
-Use GLib types and functions - e.g. g_free instead of free.
+* Use GLib types and functions - e.g. g_free instead of free.
-Your code should build against GLib 2.6 and GTK 2.6. At least for the
+* Your code should build against GLib 2.6 and GTK 2.6. At least for the
-moment, we want to keep the minimum requirement for GTK at 2.6 (of
+  moment, we want to keep the minimum requirement for GTK at 2.6 (of
-course, you can use the GTK_CHECK_VERSION macro to protect code using
+  course, you can use the GTK_CHECK_VERSION macro to protect code using
-later versions).
+  later versions).
-We currently try to support the old GCC 2.9.x compiler,
+* We currently try to support the old GCC 2.9.x compiler,
-so we always declare variables before statements. You can use
+  so we always declare variables before statements. You can use
--Wdeclaration-after-statement in your ./configure CFLAGS to warn about
+  -Wdeclaration-after-statement in your ./configure CFLAGS to warn about
-this.
+  this.
-You should also try to write ISO C90 code for portability, so always
+* You should also try to write ISO C90 code for portability, so always
-use C /* */ comments and function_name(void) instead of function_name().
+  use C ``/* */`` comments and function_name(void) instead of
-This is for compatibility with various Unix-like compilers. You can use
+  function_name().  This is for compatibility with various Unix-like
--ansi in your CFLAGS to help check this.
+  compilers. You can use -ansi in your CFLAGS to help check this.
 
 Style
 -----
-We use a tab width of 4 and indent completely with tabs not spaces.
+* We use a tab width of 4 and indent completely with tabs not spaces.
-Use the multiline comment /* */ to comment small blocks of code,
+* Use the multiline comment ``/* */`` to comment small blocks of code,
-functions descriptions or longer explanations of code, etc. C++ single
+  functions descriptions or longer explanations of code, etc. C++ single
-line comments will cause portability issues. The more comments are in
+  line comments will cause portability issues. The more comments are in
-your code the better.
+  your code the better.
-Lines should not be longer than about 100 characters and after 100
+* Lines should not be longer than about 100 characters and after 100
-characters the lines should be wrapped and more indented than the first
+  characters the lines should be wrapped and more indented than the first
-line to highlight that the line is continued. We avoid putting spaces
+  line to highlight that the line is continued.
-between function names and the opening brace for argument lists. Try to
+* We don't put spaces between function names and the opening brace for
-fit in with the existing code brace indenting style, comments, operator
+  argument lists.
-spacing etc. It's not required but it makes our lives easier ;-)
+* Try to fit in with the existing code brace indenting style, comments,
+  operator spacing etc. It's not required but it makes our lives easier
+  ;-)
 
 Libraries
 ---------
@@ -142,10 +159,10 @@ before Geany was started. It's source code parsing is mostly taken from
 Exuberant CTags (see http://ctags.sf.net).
 
 
-NOTES
+Notes
 =====
 Some of these notes below are brief (or maybe incomplete) - please
-contact the mailing list for more information.
+contact the geany-devel mailing list for more information.
 
 Using pre-defined autotools values
 ----------------------------------
@@ -159,21 +176,22 @@ printf("Prefix: %s", GEANY_PREFIX);
 
 Adding a source file foo.[hc] in src/ or plugins/
 -------------------------------------------------
-Add foo.c, foo.h to SRCS in path/Makefile.am.
+* Add foo.c, foo.h to SRCS in path/Makefile.am.
-Add foo.o to OBJS in path/makefile.win32.
+* Add foo.o to OBJS in path/makefile.win32.
-Add path/foo.c to po/POTFILES.in (for string translation).
+* Add path/foo.c to po/POTFILES.in (for string translation).
 
 Adding a filetype
 -----------------
 You can add a filetype without syntax highlighting or tag parsing, but
 check to see if those features have been written in other projects first.
 
-Add GEANY_FILETYPES_FOO to filetypes.h.
+* Add GEANY_FILETYPES_FOO to filetypes.h.
-Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
+* Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
-filetypes.c.
+  filetypes.c.
-Rebuild Geany.
+* Rebuild Geany.
-From your geany/ directory, run:
+* From your geany/ directory, run::
-src/geany --generate-data-files
+
+	src/geany --generate-data-files
 
 (The src/ prefix may be different, depending on where the binary is
 generated.)
@@ -188,9 +206,10 @@ All languages need a data/filetypes.foo configuration file. See
 data/filetypes.c for an example.
 
 Programming languages should have:
-[keywords] if the lexer supports it.
+
-[settings] mostly for comment settings.
+* [keywords] if the lexer supports it.
-[build_settings] for commands to run.
+* [settings] mostly for comment settings.
+* [build_settings] for commands to run.
 
 For languages with a Scintilla lexer, there should be a [styling] section,
 to correspond to the styles used in styleset_foo() in highlighting.c -
@@ -202,23 +221,23 @@ It may be possible to use an existing Scintilla lexer in the scintilla/
 subdirectory - if not, you will need to find (or write) one,
 LexFoo.cxx. Try the Scintilla project first. When adding a lexer, update:
 
- * scintilla/Makefile.am
+* scintilla/Makefile.am
- * scintilla/makefile.win32
+* scintilla/makefile.win32
- * scintilla/KeyWords.cxx - add a LINK_LEXER command *manually*
+* scintilla/KeyWords.cxx - add a LINK_LEXER command *manually*
 
 For syntax highlighting, you will need to edit highlighting.c and add
 the following things:
 
 1. Write styleset_foo_init() to setup default styles and load style
-settings from the filetypes.foo configuration file. You should probably
+   settings from the filetypes.foo configuration file. You should probably
-start by copying and adapting another filetype's initialization, such
+   start by copying and adapting another filetype's initialization, such
-as styleset_asm_init().
+   as styleset_asm_init().
 2. Write styleset_foo() to apply styles when a new scintilla widget
-is created. Again you could copy and adapt a function like styleset_asm().
+   is created. Again you could copy and adapt a function like styleset_asm().
-3. Add this in highlighting_init_styles():
+3. In highlighting_init_styles(), add
-init_styleset_case(GEANY_FILETYPES_FOO, foo);
+   ``init_styleset_case(GEANY_FILETYPES_FOO, foo);``.
-4. Add this in highlighting_set_styles():
+4. In highlighting_set_styles(), add
-styleset_case(GEANY_FILETYPES_FOO, foo);
+   ``styleset_case(GEANY_FILETYPES_FOO, foo);``.
 
 Please try to make your styles fit in with the other filetypes' default
 colors.
@@ -256,9 +275,9 @@ http://sf.net/projects/ctags - see the tracker.
 
 (You can also try the Anjuta project's tagmanager codebase.)
 
-Add foo.c to SRCS in Makefile.am.
+* Add foo.c to SRCS in Makefile.am.
-Add foo.o to OBJS in makefile.win32.
+* Add foo.o to OBJS in makefile.win32.
-Add Foo to parsers.h & fill in comment with parser number for foo.
+* Add Foo to parsers.h & fill in comment with parser number for foo.
 
 In foo.c:
 Edit FooKinds 3rd column to match a s_tag_type_names string in tm_tag.c.
@@ -282,17 +301,19 @@ Start normally with e.g. "gdb src/geany".
 Type 'r' to run.
 Press Ctrl-C from the gdb window to interrupt program execution.
 
-Program received signal SIGINT, Interrupt.
+Example::
-0x00d16402 in __kernel_vsyscall ()
-(gdb) call plugin_new("./plugins/.libs/demoplugin.so")
-** INFO: Loaded:   ./plugins/.libs/demoplugin.so (Demo)
-$1 = (Plugin *) 0x905a890
-(gdb) c
-Continuing.
 
-Program received signal SIGINT, Interrupt.
+	Program received signal SIGINT, Interrupt.
-0x00d16402 in __kernel_vsyscall ()
+	0x00d16402 in __kernel_vsyscall ()
-(gdb) call plugin_free(0x905a890)
+	(gdb) call plugin_new("./plugins/.libs/demoplugin.so")
-** INFO: Unloaded: ./plugins/.libs/demoplugin.so
+	** INFO: Loaded:   ./plugins/.libs/demoplugin.so (Demo)
-(gdb) c
+	$1 = (Plugin *) 0x905a890
-Continuing.
+	(gdb) c
+	Continuing.
+
+	Program received signal SIGINT, Interrupt.
+	0x00d16402 in __kernel_vsyscall ()
+	(gdb) call plugin_free(0x905a890)
+	** INFO: Unloaded: ./plugins/.libs/demoplugin.so
+	(gdb) c
+	Continuing.

doc/Makefile.am

@@ -13,6 +13,9 @@ pdf: geany.txt
 api-doc: Doxyfile
 	doxygen
 
+hacking-doc: ../HACKING
+	rst2html -stg --stylesheet=geany.css $^ hacking.html
+
 # when generating documentation, first try rst2html.py as it is the upstream default
 doc: geany.txt
 	rst2html.py -stg --stylesheet=geany.css $(srcdir)/geany.txt geany.html || \