1   Get the software

I’m assuming your system has fundamentals like Python and Apache installed. In addition:

• Trac (I’m using v0.10.x)

• Darcs (I’m using v. 1.0.8)

• sqlite2 (I personally had problems with version 3 and the Darcs plugin on a Fedora Core 4 system, which have been reported to the project maintainers)

• Trac plugins

  • Darcs plugin
  • Web Admin plugin
  • Account Manager plugin

• Python docutils (for reStructuredText support)

• SilverCity (for syntax coloring of your code)

• Python setuptools (for working with Trac plugins)

• Apache mod_python

Note that the items that are not linked above should be available via the package manager of most modern Linux systems. You’ll want to install everything except that Trac plugins before moving on to the next step.

2   Set up your Trac instance

Create a directory where you want to maintain your Trac projects and use the trac-admin command to create the instance and associate it with your Darcs repository:

trac-admin /path/to/MyProject initenv "My Project" sqlite:db/trac.db darcs /path/to/repo /usr/share/trac/templates/

The instance is successfully created, but you’ll get a warning that Trac is not supported. That’s because you haven’t setup the plugins yet.

3   Install and configure the Trac plugins

Download the source for each plugin into a temporary directory. Trac handles plugins in the Python "egg" format. So in the source directory of each, run the following command:

python setup.py bdist_egg

That will create a file with a .egg extension in the dist directory of the plugin you’ve downloaded, which you can now copy to the plugins directory of your new Trac instance. Be sure to copy all three of them.

Now you need to update your Trac instance to understand the Darcs plugin:

trac-admin /path/to/MyProject upgrade
trac-admin /path/to/MyProject resync

Finally, add the following to the conf/trac.ini file of your instance, under the [components] section:

[components]
trac.web.auth.LoginModule = disabled
acct_mgr.web_ui.LoginModule = enabled
trac.ticket.report.* = disabled

You may wish to test your instance now, using Trac’s built-in Web server, and browsing to localhost:8000:

tracd --port 8000 /path/to/MyProject

or:

/usr/sbin/tracd --port 8000 /path/to/MyProject

Make sure you can browse your Darcs repo to confirm that the Darcs plugin is working. If you’re not seeing syntax highlighting, check to make sure SilverCity has been installed correctly.

In this setup, however, we’ll ultimately be using Apache and mod_python to server the instance, and a few extra steps are needed.

4   Configure Apache and mod_python

Trac’s documentation on mod_python is mostly adequate, with one exception. You need to identify a cache directory for your instance’s egg plugins. In your Location directive, composed in accordance with that documentation, including the following line should be sufficient:

SetEnv PYTHON_EGG_CACHE /tmp/trac-eggs

For the sake of completeness, the Location directive inside the VirtualHost setup for your site should look something like this, if you have multiple Trac instances:

<Location /projects>
  SetHandler mod_python
  PythonHandler trac.web.modpython_frontend
  PythonOption TracEnvParentDir /path/to/my/trac/projects
  SetEnv PYTHON_EGG_CACHE /tmp/trac-eggs
  PythonOption TracUriRoot /projects
</Location>

Finally, the user under which Apache is run will need read and write access to the following directories in your instance:

• db
• attachments
• log

5   Configure user authentication and permissions

By default, Trac allows the anonymous user access to nearly everything, so you’ll want to make some changes. Fortunately the Web Admin and Account Manager plugins make this fairly easy to do. Before you create any user accounts, I found it was easiest simply to start by adding the TRAC_ADMIN permission to the anonymous group via the command line admin tool:

trac-admin /path/to/projenv permission add anonymous TRAC_ADMIN

Once I have access to the "Admin" button in the Web interface as anonymous I performed the following:

1. In Accounts > Configuration, identify the path to the HtPasswdStore. Ideally this will probably be a location within your instance. The Web server user will need to be able to write to the location.
2. In Accounts > Users, add a user. Note that you could also add a user by registering yourself via the "Register" link that should appear after having installed the Account Manager plugin.
3. In General > Permissions, create an "admin" group in the "Add Subject to Group" box.
4. In the same box, add the newly created user to the admin group.
5. Now, remove any "CREATE" or "DELETE" or write-related permissions, especially TRAC_ADMIN, from the anonymous subject.
6. Using the "Grant Permission" box, add anything appropriate for your setup to the "authenticated" subject. Make sure the TRAC_ADMIN permission is assigned to the newly created admin group.
7. Add any other groups appropriate to your project (e.g., developers, who would probably have access to everything except TRAC_ADMIN)

6   Final notes

It’s up to you to configure your ticket system with the appropriate values for components, milestones, versions, etc.

