[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

RE: [PATCH] Reworking INSTALL, Take 2

From: Bruce Atherton <bruce_at_callenish.com>
Date: 2002-01-30 22:08:44 CET

At 12:45 PM 1/30/2002 +0100, Sander Striker wrote:
>If someone finds the time to do some formatting changes to HACKING
>(make identation consistent, etc), that would be appreciated.

Like this?

Log:

* HACKING
Make indentation consistent at 3 spaces each, and make list types match

Index: ./HACKING
===================================================================
--- ./HACKING
+++ ./HACKING Wed Jan 30 13:04:02 2002
@@ -11,24 +11,24 @@

  TABLE OF CONTENTS

- * Participating in the community
- * Theory and documentation
- * What to read
- * Directory layout
- * Coding style
- * Document everything
- * Using page breaks
- * Other conventions
- * APR status codes
- * Automated tests
- * Writing test cases before code
- * Debugging the server
- * Writing log entries
- * Patch submission guidelines
- * The Configuration/Build System Under Unix
- * Building from a working copy - Unix
- * Building from a working copy - Win32
- * How to create a distribution tarball
+ * Participating in the community
+ * Theory and documentation
+ * What to read
+ * Directory layout
+ * Coding style
+ * Document everything
+ * Using page breaks
+ * Other conventions
+ * APR status codes
+ * Automated tests
+ * Writing test cases before code
+ * Debugging the server
+ * Writing log entries
+ * Patch submission guidelines
+ * The Configuration/Build System Under Unix
+ * Building from a working copy - Unix
+ * Building from a working copy - Win32
+ * How to create a distribution tarball

@@ -47,22 +47,22 @@

  Go to http://subversion.tigris.org and

- * Join the "dev", "svn", and "announce" mailing lists.
+ * Join the "dev", "svn", and "announce" mailing lists.
        The dev list, dev@subversion.tigris.org, is where almost all
        discussion takes place. All questions should go there, though
        you might want to check the list archives first. The "svn"
        list receives automated commit emails.

- * Print out and digest the Spec. (The postscript might look
+ * Print out and digest the Spec. (The postscript might look
        better than the PDF.) The Spec will give you a theoretical
        overview of Subversion's design.

  If you'd like to contribute code, then look at:

- * The bugs/issues database
+ * The bugs/issues database
        http://subversion.tigris.org/servlets/ProjectIssues

- * The bite-sized tasks page
+ * The bite-sized tasks page
        http://subversion.tigris.org/project_tasks.html

  To submit code, simply send your patches to dev@subversion.tigris.org.
@@ -74,8 +74,7 @@
  Theory and documentation
  ========================

- A. DESIGN
-
+ 1. DESIGN
        A design spec was written in June 2000, and is a bit out of
        date. But it still gives a good theoretical introduction to the
        inner workings of the repository, and to Subversion's various
@@ -83,22 +82,19 @@
        versions posted on the Subversion website.

- B. WEBDAV
-
+ 2. WEBDAV
        Greg Stein has written an introduction Subversion's network
        protocol, which is an extended dialect of HTTP. The document is
        'www/webdav-usage.html', and is also posted on the website.

- C. USER MANUAL
-
+ 3. USER MANUAL
        We've started documenting some of the behavior of the client;
        it's only a small beginning, but it may help. Look at
        doc/user/manual/ for this project.

- D. SYSTEM NOTES
-
+ 4. SYSTEM NOTES
        A lot of the design ideas for particular aspects of the system
        have been documented in individual files in the notes directory.

@@ -118,15 +114,15 @@
  understanding of the implementation details. Here's a suggested
  perusal order:

- * the basic building blocks: svn_string.h, svn_error.h, svn_types.h
+ * the basic building blocks: svn_string.h, svn_error.h, svn_types.h

- * useful utilities: svn_io.h, svn_path.h, svn_hash.h, svn_xml.h
+ * useful utilities: svn_io.h, svn_path.h, svn_hash.h, svn_xml.h

- * the critical interface: svn_delta.h
+ * the critical interface: svn_delta.h

- * client-side interfaces: svn_ra.h, svn_wc.h, svn_client.h
+ * client-side interfaces: svn_ra.h, svn_wc.h, svn_client.h

- * the repository and versioned filesystem: svn_repos.h svn_fs.h
+ * the repository and versioned filesystem: svn_repos.h svn_fs.h

  Subversion tries to stay portable by using only ANSI/ISO C and by
@@ -138,11 +134,11 @@
  understand Subversion without first glancing over certain header files
  in APR (look in apr/include/):

- * memory pools: apr_pools.h
+ * memory pools: apr_pools.h

- * filesystem access: apr_file_io.h
+ * filesystem access: apr_file_io.h

- * hashes and arrays: apr_hash.h, apr_tables.h
+ * hashes and arrays: apr_hash.h, apr_tables.h

@@ -290,46 +286,46 @@

  In addition to the GNU standards, Subversion uses these conventions:

- * Use only spaces for indenting code, never tabs. Tab display
- width is not standardized enough, and anyway it's easier to
- manually adjust indentation that uses spaces.
-
- * Stay within 80 columns, the width of a minimal standard display
- window.
-
- * Signify internal variables by two underscores after the prefix.
- That is, when a symbol must (for technical reasons) reside in the
- global namespace despite not being part of a published interface,
- then use two underscores following the module prefix. For
- example:
-
- svn_fs_get_rev_prop () /* Part of published API. */
- svn_fs__parse_props () /* For internal use only. */
-
- * Put this comment at the bottom of new source files to make Emacs
- automatically load svn-dev.el:
-
- /*
- * local variables:
- * eval: (load-file "../svn-dev.el")
- * end:
- */
-
- (This assumes the C file is located in a subdirectory of
- subversion/subversion/, which most are.)
-
- * We have a tradition of not marking files with the names of
- individual authors (i.e., we don't put lines like "Author: foo"
- or "@author foo" in a special position at the top of a source
- file). This is to discourage territoriality -- even when a file
- has only one author, we want to make sure others feel free to
- make changes. People might be unnecessarily hesitant if someone
- appears to have staked ownership on the file.
-
- * There are many other unspoken conventions maintained througout
- the code, that are only noticed when someone unintentionally
- fails to follow them. Just try to have a sensitive eye for the
- way things are done, and when in doubt, ask.
+ * Use only spaces for indenting code, never tabs. Tab display
+ width is not standardized enough, and anyway it's easier to
+ manually adjust indentation that uses spaces.
+
+ * Stay within 80 columns, the width of a minimal standard display
+ window.
+
+ * Signify internal variables by two underscores after the prefix.
+ That is, when a symbol must (for technical reasons) reside in the
+ global namespace despite not being part of a published interface,
+ then use two underscores following the module prefix. For
+ example:
+
+ svn_fs_get_rev_prop () /* Part of published API. */
+ svn_fs__parse_props () /* For internal use only. */
+
+ * Put this comment at the bottom of new source files to make Emacs
+ automatically load svn-dev.el:
+
+ /*
+ * local variables:
+ * eval: (load-file "../svn-dev.el")
+ * end:
+ */
+
+ (This assumes the C file is located in a subdirectory of
+ subversion/subversion/, which most are.)
+
+ * We have a tradition of not marking files with the names of
+ individual authors (i.e., we don't put lines like "Author: foo"
+ or "@author foo" in a special position at the top of a source
+ file). This is to discourage territoriality -- even when a file
+ has only one author, we want to make sure others feel free to
+ make changes. People might be unnecessarily hesitant if someone
+ appears to have staked ownership on the file.
+
+ * There are many other unspoken conventions maintained througout
+ the code, that are only noticed when someone unintentionally
+ fails to follow them. Just try to have a sensitive eye for the
+ way things are done, and when in doubt, ask.

@@ -398,11 +394,11 @@
  such as GDB. Instead, you'll need to start up, then interrupt httpd,
  set your breakpoint, and continue:

- % gdb httpd
- (gdb) run -X
- ^C
- (gdb) break some_func_in_mod_dav_svn
- (gdb) continue
+ % gdb httpd
+ (gdb) run -X
+ ^C
+ (gdb) break some_func_in_mod_dav_svn
+ (gdb) continue

  The -X switch is equivalent to -DONE_PROCESS and -DNO_DETACH, which
  ensure that httpd runs as a single thread and remains attached to the
@@ -491,8 +487,8 @@
  a comment, alongside the code it explains. Here's an example of doing
  it right:

- (consume_count): If `count' is unreasonable, return 0 and don't
- advance input pointer.
+ (consume_count): If `count' is unreasonable, return 0 and don't
+ advance input pointer.

  And then, in `consume_count' in `cplus-dem.c':

@@ -516,13 +512,13 @@
  There are some common-sense exceptions to the need to name everything
  that was changed:

- * If you have made a change which requires trivial changes
- throughout the rest of the program (e.g., renaming a variable),
- you needn't name all the functions affected.
-
- * If you have rewritten a file completely, the reader understands
- that everything in it has changed, so your log entry may simply
- give the file name, and say "Rewritten".
+ * If you have made a change which requires trivial changes
+ throughout the rest of the program (e.g., renaming a variable),
+ you needn't name all the functions affected.
+
+ * If you have rewritten a file completely, the reader understands
+ that everything in it has changed, so your log entry may simply
+ give the file name, and say "Rewritten".

  In general, there is a tension between making entries easy to find by
  searching for identifiers, and wasting time or producing unreadable
@@ -852,15 +848,15 @@
  It is possible to configure and build Subversion on Unix in a
  directory other than the working copy. For example

- $ svn co http://svn.collab.net/trunk/repos -d svn
- $ cd svn
- $ # get neon/db/apr as required
- $ chmod +x autogen.sh
- $ ./autogen.sh
- $ mkdir ../obj
- $ cd ../obj
- $ ../svn/configure [...with options as appropriate...]
- $ make
+ $ svn co http://svn.collab.net/trunk/repos -d svn
+ $ cd svn
+ $ # get neon/db/apr as required
+ $ chmod +x autogen.sh
+ $ ./autogen.sh
+ $ mkdir ../obj
+ $ cd ../obj
+ $ ../svn/configure [...with options as appropriate...]
+ $ make

  puts the Subversion working copy in the directory svn and builds it in
  a separate, parallel directory obj.
@@ -868,20 +864,21 @@
  Why would you want to do this? Well there are a number of
  reasons...

- You may prefer to avoid "polluting" the working copy with files
- generated during the build.
+ * You may prefer to avoid "polluting" the working copy with files
+ generated during the build.

- You may want to put the build directory and the working copy on
- different physical disks to improve performance.
+ * You may want to put the build directory and the working copy on
+ different physical disks to improve performance.

- You may want to separate source and object code and only backup the
- source.
+ * You may want to separate source and object code and only backup
+ the source.

- You may want to remote mount the working copy on multiple machines,
- and build for different machines from the same working copy.
+ * You may want to remote mount the working copy on multiple
+ machines, and build for different machines from the same working
+ copy.

- You may want to build multiple configurations from the same working
- copy.
+ * You may want to build multiple configurations from the same
+ working copy.

  The last reason above is possibly the most useful. For instance you
  can have separate debug and optimised builds each using the same
@@ -903,7 +900,7 @@
  To build the client components, you'll need a copy of neon 0.18.2. The
  sources are available at

- http://www.webdav.org/neon/neon-0.18.2.tar.gz
+ http://www.webdav.org/neon/neon-0.18.2.tar.gz

  Unpack the distribution into the root directory of the Subversion
  source tree and rename the directory neon-0.18.2 to neon. The MSVC
@@ -919,16 +916,16 @@
  well as the modified project files used to build them, the config.hw
  file and the complete (unmodified) neon/src directory.

- IMPORTANT NOTE: These neon libraries should *only* be used when
- building Subversion. They were build to depend on the verson
- of expat-lite in the Subversion sources.
+ IMPORTANT NOTE: These neon libraries should *only* be used when
+ building Subversion. They were build to depend on the verson
+ of expat-lite in the Subversion sources.

  If you want to build the server components, you'll also need a copy of
  Berkeley DB, version 4.0.14 or newer. The sources are available at
  http://www.sleepycat.com. There is a binary distibution on the Subversion
  downloads page, named

- db-4.0.14-win32.zip
+ db-4.0.14-win32.zip

  Unpack the distribution into the root directory of the Subversion source
  tree as <SVN>\db4-win32. It's a good idea to add <SVN>\db4-win32\bin to

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Received on Sat Oct 21 14:37:01 2006

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.