summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDan McGee <dan@archlinux.org>2007-11-20 18:58:09 -0600
committerDan McGee <dan@archlinux.org>2007-11-20 23:31:41 -0600
commit5f2899622070496eb7e918c9089c6a6327bacb41 (patch)
tree964eb9f92e3a0833f6a1f7ba8959e9feec79dc73
parent4696ad6cad9c659728e9e061689728fc0417ad73 (diff)
Turn HACKING into an asciidoc document
Add some hints so we can use asciidoc on the HACKING document. It is still readable as text, but a simple 'asciidoc HACKING' command will give you a nice pretty guide now. Signed-off-by: Dan McGee <dan@archlinux.org>
-rw-r--r--HACKING91
1 files changed, 58 insertions, 33 deletions
diff --git a/HACKING b/HACKING
index 140b11c7..5ee6d064 100644
--- a/HACKING
+++ b/HACKING
@@ -1,54 +1,65 @@
Contributing to pacman
======================
-In addition to this file, please read 'submitting-patches' and
-'translation-help' in the same directory for additional info on contributing.
+In addition to this file, please read `submitting-patches` and
+`translation-help` in the same directory for additional info on contributing.
Coding style
------------
1. All code should be indented with tabs. (Ignore the use of only spaces in
this file) By default, source files contain the following VIM modeline:
-
- /* vim: set ts=2 sw=2 noet: */
++
+[C]
+code~~~~~~~~~~
+/* vim: set ts=2 sw=2 noet: */
+code~~~~~~~~~~
2. When opening new blocks such as 'while', 'if', or 'for', leave the opening
brace on the same line as the beginning of the codeblock. The closing brace
gets its own line (the only exception being 'else'). Do not use extra
- spaces around the parentheses of the block. ALWAYS use opening/closing
+ spaces around the parentheses of the block. ALWAYS use opening and closing
braces, even if it's just a one-line block. This reduces future error when
blocks are expanded beyond one line.
-
- for(lp = list; lp; lp = lp->next) {
- newlist = _alpm_list_add(newlist, strdup(lp->data));
- }
-
- while(it) {
- ptr = it->next;
- if(fn) {
- fn(it->data);
- } else {
- return(1);
- }
- free(it);
- it = ptr;
- }
++
+[C]
+code~~~~~~~~~~
+for(lp = list; lp; lp = lp->next) {
+ newlist = _alpm_list_add(newlist, strdup(lp->data));
+}
+
+while(it) {
+ ptr = it->next;
+ if(fn) {
+ fn(it->data);
+ } else {
+ return(1);
+ }
+ free(it);
+ it = ptr;
+}
+code~~~~~~~~~~
3. When declaring a new function, put the opening and closing braces on their
own line. Also, when declaring a pointer, do not put a space between the
asterisk and the variable name.
-
- alpm_list_t *alpm_list_add(alpm_list_t *list, void *data)
- {
- alpm_list_t *ptr, *lp;
-
- ptr = list;
- if(ptr == NULL) {
- ...
- }
-
-4. Comments should be ANSI-C89 compliant. That means no "// Comment" style;
- use only "/* Comment */" style.
++
+[C]
+code~~~~~~~~~~
+alpm_list_t *alpm_list_add(alpm_list_t *list, void *data)
+{
+ alpm_list_t *ptr, *lp;
+
+ ptr = list;
+ if(ptr == NULL) {
+ ...
+ }
+ ...
+}
+code~~~~~~~~~~
+
+4. Comments should be ANSI-C89 compliant. That means no `// Comment` style;
+ use only `/* Comment */` style.
/* This is a comment */
NOT
@@ -81,31 +92,45 @@ Coding style
Other Concerns
--------------
+Header Includes
+~~~~~~~~~~~~~~~
+
Currently our #include usage is in messy shape, but this is no reason to
continue down this messy path. When adding an include to a file, follow this
general pattern, including blank lines:
+[C]
+code~~~~~~~~~~
#include "config.h"
#include <standardheader.h>
#include <another.h>
#include <...>
+code~~~~~~~~~~
Follow this with some more headers, depending on whether the file is in libalpm
or pacman proper. For libalpm:
+[C]
+code~~~~~~~~~~
/* libalpm */
#include "yourfile.h"
#include "alpm_list.h"
#include "anythingelse.h"
+code~~~~~~~~~~
For pacman:
+[C]
+code~~~~~~~~~~
#include <alpm.h>
#include <alpm_list.h>
/* pacman */
#include "yourfile.h"
#include "anythingelse.h"
+code~~~~~~~~~~
-vim: set ts=2 sw=2 et:
+/////
+vim: set ts=2 sw=2 syntax=asciidoc et:
+/////