class list_t { };
     ...
     int
     main(int argc, char *argv[])
     {
          list_t list;
     }

This pretty much forces me to start any type in the global namespace with a capitol letter (not my preference). To keep things consistent, that means all my classes/structs will now start with a capitol letter. See here for the posix rules.

1. Copy the Pygments supplied rst-directive.py to your docutils installation. Something like:

   cp Pygments/external/rst-directive.py \
    .../site-packages/docutils/parsers/rst/directives/rst_directive.py

   Notice that rst-directive.py became rst_directive.py (dash changed to underscore).

2. Modify rst_directive.py in the docutils directives directory to set INLINESTYLES = True and add a style option to the formatter. Something like:

   # Set to True if you want inline CSS styles instead of classes
   INLINESTYLES = True
   
   from pygments.formatters import HtmlFormatter
   
   # The default formatter
   DEFAULT = HtmlFormatter(noclasses=INLINESTYLES, style='trac')

3. Modify rst2html.py to import the Pygments directive. I added the following line:

   from docutils.parsers.rst.directives import rst_directive

That’s it. Now I can use the ..sourcecode directive in my rst documents. For example:

.. sourcecode:: c++
	int
	main(int argc, char *argv[])
	{
	}

1. Install subversion
2. Install the Sun Java JDK. Unfortunately, the completely free IcedTea JDK isn’t up to running jEdit.
3. Download Apache ant and put the bin directory in your path.
4. You’ll need xsltproc and docbook to build the jEdit documentation. Download the docbook xsl scripts from http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608&release_id=603854 and unpack somewhere (I unpack into c:\workspace\docbook, this path is needed later in step 7). The above links to version 1.74. The most recent version can be found from http://wiki.docbook.org/topic/DocBookXslStylesheets.
5. Download xsltproc. I downloaded a binary from http://xmlsoft.org/XSLT/downloads.html. On Windows, you’ll also need iconv.dll, zlib1.dll, libxslt.dll, libxml2.dll, and libexslt.dll to run xsltproc.exe. Put the exe and dll’s in your path.
6. Check-out jEdit from svn:

   svn co https://jedit.svn.sourceforge.net/svnroot/jedit/jEdit/trunk jEdit

7. Create jEdit’s build.properties from the build.properties.sample file:

   cd jEdit
   cp build.properties.sample build.properties

   Edit the build.properties file to point to your xslt installation. The following are the lines I add (the path to docbook.xsl should match the directory in step 4):

   xsltproc.executable=C:\\workspace\\bin\\xsltproc.exe
   docbook.xsl=C:\\workspace\\docbook\\docbook-xsl-1.74.0
   docbook.catalog=C:\\workspace\\docbook\\docbook-xsl-1.74.0\\catalog.xml

8. Now build jEdit, run:

   ant
   ant userdocs

   This builds jedit.jar and the userdocs in the build directory (a normal jEdit prints numerous warnings that can be ignored). You can run this jEdit with something like:

   javaw.exe -Xmx1024M -Dswing.aatext=true -Dawt.useSystemAAFontSettings=lcd -Dsun.java2d.d3d=false -jar build\jedit.jar

9. If the above was successful, you should now have a .jedit settings directory in your home directory. We can now setup the necessities for building a plugin. Go to your settings directory and check-out jEdit’s build-support.

   cd ~/.jedit/jars
   svn co https://jedit.svn.sourceforge.net/svnroot/jedit/build-support/trunk build-support

10. Now copy the build-support build.properties sample and edit for your installation (should still be in ~/.jedit/jars).

    cp build-support\build.properties.sample build.properties

    Edit build.properties to set the jEdit install directory (I don’t change anything else). On my system, that line looks like this:

    jedit.install.dir=c:\\workspace\\jedit\\jEdit\\build

11. Finally, check-out a plugin to build and build it.

    svn co https://jedit.svn.sourceforge.net/svnroot/jedit/plugins/VoxSpell/trunk VoxSpell
    cd VoxSpell
    ant

    This should build VoxSpell and place the jar file in your settings directory plugin-jars directory. The next time you start jEdit it will find the jar file and load the plugin.

Everything ran well, except occasionally a test would time-out. I figured this was a problem with how I was setting up the stdin/stdout pipes to the subtask (each thread would fork() to run the sub-task and use a timed poll() to wait for results). On Friday, I finally sat down to figure out what was causing the test hangs.

Turns out it had nothing to do with sub-task input and output. Each thread is responsible for one subtask. The thread creates the necessary pipes, performs some other book keeping, and then forks. The child process then transforms a vector of command line arguments to an argv[] style array, sets up stdin/stdout with dup2, and calls execvp.

To debug, I modified the parent to print the hung pid which I would attach to using gdb. Every time I attached, the child process was stuck in the same place: waiting on a mutex used by the std::string implementation.

The child process doesn’t use any threading functions, and all of its parameters are passed on the stack. However, I didn’t consider that most of libstdc++ is thread safe (I can’t find a reference that specifies exactly what is and isn’t thread safe in glibc/libstdc++). Each time the process forked, it risked forking while the underlying std::string memory mutex was being held by another thread. As documented in the pthread_atfork man page, those mutexes are not useable after the fork, and must be re-initialized with pthread_mutex_init in the child process. This caused the child process to hang indefinitely waiting on a mutex that would be released only in the parent’s process space.

The solution was to move the std::string processing before the fork. That left only dup2 calls and the execvp after the fork. Result: no more hangs!