{{{
#!rst

Your text goes here.

}}}

Preparing the central Darcs respository

Upload your public files to where your public repo will be, and then create a repository there, recursively adding the project’s files to it:

cd proj_folder
darcs init
darcs add -r *

Then record a comment for the patch:

darcs record -a

The -a flag will apply all the patches without prompting the user to approve each one. In the case of creating a new project, that means "addfile" patches (which are not really patches in the traditional sense) will be submitted for each file, along with the "hunks" containing the new code represented by the new files.

You can avoid any prompt at all by issuing the command with an extra flag and the patch name:

darcs record -am "Project imported."

The first time you do this, you’ll be prompted to add an email address for the "patch’s author", which in turn will create the _darcs/prefs/author file in your project directory.

Because this will be a basic repository where sent patches will be applied by the administrator, you’ll also want to manually add a file called email to that same directory (_darcs/prefs). That file should contain a single line: the email address of the administrator who will apply the patches. Subsequently issuing of the darcs send command by project contributors will use that email address as the destination for the patch.

You must now make the repository available to remote users. The easiest way to do that is via the Apache Web server. Make a directory in your Apache root called repos and in that directory, and simply symlink to the directory of your Darcs-enabled project. You may have to check to make sure that the appropriate Apache directive allows for following of symlinks. In my case, I also had to make the project directory (and its parent directory, in fact) world-executable.

The main repository is now available for retrieval by collaborators. As the Darcs documentation states, "As long as you’re running a web server and making your repo available to the world, you may as well make it easy for people to see what changes you’ve made." There’s a CGI script that allows users to browse the patch history of your projects. In Ubuntu Linux (Breezy), the darcs-server package handles its installation for you, installing the file /usr/lib/cgi-bin/darcs.cgi. That works out-of-the-box with Ubuntu’s Apache install. If you’ve installed darcs manually, you may have to run make installserver to do the same. Note that you can change the name and location of your repos directory, mentioned above, in /etc/darcs/cgi.conf.

Applying patches

As patches start coming in via email from contributors, you’ll need to apply them to the central repo.

The most direct way to do that would to be to login via a shell to the central repository’s server, and:

cd /path/to/project
darcs apply /path/to/patch

Another possible option is for the project administrator to maintain a local repo in addition to the central repo, apply any patches there (also using darcs apply), and then use his or her shell account to "push" the local repo changes to the central repo server:

darcs push username@website.com:/path/to/repos/proj_name

Contributing to the repo

If you’re a contributor who wants to work with the project for the first time you retrieve it from the Web like so:

darcs get http://www.website.com/repos/proj_name

Now you have a copy of the repo, a fully functional branch.

After working with the project, making changes, etc., you can view the changes you’ve made since your last repo update:

darcs whatsnew

(Add the --summary flag for less verbose output, also add the –look-for-adds flag to see any new files that have been created since your last check-in. You’ll need to add them manually (see below).)

Name your patch and comment on the details of your changes:

darcs record -a

And send them to the central repo (in our case, via email):

darcs send -a

(Note the -a flag in the above two commands, indicating all patches; otherwise you’ll have to approve them one-by-one.)

Note that "darcs send" will fail if you do not have a local mail agent installed. In that case, the best way is simply to output the patch as a file, like so:

darcs send -a --output=/tmp/changes.patch

Note also that if you added any files, you’ll need to explicitly add them to the repo:

darcs add myscript.py

If you want to subsequently pull other contributors’ changes from the repo:

darcs pull http://www.website.com/repos/proj_name

Add the -a flag to avoid being asked to confirm on a per-patch basis.

Tagging versions and getting tagged versions

From the Darcs manual:

While pull and unpull can be used to construct different "versions" in a repository, it is often desirable to name specific configurations of patches so they can be identified and retrieved easily later. This is how darcs implements what is usually known as versions. The command for this is tag, and it records a tag in the current repository.

So, to tag a version 1.0, for example, in the project directory execute:

darcs tag 1.0

And to get the tree for that version later:

darcs get --tag "1.0" http://www.website.com/repos/proj_name

The Tools

I suggest that all the average user really needs is a text editor (which saves documents in plain text rather than some proprietary and/or arcane format) that can fulfill the following functions¹ :

• Copy/cut/paste
• Undo
• Find and replace
• Spell check

These functions are handled by the lightweight text editor I’m using to compose this document, gedit for the GNOME Desktop for Linux.

Some ancillary functions, such as image processing, thesaurus, etc. can and should be fulfilled by separate programs that specialize in these features and therefore can do a much better job of them.

But what about font sizes and styles, page numbering, footnotes, indentation, text alignment, etc., etc.–features that do in fact comprise the 10% of features that almost all users need?

