SF.net SVN: geany:[3029] trunk
ntrel at users.sourceforge.net
ntrel at xxxxx
Wed Oct 1 16:47:28 UTC 2008
Revision: 3029
http://geany.svn.sourceforge.net/geany/?rev=3029&view=rev
Author: ntrel
Date: 2008-10-01 16:47:25 +0000 (Wed, 01 Oct 2008)
Log Message:
-----------
Reformat HACKING as true reStructuredText.
Add 'make hacking-doc' target to generate hacking.html.
Modified Paths:
--------------
trunk/ChangeLog
trunk/HACKING
trunk/doc/Makefile.am
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2008-10-01 12:43:17 UTC (rev 3028)
+++ trunk/ChangeLog 2008-10-01 16:47:25 UTC (rev 3029)
@@ -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:
Modified: trunk/HACKING
===================================================================
--- trunk/HACKING 2008-10-01 12:43:17 UTC (rev 3028)
+++ trunk/HACKING 2008-10-01 16:47:25 UTC (rev 3029)
@@ -1,3 +1,11 @@
+=============
+Hacking Geany
+=============
+.. contents::
+
+General
+=======
+
About this file
---------------
This file contains information for anyone wanting to work on the Geany
@@ -2,18 +10,20 @@
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
---------------
+* 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).
+
You should generate and read the plugin API documentation, see below.
-src/plugindata.h contains the plugin API data types and some notes.
-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
-be output to doc/reference/index.html.
+tool. Run ``make api-doc`` in the doc subdirectory. The documentation
+will be output to doc/reference/index.html.
@@ -26,12 +36,14 @@
is already working on similar code.
In general it's best to work from the current SVN, but we accept patches
-against other releases.
-$ svn diff > fix-some-bug.patch
+against other releases::
-If you're not using SVN, you can use the diff command:
-$ diff -u originalpath modifiedpath > new-feature.patch
+ $ svn diff > fix-some-bug.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 @@
-----------------
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
-and structs can usually still be appended to, ensuring that all the
-existing elements stay in place - this will keep the ABI stable.
+extra asterix: ``/**``) is something in the plugin API. Things like
+enums and structs can usually still be appended to, ensuring that all
+the existing elements stay in place - this will keep the ABI stable.
-Note: Some structs like KeyBindingGroup and GeanyCallback cannot be
-appended to without breaking the ABI because they are used to declare
-structs by plugins, not just for accessing struct members through
-a pointer.
+.. warning::
+ Some structs like GeanyKeyGroup and GeanyCallback cannot be
+ 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
-part of the plugin API, you should increment abi_version in plugindata.h.
-This is not needed if you're just appending fields to structs. The
-api_version value should be incremented for any changes to the plugin API,
-including appending elements.
+When reordering or changing existing elements of structs that are
+used as part of the plugin API, you should increment GEANY_ABI_VERSION
+in plugindata.h. This is usually not needed if you're just appending
+fields to structs. The GEANY_API_VERSION value should be incremented
+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 @@
Coding
------
-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
-much easier to read and maintain.
-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
-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
-later versions).
-We currently try to support the old GCC 2.9.x compiler,
-so we always declare variables before statements. You can use
--Wdeclaration-after-statement in your ./configure CFLAGS to warn about
-this.
-You should also try to write ISO C90 code for portability, so always
-use C /* */ comments and function_name(void) instead of function_name().
-This is for compatibility with various Unix-like compilers. You can use
--ansi in your CFLAGS to help check this.
+* 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
+ much easier to read and maintain.
+* 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
+ 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
+ later versions).
+* We currently try to support the old GCC 2.9.x compiler,
+ so we always declare variables before statements. You can use
+ -Wdeclaration-after-statement in your ./configure CFLAGS to warn about
+ this.
+* You should also try to write ISO C90 code for portability, so always
+ use C ``/* */`` comments and function_name(void) instead of
+ function_name(). This is for compatibility with various Unix-like
+ 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.
-Use the multiline comment /* */ to comment small blocks of code,
-functions descriptions or longer explanations of code, etc. C++ single
-line comments will cause portability issues. The more comments are in
-your code the better.
-Lines should not be longer than about 100 characters and after 100
-characters the lines should be wrapped and more indented than the first
-line to highlight that the line is continued. We avoid putting spaces
-between function names and the opening brace for argument lists. 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 ;-)
+* We use a tab width of 4 and indent completely with tabs not spaces.
+* Use the multiline comment ``/* */`` to comment small blocks of code,
+ functions descriptions or longer explanations of code, etc. C++ single
+ line comments will cause portability issues. The more comments are in
+ your code the better.
+* Lines should not be longer than about 100 characters and after 100
+ characters the lines should be wrapped and more indented than the first
+ line to highlight that the line is continued.
+* We don't put spaces between function names and the opening brace for
+ argument lists.
+* 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 @@
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,22 +176,23 @@
Adding a source file foo.[hc] in src/ or plugins/
-------------------------------------------------
-Add foo.c, foo.h to SRCS in path/Makefile.am.
-Add foo.o to OBJS in path/makefile.win32.
-Add path/foo.c to po/POTFILES.in (for string translation).
+* Add foo.c, foo.h to SRCS in path/Makefile.am.
+* Add foo.o to OBJS in path/makefile.win32.
+* 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.
-Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
-filetypes.c.
-Rebuild Geany.
-From your geany/ directory, run:
-src/geany --generate-data-files
+* Add GEANY_FILETYPES_FOO to filetypes.h.
+* Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
+ filetypes.c.
+* Rebuild Geany.
+* From your geany/ directory, run::
+ src/geany --generate-data-files
+
(The src/ prefix may be different, depending on where the binary is
generated.)
This will update data/filetype_extensions.conf. Note that
@@ -188,10 +206,11 @@
data/filetypes.c for an example.
Programming languages should have:
-[keywords] if the lexer supports it.
-[settings] mostly for comment settings.
-[build_settings] for commands to run.
+* [keywords] if the lexer supports it.
+* [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 -
see below.
@@ -202,23 +221,23 @@
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.win32
- * scintilla/KeyWords.cxx - add a LINK_LEXER command *manually*
+* scintilla/Makefile.am
+* scintilla/makefile.win32
+* 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
-start by copying and adapting another filetype's initialization, such
-as styleset_asm_init().
+ settings from the filetypes.foo configuration file. You should probably
+ start by copying and adapting another filetype's initialization, such
+ 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().
-3. Add this in highlighting_init_styles():
-init_styleset_case(GEANY_FILETYPES_FOO, foo);
-4. Add this in highlighting_set_styles():
-styleset_case(GEANY_FILETYPES_FOO, foo);
+ is created. Again you could copy and adapt a function like styleset_asm().
+3. In highlighting_init_styles(), add
+ ``init_styleset_case(GEANY_FILETYPES_FOO, foo);``.
+4. In highlighting_set_styles(), add
+ ``styleset_case(GEANY_FILETYPES_FOO, foo);``.
Please try to make your styles fit in with the other filetypes' default
colors.
@@ -256,9 +275,9 @@
(You can also try the Anjuta project's tagmanager codebase.)
-Add foo.c to SRCS in Makefile.am.
-Add foo.o to OBJS in makefile.win32.
-Add Foo to parsers.h & fill in comment with parser number for foo.
+* Add foo.c to SRCS in Makefile.am.
+* Add foo.o to OBJS in makefile.win32.
+* 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 @@
Type 'r' to run.
Press Ctrl-C from the gdb window to interrupt program execution.
-Program received signal SIGINT, Interrupt.
-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.
+Example::
-Program received signal SIGINT, Interrupt.
-0x00d16402 in __kernel_vsyscall ()
-(gdb) call plugin_free(0x905a890)
-** INFO: Unloaded: ./plugins/.libs/demoplugin.so
-(gdb) c
-Continuing.
+ Program received signal SIGINT, Interrupt.
+ 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.
+ 0x00d16402 in __kernel_vsyscall ()
+ (gdb) call plugin_free(0x905a890)
+ ** INFO: Unloaded: ./plugins/.libs/demoplugin.so
+ (gdb) c
+ Continuing.
Modified: trunk/doc/Makefile.am
===================================================================
--- trunk/doc/Makefile.am 2008-10-01 12:43:17 UTC (rev 3028)
+++ trunk/doc/Makefile.am 2008-10-01 16:47:25 UTC (rev 3029)
@@ -13,6 +13,9 @@
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 || \
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the Commits
mailing list