Here it’s necessary to draw a crucial distinction between what has become widely known as WYSIWYG (What You See Is What You Get) document composition and what has subsequently been described as WYSIWYM (What You See Is What You Mean), a semantic approach that recommends the document author concentrate on the content of the document without considering the presentation of that content. When composition is complete, the presentation of that document can be outsourced to another program. In my current way of thinking, that other program is LaTeX, a document typesetting system that was originally developed for authors of mathematics- and science-related documents, but which can be useful for any type of document.

What I’m doing here is separating the process of composition from the typesetting of the document, the latter of which I believe becomes a distraction in the composition process. What if in your super-simple text editor, you could easily indicate, say, using a system of easy-to-understand symbols, or "markup" in the relevant parlance, to indicate where your footnotes are, where your emphasized text is, etc. There exist several such systems, but the one that I believe is the most appropriate for the average user is reStructuredText (reST), about which I’ve briefly written in the pages of this site. As for the matter of page numbering, line spacing, etc. in the final document, that would be left to the typesetting system (LaTeX, mentioned above), which would permit you to choose a professionally developed document style which performs those functions according to a standard appropriate to your field of work. The Docutils project (originally project developed to facilitate documentation of the Python programming language) provides reST conversion to LaTeX, which in turn provides conversion utilities to more common document formats like PDF. You could choose to install this system on your own computer, or if a service which provides this functionality were available via a Web site (which I currently plan to develop), you could simply submit your text document for processing via your Web browser and receive a PDF or HTML document in return.

Your source document–the document to which you would make subsequent revisions–would continue to be the fully legible plain text document which uses the reST markup, and which can thus be continue to be edited in virtually any program capable of dealing with plain text.

Other Motivations

Rather than going into further technical detail at this point, I’d like to point out some deeper motivations for wishing to see the word processor consigned to the dustbin of history (or at least for wanting to see it forced to occupy a marginal space more proportional with those 10% of users who need its advanced functionality). The information technology revolution, and in particular ubiquitous Internet access, has resulted in a capacity for distraction that undermines the productivity gains promised by IT as well as the utility of the broad information access it provides. The classic dilemma of how to efficiently turn information into knowledge has never been so acute.

Paul Ford, a Harper’s editor, Web developer, and NPR commentator, has published an extremely insightful article which explores these themes. In it he refers to the measures he has taken to deal with this problem as "Amish computing":

… I can honestly say that since broadband Internet came to my home a year and a half ago my stock of new, fresh, fun ideas has grown very thin. It’s just too much. My mind can’t wander, because, with anything that interests me, I can look it up on Wikipedia to gain some context. Before I know it I’ve got thirty tabs open at once in Firefox. Then new email comes in. … I’ve started using an Alphasmart Neo to draft text, and WordPerfect for DOS to edit and revise. My average daily word count has doubled as a result, and my stock of fresh ideas seems to be replenishing.

Ford subsequently extended these thoughts to a general audience in a recent NPR commentary, suggesting the ubiquitousness of the problem.

What’s interesting about Ford’s analysis for our purposes here is not so much the distraction potential inherent in the Internet, but in the computer–the knowledge worker’s tool–itself. Ford’s solution involves composing text on a device away from his computer, and reverting to a very early version of a popular word processor program which not only has a reduced feature set, but which by virtue of being a DOS program restricts the opportunity for distraction by other items on his desktop (i.e., there is no "desktop" in DOS). Only incidentally does that desktop include a Web browser. Once a painless way of typesetting a document in accordance with what I’ve described above is made available, my suggestion to Ford will be that he do away with WordPerfect entirely and compose his documents in reST directly on his Alphasmart Neo.

Advantages

Leaving aside my own preference for parsimony regarding computer hardware resources, I’d like to summarize some of the chief advantages to the approach discussed above:

• Documents are legible by any text editor and thus fundamentally independent of any single program
• The WYSIWYM (What You See Is What You Mean) approach helps the user cut through the distractions inherent in the use of information technology tools and resources.

Challenges

A few potential challenges to the perspective outlined in this document might include:

• To what extent am I artifically assuming a scarcity of hardware resources in criticizing bloatware? I.e., in 10 years time, might not every consumer electronic device have enough muscle to run even the most bloated word processor program?
• Collaboration: If your document composition process includes a lot of collaboration, how practical is it to convince your collaborators of the legitimacy of this argument, wean them off their dependency on Microsoft Word, and to get them to learn reST, which while basically simple, does have some quirks which will no doubt annoy many users?
• Am I drawing an artificial distinction between word processors and text editors? Is a text editor not just a lightweight word processor?