git » libjio » commit 6deb156

Documentation overhaul

author Alberto Bertogli
2009-03-02 05:48:40 UTC
committer Alberto Bertogli
2009-03-02 05:51:46 UTC
parent f4f54460bfe2fd3321da7ed0e3c51d167094066f

Documentation overhaul

This patch is a much-needed documentation overhaul.

It changes the documentation format from LyX to rst, updates all the
important docs, and removes the redundant ones.

Signed-off-by: Alberto Bertogli <albertito@blitiri.com.ar>

INSTALL +0 -4
README +0 -4
doc/big_transactions +0 -9
doc/guide.lyx +0 -778
doc/guide.rst +285 -0
doc/guide.txt +0 -378
doc/jiofsck +0 -12
doc/libjio.3 +162 -145
doc/libjio.html +0 -444
doc/libjio.lyx +0 -433
doc/libjio.rst +244 -0
doc/libjio.txt +0 -305
doc/{layout => source_layout} +0 -0
doc/threads +0 -20
doc/tids +0 -83
doc/tids.rst +76 -0

diff --git a/INSTALL b/INSTALL
index 246dd15..69b49bc 100644
--- a/INSTALL
+++ b/INSTALL
@@ -36,7 +36,3 @@ instead.
 After installing, you're ready to use the library; you can see how by looking
 at the manpage with "man libjio".
 
-
-If you have any question, suggestion or comment, please send it to my email
-address, albertito@blitiri.com.ar.
-
diff --git a/README b/README
index c6136f6..1adc539 100644
--- a/README
+++ b/README
@@ -19,10 +19,6 @@ everything is isolated.
 There are more detailed documents: a programming guide, a brief introduction
 to the design and inner workings, and the manpage; all in the doc/ directory.
 
-The first two, called 'guide' and 'libjio' respectively, are both in txt and
-lyx formats, with HTML, Postscript and PDF versions in the website, which are
-not included in the package for space reasons.
-
 
 To see how to install it, please read the INSTALL file.
 
diff --git a/doc/big_transactions b/doc/big_transactions
deleted file mode 100644
index 3c5392d..0000000
--- a/doc/big_transactions
+++ /dev/null
@@ -1,9 +0,0 @@
-
-If you have to create big transactions, instead of creating a huge buffer you
-can mmap a temporary file and periodically sync it; and when you're done, just
-jtrans_commit() the whole thing.
-
-This would be a quite efficient way, without any performance penalty and a
-very simple approach; I originally thought of doing this on the journal, but
-it had many drawbacks that made it much expensive, slower and complex.
-
diff --git a/doc/guide.lyx b/doc/guide.lyx
deleted file mode 100644
index 364fe8c..0000000
--- a/doc/guide.lyx
+++ /dev/null
@@ -1,778 +0,0 @@
-#LyX 1.3 created this file. For more info see http://www.lyx.org/
-\lyxformat 221
-\textclass article
-\language english
-\inputencoding auto
-\fontscheme default
-\graphics default
-\paperfontsize default
-\papersize Default
-\paperpackage a4
-\use_geometry 0
-\use_amsmath 0
-\use_natbib 0
-\use_numerical_citations 0
-\paperorientation portrait
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\defskip medskip
-\quotes_language english
-\quotes_times 2
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-
-\layout Title
-
-libjio Programmer's Guide
-\layout Author
-
-Alberto Bertogli (albertito@blitiri.com.ar)
-\layout Standard
-
-
-\begin_inset LatexCommand \tableofcontents{}
-
-\end_inset 
-
-
-\layout Section
-
-Introduction
-\layout Standard
-
-This small document attempts serve as a guide to the programmer who wants
- to make use of the library.
- It's not a replacement for the man page or reading the code; but it's a
- good starting point for everyone who wants to get involved with it.
-\layout Standard
-
-The library is not complex to use at all, and the interfaces were designed
- to be as intuitive as possible, so the text is structured as a guide to
- present the reader all the common structures and functions the way they're
- normally used.
-\layout Section
-
-Definitions
-\layout Standard
-
-This is a library which provides a journaled transaction-oriented I/O API.
- You've probably read this a hundred times already in the documents, and
- if you haven't wondered yet what on earth does this mean you should be
- reading something else!
-\layout Standard
-
-We say this is a transaction-oriented API because we make transactions the
- center of our operations, and journaled because we use a journal (which
- takes the form of a directory with files on it) to guarantee coherency
- even after a crash at any point.
-\layout Standard
-
-Here we think a transaction as a list of 
-\emph on 
-(buffer, length, offset)
-\emph default 
- to be applied to a file.
- That triple is called an 
-\emph on 
-operation
-\emph default 
-, so we can say that a transaction represent an ordered group of operations
- on the same file
-\emph on 
-.
-\layout Standard
-
-The act of 
-\emph on 
-committing
-\emph default 
- a transaction means writing all the elements of the list; and 
-\emph on 
-rollbacking
-\emph default 
- means to undo a previous commit, and leave the data just as it was before
- doing the commit.
-\begin_inset Foot
-collapsed false
-
-\layout Standard
-
-While all this definitions may seem obvious to some people, it requires
- special attention because there are a lot of different definitions, and
- it's not that common to see 
-\begin_inset Quotes eld
-\end_inset 
-
-transaction
-\begin_inset Quotes erd
-\end_inset 
-
- applied to file I/O (it's a term used mostly on database stuff), so it's
- important to clarify before continuing.
-\end_inset 
-
-
-\layout Standard
-
-It's important to note that the library not only provides a convenient and
- easy API to perform this kind of operations, but provides a lot of guarantees
- while doing this.
- The most relevant and useful is that at any point of time, even if we crash
- horribly, a transaction will be either fully applied or not applied at
- all.
- You should not ever see partial transactions or any kind of data corruption.
-\layout Standard
-
-To achieve this, the library uses what is called a 
-\emph on 
-journal
-\emph default 
-, a very vague (and fashionable) term we use to describe a set of auxiliary
- files that get created to store temporary data at several stages.
- The proper definition and how we use them is outside the scope of this
- document, and you as a programmer shouldn't need to deal with it.
- In case you're curious, it's described in a bit more detail in another
- text which talks about how the library works internally.
- Now let's get real.
-\layout Section
-
-The data types
-\layout Standard
-
-To understand any library, it's essential to be confident in the knowledge
- of their data structures and how they relate each other.
- In libjio we have two basic structures which have a very strong relationship,
- and represent the essential objects we deal with.
- Note that you normally don't manipulate them directly, because they have
- their own initializer functions, but they are the building blocks for the
- rest of the text, which, once this is understood, is obvious and self-evident.
-\layout Standard
-
-The first structure we face is 
-\family typewriter 
-struct\SpecialChar ~
-jfs
-\family default 
-, called the 
-\emph on 
-file structure
-\emph default 
-, and it represents an open file, just like a regular file descriptor or
- a 
-\family typewriter 
-FILE\SpecialChar ~
-*
-\family default 
-.
-\layout Standard
-
-Then you find 
-\family typewriter 
-struct\SpecialChar ~
-jtrans
-\family default 
-, called the 
-\emph on 
-transaction structure
-\emph default 
-, which represents a single transaction.
- You can have as many transactions as you want, and operate on all of them
- simultaneously without problems; the library is entirely thread safe so
- there's no need to worry about that.
-\layout Section
-
-The basic functions
-\layout Standard
-
-Now that we've described our data types, let's see how we can really operate
- with the library.
- 
-\layout Standard
-
-First of all, as with regular I/O, you need to open your files.
- This is done with 
-\family typewriter 
-jopen()
-\family default 
-, which looks a lot like 
-\family typewriter 
-open()
-\family default 
- but takes a file structure instead of a file descriptor (this will be very
- common among all the functions), and adds a new parameter 
-\emph on 
-jflags
-\emph default 
- that can be used to modify some subtle library behaviour we'll see later,
- and it's normally not used.
-\layout Standard
-
-We have a happy file structure open now, and the next thing to do would
- be to create a transaction.
- This is what 
-\family typewriter 
-jtrans_init()
-\family default 
- is for: it takes a file structure and a transaction structure and initializes
- the latter, leaving it ready to use.
-\layout Standard
-
-So we have our transaction, let's add a write operation to it; to do this
- we use 
-\family typewriter 
-jtrans_add()
-\family default 
-.
- We could keep on adding operations to the transaction by keep on calling
- 
-\family typewriter 
-jtrans_add()
-\family default 
- as many times as we want.
-\layout Standard
-
-Finally, we decide to apply our transaction to the file, that is, write
- all the operations we've added.
- And this is the easiest part: we call 
-\family typewriter 
-jtrans_commit()
-\family default 
-, and that's it!
-\layout Standard
-
-When we're done using the file, we call 
-\family typewriter 
-jclose()
-\family default 
-, just like we call 
-\family typewriter 
-close()
-\family default 
-.
-\layout Standard
-
-Let's put it all together and code a nice 
-\begin_inset Quotes eld
-\end_inset 
-
-hello world
-\begin_inset Quotes erd
-\end_inset 
-
- program (return values are ignored for simplicity):
-\layout LyX-Code
-
-char buf[] = "Hello world!";
-\layout LyX-Code
-
-struct jfs file;
-\layout LyX-Code
-
-struct jtrans trans;
-\newline 
-
-\newline 
-
-\layout LyX-Code
-
-jopen(&file, "filename", O_RDWR | O_CREAT, 0600, 0);
-\layout LyX-Code
-
-jtrans_init(&file, &trans);
-\newline 
-
-\newline 
-
-\layout LyX-Code
-
-jtrans_add(&trans, buf, strlen(buf), 0);
-\newline 
-
-\newline 
-
-\layout LyX-Code
-
-jtrans_commit(&trans);
-\newline 
-
-\newline 
-
-\layout LyX-Code
-
-jclose(&file);
-\layout Standard
-
-As we've seen, we open the file and initialize the structure with 
-\family typewriter 
-jopen()
-\family default 
- (with the parameter 
-\emph on 
-jflags
-\emph default 
- being the last 0)and 
-\family typewriter 
-jtrans_init()
-\family default 
-, then add an operation with 
-\family typewriter 
-jtrans_add()
-\family default 
- (the last 0 is the offset, in this case the beginning of the file), commit
- the transaction with 
-\family typewriter 
-jtrans_commit()
-\family default 
-, and finally close the file with 
-\family typewriter 
-jclose()
-\family default 
-.
-\layout Section
-
-Advanced functions
-\layout Subsection
-
-Interaction with reads
-\begin_inset LatexCommand \label{sub:Interaction-with-reads}
-
-\end_inset 
-
-
-\layout Standard
-
-So far we've seen how to use the library to perform writes, but what about
- reads? The only and main issue with reads is that, because we provide transacti
-on atomicity, a read must never be able to 
-\begin_inset Quotes eld
-\end_inset 
-
-see
-\begin_inset Quotes erd
-\end_inset 
-
- a transaction partially applied.
- This is achieved internally by using fine-grained file locks; but you shouldn't
- mind about it if you use the functions the library gives you because they
- take care of all the locking.
-\layout Standard
-
-This set of functions are very similar to the UNIX ones (
-\family typewriter 
-read()
-\family default 
-, 
-\family typewriter 
-readv()
-\family default 
-, etc.); and in fact are named after them: they're called 
-\family typewriter 
-jread()
-\family default 
-, 
-\family typewriter 
-jreadv()
-\family default 
- and 
-\family typewriter 
-jpread()
-\family default 
-; and have the same parameters except for the first one, which instead of
- a file descriptor is a file structure
-\begin_inset Foot
-collapsed false
-
-\layout Standard
-
-In fact, this set of functions is a part of what is called the 
-\begin_inset Quotes eld
-\end_inset 
-
-UNIX API
-\begin_inset Quotes erd
-\end_inset 
-
-, which is described below.
-\end_inset 
-
-.
- Bear in mind that transactions are only visible by reads 
-\emph on 
-after
-\emph default 
- you commit them with 
-\family typewriter 
-jtrans_commit()
-\family default 
-.
-\layout Subsection
-
-Rollback
-\layout Standard
-
-There is a very nice and important feature in transactions, that allow them
- to be 
-\begin_inset Quotes eld
-\end_inset 
-
-undone
-\begin_inset Quotes erd
-\end_inset 
-
-, which means that you can undo a transaction and leave the file just as
- it was the moment before applying it.
- The action of undoing it is called to 
-\emph on 
-rollback
-\emph default 
-, and the function is called 
-\family typewriter 
-jtrans_rollback()
-\family default 
-, which takes the transaction as the only parameter.
-\layout Standard
-
-Be aware that rollbacking a transaction can be dangerous if you're not careful
- and cause you a lot of troubles.
- For instance, consider you have two transactions (let's call them 1 and
- 2, and assume they were applied in that order) that modify the same offset,
- and you rollback transaction 1; then 2 would be lost.
- It is not an dangerous operation itself, but its use requires care and
- thought.
-\layout Subsection
-
-Integrity checking and recovery
-\layout Standard
-
-An essential part of the library is taking care of recovering from crashes
- and be able to assure a file is consistent.
- When you're working with the file, this is taking care of; but what when
- you first open it? To answer that question, the library provides you with
- a function named 
-\family typewriter 
-jfsck()
-\family default 
-, which checks the integrity of a file and makes sure that everything is
- consistent.
- It must be called 
-\begin_inset Quotes eld
-\end_inset 
-
-offline
-\begin_inset Quotes erd
-\end_inset 
-
-, that is when you are not actively committing and rollbacking; it is normally
- done before calling 
-\family typewriter 
-jopen()
-\family default 
-.
- Another good practise is call jfsck_cleanup() after calling jfsck() to
- make sure we're starting up with a fresh clean journal.
- After both calls, it is safe to assume that the file is and ready to use.
-\layout Standard
-
-You can also do this manually with an utility named 
-\emph on 
-jiofsck
-\emph default 
-, which can be used from the shell to perform the checking and cleanup.
-\layout Subsection
-
-Threads and locking
-\layout Standard
-
-The library is completely safe to use in multithreaded applications; however,
- there are some very basic and intuitive locking rules you have to bear
- in mind.
-\layout Standard
-
-Most is fully threadsafe so you don't need to worry about concurrency; in
- fact, a lot of effort has been put in making parallel operation safe and
- fast.
-\layout Standard
-
-You need to care only when opening, closing and checking for integrity.
- In practise, that means that you shouldn't call 
-\family typewriter 
-jopen()
-\family default 
-, 
-\family typewriter 
-jclose()
-\family default 
- in parallel with the same jfs structure, or in the middle of an I/O operation,
- just like you do when using the normal UNIX calls.
- In the case of 
-\family typewriter 
-jfsck()
-\family default 
-, you shouldn't invoke it for the same file more than once at the time;
- while it will cope with that situation, it's not recommended.
-\layout Standard
-
-All other operations (commiting a transaction, rollbacking it, adding operations
-, etc.) and all the wrappers are safe and don't require any special consideration
-s.
-\layout Subsection
-
-Lingering transactions
-\layout Standard
-
-If you need to increase performance, you can use lingering transactions.
- In this mode, transactions take up more disk space but allows you to do
- the synchronous write only once, making commits much faster.
- To use them, just add 
-\family typewriter 
-J_LINGER
-\family default 
- to the jflags parameter in 
-\family typewriter 
-jopen()
-\family default 
-.
- It is very wise to call 
-\family typewriter 
-jsync()
-\family default 
- frequently to avoid using up too much space.
-\layout Section
-
-Disk layout
-\layout Standard
-
-The library creates a single directory for each file opened, named after
- it.
- So if we open a file 
-\begin_inset Quotes eld
-\end_inset 
-
-output
-\begin_inset Quotes erd
-\end_inset 
-
-, a directory named 
-\begin_inset Quotes eld
-\end_inset 
-
-.output.jio
-\begin_inset Quotes erd
-\end_inset 
-
- will be created.
- We call it the 
-\emph on 
-journal directory
-\emph default 
-, and it's used internally by the library to save temporary data; you shouldn't
- modify any of the files that are inside it, or move it while it's in use.
- It doesn't grow much (it only uses space for transactions that are in the
- process of committing) and gets automatically cleaned while working with
- it so you can (and should) ignore it.
- Besides that, the file you work with has no special modification and is
- just like any other file, all the internal stuff is kept isolated on the
- journal directory.
-\layout Section
-
-Other APIs
-\layout Standard
-
-We're all used to do things our way, and when we learn something new it's
- often better if it looks alike what we already know.
- With this in mind, the library comes with two sets of APIs that look a
- lot like traditional, well known ones.
- Bear in mind that they are not as powerful as the transaction API that
- is described above, and they can't provide the same functionality in a
- lot of cases; however for a lot of common and simple use patterns they
- are good enough.
-\layout Subsection
-
-UNIX API
-\layout Standard
-
-There is a set of functions that emulate the UNIX API (
-\family typewriter 
-read()
-\family default 
-, 
-\family typewriter 
-write()
-\family default 
-, and so on) which make each operation a transaction.
- This can be useful if you don't need to have the full power of the transactions
- but only to provide guarantees between the different functions.
- They are a lot like the normal UNIX functions, but instead of getting a
- file descriptor as their first parameter, they get a file structure.
- You can check out the manual page to see the details, but they work just
- like their UNIX version, only that they preserve atomicity and thread-safety
- 
-\emph on 
-within each call
-\emph default 
-.
-\layout Standard
-
-In particular, the group of functions related to reading (which was described
- above in 
-\begin_inset LatexCommand \ref{sub:Interaction-with-reads}
-
-\end_inset 
-
-) are extremely useful because they take care of the locking needed for
- the library proper behaviour.
- You should use them instead of the regular calls.
-\layout Standard
-
-The full function list is available on the man page and I won't reproduce
- it here; however the naming is quite simple: just prepend a 'j' to all
- the names: 
-\family typewriter 
-jread()
-\family default 
-, 
-\family typewriter 
-jwrite()
-\family default 
-, etc.
-\layout Subsection
-
-ANSI C API
-\layout Standard
-
-Besides the UNIX API you can find an ANSI C API, which emulates the traditional
- 
-\family typewriter 
-fread()
-\family default 
-, 
-\family typewriter 
-fwrite()
-\family default 
-, etc.
- They're still in development and has not been tested carefully, so I won't
- spend time documenting them.
- Let me know if you need them.
-\layout Section
-
-Compiling and linking
-\layout Standard
-
-When you want to use your library, besides including the 
-\emph on 
-
-\begin_inset Quotes eld
-\end_inset 
-
-libjio.h
-\begin_inset Quotes erd
-\end_inset 
-
-
-\emph default 
- header, you have to make sure your application uses the Large File Support
- (
-\begin_inset Quotes eld
-\end_inset 
-
-LFS
-\begin_inset Quotes erd
-\end_inset 
-
- from now on), to be able to handle large files properly.
- This means that you will have to pass some special standard flags to the
- compiler, so your C library uses the same data types as the library.
- For instance, on 32-bit platforms (like x86), when using LFS, offsets are
- usually 64 bits, as opposed to the usual 32.
-\layout Standard
-
-The library is always built with LFS; however, link it against an application
- without LFS support could lead to serious problems because this kind of
- size differences and ABI compatibility.
-\layout Standard
-
-The Single Unix Specification standard proposes a simple and practical way
- to get the flags you need to pass your C compiler to tell you want to compile
- your application with LFS: use a program called 
-\emph on 
-
-\begin_inset Quotes eld
-\end_inset 
-
-getconf
-\begin_inset Quotes erd
-\end_inset 
-
-
-\emph default 
- which should be called like 
-\emph on 
-
-\begin_inset Quotes eld
-\end_inset 
-
-getconf LFS_CFLAGS
-\begin_inset Quotes erd
-\end_inset 
-
-
-\emph default 
-, and it outputs the appropiate parameters.
- Sadly, not all platforms implement it, so it's also wise to pass 
-\emph on 
-
-\begin_inset Quotes eld
-\end_inset 
-
--D_FILE_OFFSET_BITS=64
-\begin_inset Quotes erd
-\end_inset 
-
-
-\emph default 
- just in case.
-\layout Standard
-
-In the end, the command line would be something like:
-\layout LyX-Code
-
-gcc `getconf LFS_CFLAGS` -D_FILE_OFFSET_BITS=64 
-\backslash 
-
-\layout LyX-Code
-
-        app.c -ljio -lpthread -o app
-\layout Standard
-
-If you want more detailed information or examples, you can check out how
- the library and sample applications get built.
-\layout Section
-
-Where to go from here
-\layout Standard
-
-If you're still interested in learning more, you can find some small and
- clean samples are in the 
-\begin_inset Quotes eld
-\end_inset 
-
-samples
-\begin_inset Quotes erd
-\end_inset 
-
- directory (full.c is a simple and complete one), other more advanced examples
- can be found in the web page, as well as modifications to well known software
- to make use of the library.
- For more information about the inner workings of the library, you can read
- the 
-\begin_inset Quotes eld
-\end_inset 
-
-libjio
-\begin_inset Quotes erd
-\end_inset 
-
- document, and the source code.
-\the_end
diff --git a/doc/guide.rst b/doc/guide.rst
new file mode 100644
index 0000000..3f3bdef
--- /dev/null
+++ b/doc/guide.rst
@@ -0,0 +1,285 @@
+
+libjio Programmer's Guide
+=========================
+
+Introduction
+------------
+
+This small document attempts serve as a guide to the programmer who wants to
+make use of the library. It's not a replacement for the man page or reading
+the code; but it's a good starting point for everyone who wants to get
+involved with it.
+
+The library is not complex to use at all, and the interfaces were designed to
+be as intuitive as possible, so the text is structured as a guide to present
+the reader all the common structures and functions the way they're normally
+used.
+
+Definitions
+-----------
+
+This is a library which provides a journaled, transaction-oriented I/O API.
+You've probably read this a hundred times already in the documents, and if you
+haven't wondered yet what on earth does, this mean you should be reading
+something else!
+
+We say this is a transaction-oriented API because we make transactions the
+center of our operations, and journaled because we use a journal (which takes
+the form of a directory with files on it) to guarantee coherency even after a
+crash at any point.
+
+In this document, we think of a transaction as a list of *(buffer, length,
+offset)* to be applied to a file. That triplet is called an *operation*, so we
+can say that a transaction represent an ordered group of operations on the
+same file.
+
+The act of *committing* a transaction means writing all the elements of the
+list; and rollbacking means to undo a previous commit, and leave the data just
+as it was before doing the commit. While all this definitions may seem obvious
+to some people, it requires special attention because there are a lot of
+different definitions, and it's not that common to see "transaction" applied
+to file I/O, because it's a term used mostly on database stuff.
+
+The library provides several guarantees, the most relevant and useful being
+that at any point of time, even if the machine crash horribly, a transaction
+will be either fully applied or not applied at all.
+
+To achieve this, the library uses what is called a journal, a very vague (and
+fashionable) term we use to describe a set of auxiliary files that get created
+to store temporary data at several stages. The proper definition and how we
+use them is outside the scope of this document, and you as a programmer
+shouldn't need to deal with it. In case you're curious, it's described in a
+bit more detail in another text which talks about how the library works
+internally. Now let's get real.
+
+
+The data types
+--------------
+
+To understand any library, it's essential to be confident in the knowledge of
+their data structures and how they relate each other. libjio has two basic
+structures which have a very strong relationship, and represent the essential
+objects it deals with. Note that you normally don't manipulate them directly,
+because they have their own initializer functions, but they are the building
+blocks for the rest of the text, which, once this is understood, should be
+obvious and self-evident.
+
+The first structure we face is *struct jfs*, usually called the file
+structure, and it represents an open file, just like a regular file descriptor
+or a FILE \*.
+
+Then you find *struct jtrans*, usually called the transaction structure, which
+represents a single transaction.
+
+
+Basic operation
+---------------
+
+Now that we've described our data types, let's see how we can operate with the
+library.
+
+First of all, as with regular I/O, you need to open your files. This is done
+with *jopen()*, which looks a lot like *open()* but takes a file structure
+instead of a file descriptor (this will be very common among all the
+functions), and adds a new parameter *jflags* that can be used to modify some
+subtle library behaviour we'll see later, and is normally not used.
+
+We have a happy file structure open now, and the next thing to do would be to
+create a transaction. This is what *jtrans_init()* is for: it takes a file
+structure and a transaction structure and initializes the latter, leaving it
+ready to use.
+
+Now that we have our transaction, let's add a write operation to it; to do
+this we use *jtrans_add()*. We could keep on adding operations to the
+transaction by keep on calling jtrans_add() as many times as we want.
+Operations within a transaction may overlap, and will be applied in order.
+
+Finally, we decide to apply our transaction to the file, that is, write all
+the operations we've added. And this is the easiest part: we call
+*jtrans_commit()*, and that's it!
+
+When we're done using the file, we call *jclose()*, just like we would call
+*close()*.
+
+Let's put it all together and code a nice "hello world"
+program (return values are ignored for simplicity)::
+
+  char buf[] = "Hello world!";
+  struct jfs file;
+  struct jtrans trans;
+
+  jopen(&file, "filename", O_RDWR | O_CREAT, 0600, 0);
+
+  jtrans_init(&file, &trans);
+  jtrans_add(&trans, buf, strlen(buf), 0);
+  jtrans_commit(&trans);
+
+  jclose(&file);
+
+As we've seen, we open the file and initialize the structure with *jopen()*
+(with the parameter *jflags* being the last 0), create a new transaction with
+*jtrans_init()*, then add an operation with *jtrans_add()* (the last 0 is the
+offset, in this case the beginning of the file), commit the transaction with
+*jtrans_commit()*, and finally close the file with *jclose()*.
+
+Reading is much easier: the library provides three functions, *jread()*,
+*jpread()* and *jreadv()*, that behave exactly like *read()*, *pread()* and
+*readv()*, except that they play safe with libjio's writing code. You should
+use these to read from files you're writing with libjio.
+
+
+Integrity checking and recovery
+-------------------------------
+
+An essential part of the library is taking care of recovering from crashes and
+be able to assure a file is consistent. When you're working with the file,
+this is taking care of; but what when you first open it? To answer that
+question, the library provides you with a function named *jfsck()*, which
+checks the integrity of a file and makes sure that everything is consistent.
+
+It must be called "offline", that is when you are not actively committing and
+rollbacking; it is normally done before calling *jopen()* and is **very, very
+important**. Another good practise is to call *jfsck_cleanup()* after calling
+*jfsck()*, to make sure we're starting up with a fresh clean journal. After
+both calls, it is safe to assume that the file is and ready to use.
+
+You can also do this manually with an utility named jiofsck, which can be used
+from the shell to perform the checking and cleanup.
+
+
+Rollback
+--------
+
+There is a very nice and important feature in transactions, that allow them to
+be "undone", which means that you can undo a transaction and leave the file
+just as it was the moment before applying it. The action of undoing it is
+called to rollback, and the function is called jtrans_rollback(), which takes
+the transaction as the only parameter.
+
+Be aware that rollbacking a transaction can be dangerous if you're not careful
+and cause you a lot of troubles. For instance, consider you have two
+transactions (let's call them 1 and 2, and assume they were applied in that
+order) that modify the same offset, and you rollback transaction 1; then 2
+would be lost. It is not an dangerous operation itself, but its use requires
+care and thought.
+
+
+UNIX-alike API
+--------------
+
+There is a set of functions that emulate the UNIX API (*read()*, *write()*,
+and so on) which make each operation a transaction. This can be useful if you
+don't need to have the full power of the transactions but only to provide
+guarantees between the different functions. They are a lot like the normal
+UNIX functions, but instead of getting a file descriptor as their first
+parameter, they get a file structure. You can check out the manual page to see
+the details, but they work just like their UNIX version, only that they
+preserve atomicity and thread-safety within each call.
+
+In particular, the group of functions related to reading (which was described
+above in `Basic operation`_) are extremely useful because they take care of
+the locking needed for the library proper behaviour. You should use them
+instead of the regular calls.
+
+The full function list is available on the man page and I won't reproduce it
+here; however the naming is quite simple: just prepend a 'j' to all the names:
+*jread()*, *jwrite()*, etc.
+
+
+Threads and locking
+-------------------
+
+The library is completely safe to use in multithreaded applications; however,
+there are some very basic and intuitive locking rules you have to bear in
+mind.
+
+Most is fully threadsafe so you don't need to worry about concurrency; in
+fact, a lot of effort has been put in making parallel operation safe and fast.
+
+You need to care only when opening, closing and checking for integrity. In
+practise, that means that you shouldn't call *jopen()*, *jclose()* in parallel
+with the same jfs structure, or in the middle of an I/O operation, just like
+you do when using the normal UNIX calls. In the case of *jfsck()*, you
+shouldn't invoke it for the same file more than once at the time; while it
+will cope with that situation, it's not recommended.
+
+All other operations (commiting a transaction, rollbacking it, adding
+operations, etc.) and all the wrappers are safe and don't require any special
+considerations.
+
+
+Lingering transactions
+----------------------
+
+If you need to increase performance, you can use lingering transactions. In
+this mode, transactions take up more disk space but allows you to do the
+synchronous write only once, making commits much faster. To use them, just add
+*J_LINGER* to the *jflags* parameter in *jopen()*. You should call *jsync()*
+frequently to avoid using up too much space.
+
+
+Disk layout
+-----------
+
+The library creates a single directory for each file opened, named after it.
+So if we open a file *output*, a directory named *.output.jio* will be
+created. We call it the journal directory, and it's used internally by the
+library to save temporary data; **you shouldn't modify any of the files that
+are inside it, nor move it while it's in use**.
+
+It doesn't grow much (it only uses space for transactions that are in the
+process of committing) and gets automatically cleaned while working with it so
+you can (and should) ignore it. Besides that, the file you work with has no
+special modification and is just like any other file, all the internal stuff
+is kept isolated on the journal directory.
+
+
+ANSI C alike API
+----------------
+
+Besides the UNIX-alike API you can find an ANSI C alike API, which emulates
+the traditional *fread()*, *fwrite()*, etc. It's still in development and has
+not been tested carefully, so I won't spend time documenting them. Let me know
+if you need them.
+
+
+Compiling and linking
+---------------------
+
+When you want to use your library, besides including the "libjio.h" header,
+you have to make sure your application uses the Large File Support ("LFS" from
+now on), to be able to handle large files properly. This means that you will
+have to pass some special standard flags to the compiler, so your C library
+uses the same data types as the library. For instance, on 32-bit platforms
+(like x86), when using LFS, offsets are usually 64 bits, as opposed to the
+usual 32.
+
+The library is always built with LFS; however, link it against an application
+without LFS support could lead to serious problems because this kind of size
+differences and ABI compatibility.
+
+The Single Unix Specification standard proposes a simple and practical way to
+get the flags you need to pass your C compiler to tell you want to compile
+your application with LFS: use a program called "getconf" which should be
+called like "getconf LFS_CFLAGS", and it outputs the appropiate parameters.
+Sadly, not all platforms implement it, so it's also wise to pass
+"-D_FILE_OFFSET_BITS=64" just in case.
+
+In the end, the command line would be something like::
+
+  gcc `getconf LFS_CFLAGS` -D_FILE_OFFSET_BITS=64 app.c -ljio -o app
+
+If you want more detailed information or examples, you can check out how the
+library and sample applications get built.
+
+
+Where to go from here
+---------------------
+
+If you're still interested in learning more, you can find some small and clean
+samples are in the "samples" directory (full.c is a simple and complete one),
+other more advanced examples can be found in the web page, as well as
+modifications to well known software to make use of the library. For more
+information about the inner workings of the library, you can read the "libjio"
+document, and the source code.
+
diff --git a/doc/guide.txt b/doc/guide.txt
deleted file mode 100644
index 44ba7d5..0000000
--- a/doc/guide.txt
+++ /dev/null
@@ -1,378 +0,0 @@
-libjio Programmer's Guide
-
-Alberto Bertogli (albertito@blitiri.com.ar)
-
-Table of Contents
-
-1 Introduction
-2 Definitions
-3 The data types
-4 The basic functions
-5 Advanced functions
-    5.1 Interaction with reads
-    5.2 Rollback
-    5.3 Integrity checking and recovery
-    5.4 Threads and locking
-    5.5 Lingering transactions
-6 Disk layout
-7 Other APIs
-    7.1 UNIX API
-    7.2 ANSI C API
-8 Compiling and linking
-9 Where to go from here
-
-
-
-1 Introduction
-
-This small document attempts serve as a guide to the 
-programmer who wants to make use of the library. It's 
-not a replacement for the man page or reading the code; 
-but it's a good starting point for everyone who wants 
-to get involved with it.
-
-The library is not complex to use at all, and the 
-interfaces were designed to be as intuitive as 
-possible, so the text is structured as a guide to 
-present the reader all the common structures and 
-functions the way they're normally used.
-
-2 Definitions
-
-This is a library which provides a journaled 
-transaction-oriented I/O API. You've probably read this 
-a hundred times already in the documents, and if you 
-haven't wondered yet what on earth does this mean you 
-should be reading something else!
-
-We say this is a transaction-oriented API because we 
-make transactions the center of our operations, and 
-journaled because we use a journal (which takes the 
-form of a directory with files on it) to guarantee 
-coherency even after a crash at any point.
-
-Here we think a transaction as a list of (buffer, 
-length, offset) to be applied to a file. That triple is 
-called an operation, so we can say that a transaction 
-represent an ordered group of operations on the same file.
-
-The act of committing a transaction means writing all 
-the elements of the list; and rollbacking means to undo 
-a previous commit, and leave the data just as it was 
-before doing the commit.While all this definitions may seem obvious to some 
-people, it requires special attention because there are 
-a lot of different definitions, and it's not that 
-common to see "transaction" applied to file I/O (it's a 
-term used mostly on database stuff), so it's important 
-to clarify before continuing.
-
-It's important to note that the library not only 
-provides a convenient and easy API to perform this kind 
-of operations, but provides a lot of guarantees while 
-doing this. The most relevant and useful is that at any 
-point of time, even if we crash horribly, a transaction 
-will be either fully applied or not applied at all. You 
-should not ever see partial transactions or any kind of 
-data corruption.
-
-To achieve this, the library uses what is called a 
-journal, a very vague (and fashionable) term we use to 
-describe a set of auxiliary files that get created to 
-store temporary data at several stages. The proper 
-definition and how we use them is outside the scope of 
-this document, and you as a programmer shouldn't need 
-to deal with it. In case you're curious, it's described 
-in a bit more detail in another text which talks about 
-how the library works internally. Now let's get real.
-
-3 The data types
-
-To understand any library, it's essential to be 
-confident in the knowledge of their data structures and 
-how they relate each other. In libjio we have two basic 
-structures which have a very strong relationship, and 
-represent the essential objects we deal with. Note that 
-you normally don't manipulate them directly, because 
-they have their own initializer functions, but they are 
-the building blocks for the rest of the text, which, 
-once this is understood, is obvious and self-evident.
-
-The first structure we face is struct jfs, called the 
-file structure, and it represents an open file, just 
-like a regular file descriptor or a FILE *.
-
-Then you find struct jtrans, called the transaction 
-structure, which represents a single transaction. You 
-can have as many transactions as you want, and operate 
-on all of them simultaneously without problems; the 
-library is entirely thread safe so there's no need to 
-worry about that.
-
-4 The basic functions
-
-Now that we've described our data types, let's see how 
-we can really operate with the library. 
-
-First of all, as with regular I/O, you need to open 
-your files. This is done with jopen(), which looks a 
-lot like open() but takes a file structure instead of a 
-file descriptor (this will be very common among all the 
-functions), and adds a new parameter jflags that can be 
-used to modify some subtle library behaviour we'll see 
-later, and it's normally not used.
-
-We have a happy file structure open now, and the next 
-thing to do would be to create a transaction. This is 
-what jtrans_init() is for: it takes a file structure 
-and a transaction structure and initializes the latter, 
-leaving it ready to use.
-
-So we have our transaction, let's add a write operation 
-to it; to do this we use jtrans_add(). We could keep on 
-adding operations to the transaction by keep on calling 
-jtrans_add() as many times as we want.
-
-Finally, we decide to apply our transaction to the 
-file, that is, write all the operations we've added. 
-And this is the easiest part: we call jtrans_commit(), 
-and that's it!
-
-When we're done using the file, we call jclose(), just 
-like we call close().
-
-Let's put it all together and code a nice "hello world" 
-program (return values are ignored for simplicity):
-
-char buf[] = "Hello world!";
-
-struct jfs file;
-
-struct jtrans trans;
-
-
-
-jopen(&file, "filename", O_RDWR | O_CREAT, 0600, 0);
-
-jtrans_init(&file, &trans);
-
-
-
-jtrans_add(&trans, buf, strlen(buf), 0);
-
-
-
-jtrans_commit(&trans);
-
-
-
-jclose(&file);
-
-As we've seen, we open the file and initialize the 
-structure with jopen() (with the parameter jflags being 
-the last 0)and jtrans_init(), then add an operation 
-with jtrans_add() (the last 0 is the offset, in this 
-case the beginning of the file), commit the transaction 
-with jtrans_commit(), and finally close the file with jclose().
-
-5 Advanced functions
-
-5.1 Interaction with reads<sub:Interaction-with-reads>
-
-So far we've seen how to use the library to perform 
-writes, but what about reads? The only and main issue 
-with reads is that, because we provide transaction 
-atomicity, a read must never be able to "see" a 
-transaction partially applied. This is achieved 
-internally by using fine-grained file locks; but you 
-shouldn't mind about it if you use the functions the 
-library gives you because they take care of all the locking.
-
-This set of functions are very similar to the UNIX ones 
-(read(), readv(), etc.); and in fact are named after 
-them: they're called jread(), jreadv() and jpread(); 
-and have the same parameters except for the first one, 
-which instead of a file descriptor is a file structureIn fact, this set of functions is a part of what is 
-called the "UNIX API", which is described below.
-. Bear in mind that transactions are only visible by 
-reads after you commit them with jtrans_commit().
-
-5.2 Rollback
-
-There is a very nice and important feature in 
-transactions, that allow them to be "undone", which means 
-that you can undo a transaction and leave the file just 
-as it was the moment before applying it. The action of 
-undoing it is called to rollback, and the function is 
-called jtrans_rollback(), which takes the transaction 
-as the only parameter.
-
-Be aware that rollbacking a transaction can be 
-dangerous if you're not careful and cause you a lot of 
-troubles. For instance, consider you have two 
-transactions (let's call them 1 and 2, and assume they 
-were applied in that order) that modify the same 
-offset, and you rollback transaction 1; then 2 would be 
-lost. It is not an dangerous operation itself, but its 
-use requires care and thought.
-
-5.3 Integrity checking and recovery
-
-An essential part of the library is taking care of 
-recovering from crashes and be able to assure a file is 
-consistent. When you're working with the file, this is 
-taking care of; but what when you first open it? To 
-answer that question, the library provides you with a 
-function named jfsck(), which checks the integrity of a 
-file and makes sure that everything is consistent. It 
-must be called "offline", that is when you are not 
-actively committing and rollbacking; it is normally 
-done before calling jopen(). Another good practise is 
-call jfsck_cleanup() after calling jfsck() to make sure 
-we're starting up with a fresh clean journal. After 
-both calls, it is safe to assume that the file is and 
-ready to use.
-
-You can also do this manually with an utility named 
-jiofsck, which can be used from the shell to perform 
-the checking and cleanup.
-
-5.4 Threads and locking
-
-The library is completely safe to use in multithreaded 
-applications; however, there are some very basic and 
-intuitive locking rules you have to bear in mind.
-
-Most is fully threadsafe so you don't need to worry 
-about concurrency; in fact, a lot of effort has been 
-put in making parallel operation safe and fast.
-
-You need to care only when opening, closing and 
-checking for integrity. In practise, that means that 
-you shouldn't call jopen(), jclose() in parallel with 
-the same jfs structure, or in the middle of an I/O 
-operation, just like you do when using the normal UNIX 
-calls. In the case of jfsck(), you shouldn't invoke it 
-for the same file more than once at the time; while it 
-will cope with that situation, it's not recommended.
-
-All other operations (commiting a transaction, 
-rollbacking it, adding operations, etc.) and all the 
-wrappers are safe and don't require any special considerations.
-
-5.5 Lingering transactions
-
-If you need to increase performance, you can use 
-lingering transactions. In this mode, transactions take 
-up more disk space but allows you to do the synchronous 
-write only once, making commits much faster. To use 
-them, just add J_LINGER to the jflags parameter in 
-jopen(). It is very wise to call jsync() frequently to 
-avoid using up too much space.
-
-6 Disk layout
-
-The library creates a single directory for each file 
-opened, named after it. So if we open a file "output", a 
-directory named ".output.jio" will be created. We call it 
-the journal directory, and it's used internally by the 
-library to save temporary data; you shouldn't modify 
-any of the files that are inside it, or move it while 
-it's in use. It doesn't grow much (it only uses space 
-for transactions that are in the process of committing) 
-and gets automatically cleaned while working with it so 
-you can (and should) ignore it. Besides that, the file 
-you work with has no special modification and is just 
-like any other file, all the internal stuff is kept 
-isolated on the journal directory.
-
-7 Other APIs
-
-We're all used to do things our way, and when we learn 
-something new it's often better if it looks alike what 
-we already know. With this in mind, the library comes 
-with two sets of APIs that look a lot like traditional, 
-well known ones. Bear in mind that they are not as 
-powerful as the transaction API that is described 
-above, and they can't provide the same functionality in 
-a lot of cases; however for a lot of common and simple 
-use patterns they are good enough.
-
-7.1 UNIX API
-
-There is a set of functions that emulate the UNIX API 
-(read(), write(), and so on) which make each operation 
-a transaction. This can be useful if you don't need to 
-have the full power of the transactions but only to 
-provide guarantees between the different functions. 
-They are a lot like the normal UNIX functions, but 
-instead of getting a file descriptor as their first 
-parameter, they get a file structure. You can check out 
-the manual page to see the details, but they work just 
-like their UNIX version, only that they preserve 
-atomicity and thread-safety within each call.
-
-In particular, the group of functions related to 
-reading (which was described above in [sub:Interaction-with-reads]) are extremely 
-useful because they take care of the locking needed for 
-the library proper behaviour. You should use them 
-instead of the regular calls.
-
-The full function list is available on the man page and 
-I won't reproduce it here; however the naming is quite 
-simple: just prepend a 'j' to all the names: jread(), 
-jwrite(), etc.
-
-7.2 ANSI C API
-
-Besides the UNIX API you can find an ANSI C API, which 
-emulates the traditional fread(), fwrite(), etc. 
-They're still in development and has not been tested 
-carefully, so I won't spend time documenting them. Let 
-me know if you need them.
-
-8 Compiling and linking
-
-When you want to use your library, besides including 
-the "libjio.h" header, you have to make sure your 
-application uses the Large File Support ("LFS" from now 
-on), to be able to handle large files properly. This 
-means that you will have to pass some special standard 
-flags to the compiler, so your C library uses the same 
-data types as the library. For instance, on 32-bit 
-platforms (like x86), when using LFS, offsets are 
-usually 64 bits, as opposed to the usual 32.
-
-The library is always built with LFS; however, link it 
-against an application without LFS support could lead 
-to serious problems because this kind of size 
-differences and ABI compatibility.
-
-The Single Unix Specification standard proposes a 
-simple and practical way to get the flags you need to 
-pass your C compiler to tell you want to compile your 
-application with LFS: use a program called "getconf" 
-which should be called like "getconf LFS_CFLAGS", and it 
-outputs the appropiate parameters. Sadly, not all 
-platforms implement it, so it's also wise to pass "
--D_FILE_OFFSET_BITS=64" just in case.
-
-In the end, the command line would be something like:
-
-gcc `getconf LFS_CFLAGS` -D_FILE_OFFSET_BITS=64 \
-
-        app.c -ljio -lpthread -o app
-
-If you want more detailed information or examples, you 
-can check out how the library and sample applications 
-get built.
-
-9 Where to go from here
-
-If you're still interested in learning more, you can 
-find some small and clean samples are in the "samples" 
-directory (full.c is a simple and complete one), other 
-more advanced examples can be found in the web page, as 
-well as modifications to well known software to make 
-use of the library. For more information about the 
-inner workings of the library, you can read the "libjio" 
-document, and the source code.
diff --git a/doc/jiofsck b/doc/jiofsck
deleted file mode 100644
index b42aeb2..0000000
--- a/doc/jiofsck
+++ /dev/null
@@ -1,12 +0,0 @@
-
-Note that jfsck does not warantee that all the transactions are fully
-completed, it can only do so if you run it without any other process accessing
-the journal.
-
-If you want to see this, you can take a look at the struct jfsck_result. It
-include a field named in_progress which tell the number of transactions that
-were in progress at the moment of checking, and as such weren't checked.
-
-Be aware that the counter is not atomic, as two checkers can be running at the
-same time.
-
diff --git a/doc/libjio.3 b/doc/libjio.3
index 76b2e1e..414f47f 100644
--- a/doc/libjio.3
+++ b/doc/libjio.3
@@ -1,78 +1,19 @@
 .TH libjio 3 "21/Feb/2004"
 .SH NAME
 libjio - A library for Journaled I/O
-
-.SH FUNCTIONS
-
+.SH SYNOPSYS
+.nf
 .B #include <libjio.h>
 
-.BI "int jopen(struct jfs *" fs ", const char *" name ", int " flags ", int " mode ", int " jflags " );
-
-.BI "ssize_t jread(struct jfs *" fs ", void *" buf ", size_t " count " );
-
-.BI "ssize_t jpread(struct jfs *" fs ", void *" buf ", size_t " count ", off_t " offset " );
-
-.BI "ssize_t jreadv(struct jfs *" fs ", struct iovec *" vector ", int " count " );
-
-.BI "ssize_t jwrite(struct jfs *" fs ", const void *" buf ", size_t " count " );
-
-.BI "ssize_t jpwrite(struct jfs *" fs ", const void *" buf ", size_t " count ", off_t " offset " );
-
-.BI "ssize_t jwritev(struct jfs *" fs ", const struct iovec *" vector ", int " count " );
-
-.BI "int jtruncate(struct jfs *" fs ", off_t " lenght " );
+.B struct jfs;
 
-.BI "int jclose(struct jfs *" fs " );
-
-.BI "void jtrans_init(struct jfs *" fs " ,struct jtrans *" ts " );
-
-.BI "int jtrans_commit(struct jtrans *" ts " );
-
-.BI "int jtrans_add(struct jtrans *" ts ", const void * " buf ", size_t " count ", off_t " offset " );
-
-.BI "int jtrans_rollback(struct jtrans *" ts " );
-
-.BI "void jtrans_free(struct jtrans *" ts " );
-
-.BI "int jfsck(const char *" name ", struct jfsck_result *" res " );
-
-.BI "int jfsck_cleanup(const char *" name" );
-
-.SH STRUCTURES
-.PP
-.br
-.nf
-.in +2n
-struct jfs {
-    int fd;                /* main file descriptor */
-    char *name;            /* and its name */
-    int jfd;               /* journal's lock file descriptor */
-    int flags;             /* journal mode options used in jopen() */
-    pthread_mutex_t lock;  /* a soft lock used in some operations */
+.BR "struct jtrans " {
     ...
-};
-.FI
-.in -2n
-
-.PP
-.br
-.nf
-.in +2n
-struct jtrans {
-    struct jfs *fs;       /* journal file structure to operate on */
-    char *name;           /* name of the transaction file */
-    int id;               /* transaction id */
-    int flags;            /* misc flags */
+    unsigned int flags;
     ...
 };
-.FI
-.in -2n
 
-.PP
-.br
-.nf
-.in +2n
-struct jfsck_result {
+.BR "struct jfsck_result" " {"
     int total;            /* total transactions files we looked at */
     int invalid;          /* invalid files in the journal directory */
     int in_progress;      /* transactions in progress */
@@ -81,106 +22,175 @@ struct jfsck_result {
     int rollbacked;       /* transactions that were rollbacked */
     ...
 };
-.FI
-.in -2n
+
+.BI "int jopen(struct jfs *" fs ", const char *" name ","
+.BI "		int " flags ", int " mode ", int " jflags ");"
+.BI "ssize_t jread(struct jfs *" fs ", void *" buf ", size_t " count ");"
+.BI "ssize_t jpread(struct jfs *" fs ", void *" buf ", size_t " count ","
+.BI "		off_t " offset ");"
+.BI "ssize_t jreadv(struct jfs *" fs ", struct iovec *" vector ","
+.BI "		int " count ");"
+.BI "ssize_t jwrite(struct jfs *" fs ", const void *" buf ", size_t " count ");"
+.BI "ssize_t jpwrite(struct jfs *" fs ", const void *" buf ", size_t " count ","
+.BI "		off_t " offset ");"
+.BI "ssize_t jwritev(struct jfs *" fs ", const struct iovec *" vector ","
+.BI "		int " count ");"
+.BI "int jtruncate(struct jfs *" fs ", off_t " lenght ");"
+
+.BI "int jclose(struct jfs *" fs ");"
+
+.BI "void jtrans_init(struct jfs *" fs " ,struct jtrans *" ts ");"
+.BI "int jtrans_commit(struct jtrans *" ts ");"
+.BI "int jtrans_add(struct jtrans *" ts ", const void * " buf ","
+.BI "		size_t " count ", off_t " offset ");"
+.BI "int jtrans_rollback(struct jtrans *" ts ");"
+.BI "void jtrans_free(struct jtrans *" ts ");"
+
+.BI "int jfsck(const char *" name ", struct jfsck_result *" res ");"
+.BI "int jfsck_cleanup(const char *" name ");"
 
 .SH DESCRIPTION
 
 libjio is a library to do transaction-oriented journaled I/O. This manpage
-describes it's C API very briefly, further information can be found in the
+describes its C API very briefly, further information can be found in the
 documentation that comes along with the library itself, or on the web at
 http://blitiri.com.ar/p/libjio.
 
-We can group the functions into three groups: the common functions, the basic
-functions and the UNIX API.
-
-The common functions provide functionality common to the other two: jopen to
-open files to use them with the library, and jfsck and jfsck_cleanup to
-provide integrity checking.
+Functions can be grouped in three different groups: the common functions, the
+UNIX-alike API, and the basic functions.
 
-The basic functions consists of jtrans_commit, jtrans_add and jtrans_rollback.
-They provide a method for manipulating transactions, which are defined in the
-jtrans structure (described above).
+The common functions provide functionality common to the other two:
+.B jopen()
+to open files in order to use them with the library, and
+.BR "jfsck() " and " jfsck_cleanup()"
+to provide integrity checking.
 
 The second group mimics somehow the traditional UNIX API by providing similar
 interfaces to read(), write(), and their friends.
 
-.SH Common functions
+The basic functions consists of
+.BR "jtrans_commit()" , " jtrans_add() " and " jtrans_rollback()" .
+They provide a method for manipulating transactions, which are defined in the
+.IR "jtrans structure" " (described above)."
+
+.SS STRUCTURES
+
+Both
+.IR "struct jfs" " and " "struct jtrans"
+are meant to be treated as opaque types, except for the fields documented
+above, which you should treat as read-only.
+
+.B struct jfsck_result
+holds the results of a
+.B jfsck()
+run, see below for details.
+
+.SS COMMON FUNCTIONS
 
 Most functions reference somehow the structures described avobe, specially
-struct jfs and struct jtrans. They represent a file to operate on and a single
-transaction, respectively. To open a file, you should use the jopen() call,
-which is just like the normal open() call but affects a pointer to a struct
-jfs. To close a file, use jclose(). They're exactly like the open() and
-close() functions but use a struct jfs instead of a file descriptor; take a
-look at their manpages if you have any doubts about how to use them.
-
-There are two functions that differs from the rest, which are jfsck() and
-jfsck_cleanup().
-
-The first one, jfsck(), is used to perform journal checking and recovery in
-case of a crash. It must be performed when nobody else is using the file (like
-in the case of a filesystem which can't be mounted), and it returns 0 if
-success or an error code != 0 in case of a failure. If it succeeded, it will
-fill jfsck_result summarizing the outcome of the operation. The error codes
-can be either J_ENOENT (no such file), J_ENOJOURNAL (no journal associated
-with that file) or J_ENOMEM (not enough free memory). There is also a program
-named jiofsck which is just a simple human frontend to this function.
-
-The second, jfsck_cleanup(), is intended to be used after jfsck() by programs
-wanting to remove all the stall transaction files and leave the journal
-directory ready to use. After calling jfsck(), the transaction files will no
-longer be needed, so by cleaning up the directory you make sure you're
-starting over with a clean journal. It returns 0 if there was an error, or 1
-if it succeeded.
-
-.SH UNIX API
-
-The UNIX API, as explained before, consists of the functions jread(),
-jpread(), jreadv(), jwrite(), jpwrite(), jwritev(), jtruncate(). In most cases
-you will only need to use this, because they're simple and familiar.
+.IR "struct jfs" " and " "struct jtrans" .
+They represent a file to operate on and a single transaction, respectively. To
+open a file, you should use the
+.B jopen()
+call, which is just like the normal
+.B open(3)
+call but affects a pointer to a
+.IR struct jfs .
+To close a file, use
+.BR jclose() .
+They're exactly like the
+.BR open(3) " and close()
+functions but use a
+.I struct jfs
+instead of a file descriptor; take a look at their manpages if you have any
+doubts about how to use them.
+
+There are two functions that differ from the rest, which are
+.BR jfsck() " and " jfsck_cleanup() .
+
+The first one,
+.BR jfsck() ,
+is used to perform journal checking and recovery in case of a crash. It must
+be performed when nobody else is using the file (like in the case of a
+filesystem which can't be mounted), and it returns 0 if success or an error
+code != 0 in case of a failure. If it succeeded, it will fill jfsck_result
+summarizing the outcome of the operation. The error codes can be either
+.I J_ENOENT
+(no such file),
+.I J_ENOJOURNAL
+(no journal associated with that file) or
+.I J_ENOMEM
+(not enough free memory). There is also a program named
+.I jiofsck
+which is just a simple human frontend to this function.
+
+The second,
+.BR jfsck_cleanup() ,
+is intended to be used after
+.B jfsck()
+by programs wanting to remove all the stall transaction files and leave the
+journal directory ready to use. After calling
+.BR jfsck() ,
+the transaction files will no longer be needed, so by cleaning up the
+directory you make sure you're starting over with a clean journal. It returns
+0 if there was an error, or 1 if it succeeded. The aforementioned
+.I jiofsck
+can also optionally invoke this function after performing the regular checks.
+
+.SS UNIX-alike API
+
+The UNIX-alike API, as explained before, consists of the functions
+.BR jread() ", " jpread() ", " jreadv() ", " jwrite() ", " jpwrite() ", "
+.BR jwritev() ", " jtruncate() .
 
 They are all exactly like the UNIX equivalent (if you still don't get it, take
 the initial 'j' out), and behave the same way, with the only exception that
-instead of a file descriptor you need to pass a pointer to a struct jfs (just
-like jopen() and jclose()). Again, I will not duplicate the manpage for all
-these functions, just refer to the regular UNIX versions to see how to use
-them, they all have the same semantics and behave the same way.
+instead of a file descriptor you need to pass a pointer to a
+.IR "struct jfs" .
+Again, I will not duplicate the manpage for all these functions, just refer to
+the regular UNIX versions to see how to use them, they all have the same
+semantics and behave the same way.
 
-.SH Basic functions
+.SS BASIC FUNCTIONS
 
 The basic functions are the ones which manipulate transactions directly; they
-are five: jtrans_init(), jtrans_add(), jtrans_commit(), jtrans_rollback() and
-jtrans_free(). These are intended to be use in special situations where your
-application needs direct control over the transactions.
-
-jtrans_init() and jtrans_free() just initialize and free a given transaction,
-the former should be called prior any use, and the latter when you want to
-destroy a transaction. Note that jtrans_free() is not a disk operation, but
-only frees the pointers that were previously allocated by the library; all
-disk operations are performed by the other two functions. They have no return
-value.
-
-jtrans_add() is used to add operations to a transaction, and it takes the same
-parameters as the pwrite() call. It gets a buffer, it's lenght and the offset
-where it should be applied, and adds it to the transaction. You can add
-multiple operations to a transaction, and they will be applied in order.
-Operation within the same transaction must not overlap; if they do, commiting
-the transaction will fail.
-
-jtrans_commit() is in charge of commiting the given transaction, and after its
-return the data has been saved to the disk atomically. It returns the number
-of bytes written or -1 if there was an error.
-
-jtrans_rollback() reverses a transaction that was applied with
-jtrans_commit(), and leaves the file as it was before applying it. Be very
-very careful with this function, it's quite dangerous if you don't know for
-sure that you're doing the right thing. It returns as jtrans_commit().
-
-.SH BUGS
-
-None that I'm aware of, but if you find one please let me know at
-albertito@blitiri.com.ar.
+are five:
+.BR jtrans_init() ", " jtrans_add() ", " jtrans_commit() ", " jtrans_rollback()
+and
+.BR jtrans_free() .
+These are intended to be use where your application requires direct control
+over the transactions.
+
+.BR jtrans_init() " and " jtrans_free()
+just initialize and free a given transaction; the former should be called
+prior any use, and the latter when you want to destroy a transaction. Note
+that
+.B jtrans_free()
+is not a disk operation, but only frees the pointers that were previously
+allocated by the library; all disk operations are performed by the other two
+functions.
+
+.B jtrans_add()
+is used to add operations to a transaction, and it takes the same parameters
+as
+.BR pwrite() .
+It gets a buffer, its lenght and the offset where it should be applied, and
+adds it to the transaction. You can add multiple operations to a transaction,
+and they will be applied in order.
+
+.B jtrans_commit()
+commits the given transaction to disk. After it has returned, data has been
+saved to the disk. It returns the number of bytes written or -1 if there was
+an error. The commit operation is atomic with regards to other read or write
+operations on different processes, as long as they all access it via libjio.
+
+.B jtrans_rollback()
+reverses a transaction that was applied with
+.BR jtrans_commit() ,
+and leaves the file as it was before applying it. Be very very careful with
+this function, it's quite dangerous if you don't know for sure that you're
+doing the right thing. It returns the number of bytes written or -1 if there
+was an error.
 
 .SH SEE ALSO
 
@@ -193,3 +203,10 @@ albertito@blitiri.com.ar.
 .BR pwrite (2),
 .BR ftruncate (2),
 .BR close (2)
+
+.SH BUGS
+
+None that I'm aware of, but if you find one please let me know at
+If you want to report bugs, or have any questions or comments, just let me
+know at albertito@blitiri.com.ar.
+
diff --git a/doc/libjio.html b/doc/libjio.html
deleted file mode 100644
index e43e1d8..0000000
--- a/doc/libjio.html
+++ /dev/null
@@ -1,444 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-
-<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
-original version by:  Nikos Drakos, CBLU, University of Leeds
-* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
-* with significant contributions from:
-  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-<HTML>
-<HEAD>
-<TITLE>libjio - A library for journaled I/O </TITLE>
-<META NAME="description" CONTENT="libjio - A library for journaled I/O ">
-<META NAME="keywords" CONTENT="libjio">
-<META NAME="resource-type" CONTENT="document">
-<META NAME="distribution" CONTENT="global">
-
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
-<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
-<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
-
-<LINK REL="STYLESHEET" HREF="libjio.css">
-
-</HEAD>
-
-<BODY >
-<!--Navigation Panel-->
-<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
- SRC="file:/usr/lib/latex2html/icons/nx_grp_g.png"> 
-<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
- SRC="file:/usr/lib/latex2html/icons/up_g.png"> 
-<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
- SRC="file:/usr/lib/latex2html/icons/prev_g.png">   
-<BR>
-<BR>
-<BR>
-<!--End of Navigation Panel-->
-
-<P>
-
-<P>
-
-<P>
-<H1 ALIGN="CENTER">libjio - A library for journaled I/O </H1>
-<DIV>
-
-<P ALIGN="CENTER"><STRONG>Alberto Bertogli (albertito@blitiri.com.ar) </STRONG></P>
-</DIV>
-<BR>
-
-<H2><A NAME="SECTION00010000000000000000">
-Contents</A>
-</H2>
-<!--Table of Contents-->
-
-<UL>
-<LI><A NAME="tex2html12"
-  HREF="libjio.html#SECTION00020000000000000000">1 Introduction</A>
-<LI><A NAME="tex2html13"
-  HREF="libjio.html#SECTION00030000000000000000">2 General on-disk data organization</A>
-<UL>
-<LI><A NAME="tex2html14"
-  HREF="libjio.html#SECTION00031000000000000000">2.1 The transaction file</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html15"
-  HREF="libjio.html#SECTION00040000000000000000">3 The commit procedure</A>
-<LI><A NAME="tex2html16"
-  HREF="libjio.html#SECTION00050000000000000000">4 The rollback procedure</A>
-<LI><A NAME="tex2html17"
-  HREF="libjio.html#SECTION00060000000000000000">5 The recovery procedure</A>
-<LI><A NAME="tex2html18"
-  HREF="libjio.html#SECTION00070000000000000000">6 High-level functions</A>
-<LI><A NAME="tex2html19"
-  HREF="libjio.html#SECTION00080000000000000000">7 ACID (or How does libjio fit into theory)</A>
-<LI><A NAME="tex2html20"
-  HREF="libjio.html#SECTION00090000000000000000">8 Working from outside</A>
-</UL>
-<!--End of Table of Contents-->
-
-<P>
-
-<H1><A NAME="SECTION00020000000000000000">
-1 Introduction</A>
-</H1>
-
-<P>
-<I>libjio</I> is a library for doing journaled transaction-oriented
-I/O, providing atomicity warantees and a simple to use but powerful
-API.
-
-<P>
-This document explains the design of the library, how it works internally
-and why it works that way. You should read it even if you don't plan
-to do use the library in strange ways, it provides (or at least tries
-to =) an insight view on how the library performs its job, which can
-be very valuable knowledge when working with it.
-
-<P>
-To the user, libjio provides two groups of functions, one UNIX-alike
-that implements the journaled versions of the classic functions (<I>open()</I>,
-<I>read()</I>, <I>write()</I> and friends); and a lower-level one
-that center on transactions and allows the user to manipulate them
-directly by providing means of commiting and rollbacking. The former,
-as expected, are based on the latter and interact safely with them.
-Besides, it's designed in a way that allows efficient and safe interaction
-with I/O performed from outside the library in case you want to.
-
-<P>
-The following sections describe different concepts and procedures
-that the library bases its work on. It's not intended to be a replace
-to reading the source code: please do so if you have any doubts, it's
-not big at all (less than 800 lines, including comments) and I hope
-it's readable enough. If you think that's not the case, please let
-me know and I'll try to give you a hand.
-
-<P>
-
-<H1><A NAME="SECTION00030000000000000000">
-2 General on-disk data organization</A>
-</H1>
-
-<P>
-On the disk, the file you are working on will look exactly as you
-expect and hasn't got a single bit different that what you would get
-using the regular API. But, besides the working file, you will find
-a directory named after it where the journaling information lives. 
-
-<P>
-Inside, there are two kind of files: the lock file and transaction
-files. The first one is used as a general lock and holds the next
-transaction ID to assign, and there is only one; the second one holds
-one transaction, which is composed by a header of fixed size and a
-variable-size payload, and can be as many as in-flight transactions. 
-
-<P>
-This impose some restrictions to the kind of operations you can perform
-over a file while it's currently being used: you can't move it (because
-the journal directory name depends on the filename) and you can't
-unlink it (for similar reasons). 
-
-<P>
-This warnings are no different from a normal simultaneous use under
-classic UNIX environments, but they are here to remind you that even
-tho the library warantees a lot and eases many things from its user
-(specially from complex cases, like multiple threads using the file
-at the same time), you should still be careful when doing strange
-things with files while working on them. 
-
-<P>
-
-<H2><A NAME="SECTION00031000000000000000">
-2.1 The transaction file</A>
-</H2>
-
-<P>
-The transaction file is composed of two main parts: the header and
-the payload.
-
-<P>
-The header holds basic information about the transaction itself, including
-the ID, some flags, the offset to commit to and the lenght of the
-data. The payload holds the data, in three parts: user-defined data,
-previous data, and real data.
-
-<P>
-User-defined data is not used by the library itself, but it's a space
-where the user can save private data that can be useful later. Previous
-data is saved by the library prior applying the commit, so transactions
-can be rollbacked. Real data is just the data to save to the disk,
-and it is saved because if a crash occurs when while we are applying
-the transaction we can recover gracefuly.
-
-<P>
-
-<H1><A NAME="SECTION00040000000000000000">
-3 The commit procedure</A>
-</H1>
-
-<P>
-We call &#34;commit&#34; to the action of <I>safely</I>
-and <I>atomically</I> write some given data to the disk.
-
-<P>
-The former, <I>safely</I>, means that after a commit has been done
-we can assume the data will not get lost and can be retrieved, unless
-of course some major event happens (like a hardware failure). For
-us, this means that the data was effectively written to the disk and
-if a crash occurs after the commit operation has returned, the operation
-will be complete and data will be available from the file.
-
-<P>
-The latter, <I>atomically</I>, warantees that the operation is either
-completely done, or not done at all. This is a really common word,
-specially if you have worked with multiprocessing, and should be quite
-familiar. We implement atomicity by combining fine-grained locks and
-journaling, which can assure us both to be able to recover from crashes,
-and to have exclusive access to a portion of the file without having
-any other transaction overlap it.
-
-<P>
-Well, so much for talking, now let's get real; libjio applies commits
-in a very simple and straightforward way, inside <I>jtrans_commit()</I>:
-
-<P>
-
-<UL>
-<LI>Lock the section where the commit takes place
-</LI>
-<LI>Open the transaction file
-</LI>
-<LI>Write the header
-</LI>
-<LI>Write the user data (if any)
-</LI>
-<LI>Read the previous data from the file
-</LI>
-<LI>Write the previous data in the transaction
-</LI>
-<LI>Write the data to the file
-</LI>
-<LI>Mark the transaction as commited by setting a flag in the header
-</LI>
-<LI>Unlink the transaction file
-</LI>
-<LI>Unlock the section where the commit takes place
-</LI>
-</UL>
-This may look as a lot of steps, but they're not as much as it looks
-like inside the code, and allows a recovery from interruptions in
-every step of the way (or even in the middle of a step).
-
-<P>
-
-<H1><A NAME="SECTION00050000000000000000">
-4 The rollback procedure</A>
-</H1>
-
-<P>
-First of all, rollbacking is like ``undo'' a commit: return the
-data to the state it had exactly before a given commit was applied.
-Due to the way we handle commits, doing this operation becomes quite
-simple and straightforward.
-
-<P>
-In the previous section we said that each transaction held, besides
-the data to commit to the disk, the data that was on it before commiting.
-That data is saved precisely to be able to rollback. So, to rollback
-a transaction all that has to be done is recover that ``previous
-data'' from the transaction we want to rollback, and save it to the
-disk. In the end, this ends up being a new transaction with the previous
-data as the new one, so we do that: create a new transaction structure,
-fill in the data from the transaction we want to rollback, and commit
-it. All this is performed by <I>jtrans_rollback()</I>.
-
-<P>
-By doing this we can provide the same warranties a commit has, it's
-really fast, eases the recovery, and the code is simple and clean.
-What a deal.
-
-<P>
-But be aware that rollbacking is dangerous. And I really mean it:
-you should <B><I>only</I></B> do it if you're really sure it's ok.
-Consider, for instance, that you commit transaction A, then B, and
-then you rollback A. If A and B happen to touch the same portion of
-the file, the rollback will, of course, not return the state previous
-to B, but previous to A. If it's not done safely, this can lead to
-major corruption. Now, if you add to this transactions that extend
-the file (and thus rollbacking truncates it back), you not only have
-corruption but data loss. So, again, be aware, I can't stress this
-enough, <B><I>rollback only if you really really know what
-you are doing</I></B>.
-
-<P>
-
-<H1><A NAME="SECTION00060000000000000000">
-5 The recovery procedure</A>
-</H1>
-
-<P>
-Recovering from crashes is done by the <I>jfsck()</I> call (or the
-program <I>jiofsck</I> which is just a simple invocation to that function),
-which opens the file and goes through all transactions in the journal
-(remember that transactions are removed from the journal directory
-after they're applied), loading and rollbacking them if necessary.
-There are several steps where it can fail: there could be no journal,
-a given transaction file might be corrupted, incomplete, and so on;
-but in the end, there are two cases regarding each transaction: either
-it's complete and can be rollbacked, or not.
-
-<P>
-In the case the transaction is not complete, there is no possibility
-that it has been partially applied to the disk, remember that, from
-the commit procedure, we only apply the transaction <I>after</I> saving
-it in the journal, so there is really nothing left to be done. So
-if the transaction is complete, we only need to rollback.
-
-<P>
-In any case, after making the recovery you can simply remove the journal
-entirely and let the library create a new one, and you can be sure
-that transaction atomicity was preserved.
-
-<P>
-
-<H1><A NAME="SECTION00070000000000000000">
-6 High-level functions</A>
-</H1>
-
-<P>
-We call <I>high-level functions</I> to the ones provided by the library
-that emulate the good old unix file manipulation calls. Most of them
-are just wrappers around commits, and implement proper locking when
-operating in order to allow simultaneous operations (either across
-threads or processes). They are described in detail in the manual
-pages, we'll only list them here for completion:
-
-<P>
-
-<UL>
-<LI>jopen()
-</LI>
-<LI>jread(), jpread(), jreadv()
-</LI>
-<LI>jwrite(), jpwrite(), jwritev()
-</LI>
-<LI>jtruncate()
-</LI>
-<LI>jclose()
-</LI>
-</UL>
-
-<P>
-
-<H1><A NAME="SECTION00080000000000000000">
-7 ACID (or How does libjio fit into theory)</A>
-</H1>
-
-<P>
-I haven't read much theory about this, and the library was implemented
-basically by common sense and not theorethical study. 
-
-<P>
-However, I'm aware that database people like ACID (well, that's not
-news for anybody ;), which they say mean &#34;Atomicity, Consistency,
-Isolation, Durability&#34; (yeah, right!). 
-
-<P>
-So, even libjio is not a purely database thing, it can be used to
-achieve those attributes in a simple and efficient way. 
-
-<P>
-Let's take a look one by one:
-
-<P>
-
-<UL>
-<LI>Atomicity: In a transaction involving two or more discrete pieces
-of information, either all of the pieces are committed or none are.
-This has been talked before and we've seen how the library achieves
-this point, mostly based on locks and relying on a commit procedure.
-</LI>
-<LI>Consistency: A transaction either creates a new and valid state of
-data, or, if any failure occurs, returns all data to its state before
-the transaction was started. This, like atomicity, has been discussed
-before, specially in the recovery section, when we saw how in case
-of a crash we end up with a fully applied transaction, or no transaction
-applied at all.
-</LI>
-<LI>Isolation: A transaction in process and not yet committed must remain
-isolated from any other transaction. This comes as a side effect of
-doing proper locking on the sections each transaction affect, and
-guarantees that there can't be two transactions working on the same
-section at the same time.
-</LI>
-<LI>Durability: Committed data is saved by the system such that, even
-in the event of a failure and system restart, the data is available
-in its correct state. For this point we rely on the disk as a method
-of permanent storage, and expect that when we do syncronous I/O, data
-is safely written and can be recovered after a crash.
-</LI>
-</UL>
-
-<P>
-
-<H1><A NAME="SECTION00090000000000000000">
-8 Working from outside</A>
-</H1>
-
-<P>
-If you want, and are careful enough, you can safely do I/O without
-using the library. Here I'll give you some general guidelines that
-you need to follow in order to prevent corruption. Of course you can
-bend or break them according to your use, this is just a general overview
-on how to interact from outside. 
-
-<P>
-
-<UL>
-<LI>Lock the sections you want to use: the library, as we have already
-exposed, relies on fcntl locking; so, if you intend to operate on
-parts on the file while using it, you should lock them. 
-</LI>
-<LI>Don't tuncate, unlink or rename: these operations have serious implications
-when they're done while using the library, because the library itself
-assumes that names don't change, and files don't dissapear beneath
-it. It could potentially lead to corruption, although most of the
-time you would just get errors from every call.
-</LI>
-</UL>
-
-<P>
-
-<H1><A NAME="SECTION000100000000000000000">
-About this document ...</A>
-</H1>
- <STRONG>libjio - A library for journaled I/O </STRONG><P>
-This document was generated using the
-<A HREF="http://www.latex2html.org/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2002-2-1 (1.70)
-<P>
-Copyright &#169; 1993, 1994, 1995, 1996,
-<A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>, 
-Computer Based Learning Unit, University of Leeds.
-<BR>
-Copyright &#169; 1997, 1998, 1999,
-<A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>, 
-Mathematics Department, Macquarie University, Sydney.
-<P>
-The command line arguments were: <BR>
- <STRONG>latex2html</STRONG> <TT>-no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir2441q5CgGo/lyx_tmpbuf0/libjio.tex</TT>
-<P>
-The translation was initiated by root on 2004-04-30<HR>
-<!--Navigation Panel-->
-<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
- SRC="file:/usr/lib/latex2html/icons/nx_grp_g.png"> 
-<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
- SRC="file:/usr/lib/latex2html/icons/up_g.png"> 
-<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
- SRC="file:/usr/lib/latex2html/icons/prev_g.png">   
-<BR>
-<!--End of Navigation Panel-->
-<ADDRESS>
-root
-2004-04-30
-</ADDRESS>
-</BODY>
-</HTML>
diff --git a/doc/libjio.lyx b/doc/libjio.lyx
deleted file mode 100644
index cfa8df0..0000000
--- a/doc/libjio.lyx
+++ /dev/null
@@ -1,433 +0,0 @@
-#LyX 1.3 created this file. For more info see http://www.lyx.org/
-\lyxformat 221
-\textclass article
-\language english
-\inputencoding auto
-\fontscheme default
-\graphics default
-\paperfontsize default
-\papersize Default
-\paperpackage a4
-\use_geometry 0
-\use_amsmath 0
-\use_natbib 0
-\use_numerical_citations 0
-\paperorientation portrait
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\defskip medskip
-\quotes_language english
-\quotes_times 2
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-
-\layout Title
-
-libjio - A library for journaled I/O 
-\layout Author
-
-Alberto Bertogli (albertito@blitiri.com.ar)
-\layout Standard
-
-
-\begin_inset LatexCommand \tableofcontents{}
-
-\end_inset 
-
-
-\layout Section
-
-Introduction
-\layout Standard
-
-
-\emph on 
-libjio
-\emph default 
- is a library for doing journaled transaction-oriented I/O, providing atomicity
- warantees and a simple to use but powerful API.
-\layout Standard
-
-This document explains the design of the library, how it works internally
- and why it works that way.
- You should read it even if you don't plan to do use the library in strange
- ways, it provides (or at least tries to =) an insight view on how the library
- performs its job, which can be very valuable knowledge when working with
- it.
- It assumes that there is some basic knowledge about how the library is
- used, which can be found in the manpage or in the programmer's guide.
-\layout Standard
-
-To the user, libjio provides two groups of functions, one UNIX-alike that
- implements the journaled versions of the classic functions (
-\emph on 
-open()
-\emph default 
-, 
-\emph on 
-read()
-\emph default 
-, 
-\emph on 
-write()
-\emph default 
- and friends); and a lower-level one that center on transactions and allows
- the user to manipulate them directly by providing means of commiting and
- rollbacking.
- The former, as expected, are based on the latter and interact safely with
- them.
- Besides, it's designed in a way that allows efficient and safe interaction
- with I/O performed from outside the library in case you want to.
-\layout Standard
-
-The following sections describe different concepts and procedures that the
- library bases its work on.
- It's not intended to be a replace to reading the source code: please do
- so if you have any doubts, it's not big at all (less than 1500 lines, including
- comments) and I hope it's readable enough.
- If you think that's not the case, please let me know and I'll try to give
- you a hand.
-\layout Section
-
-General on-disk data organization
-\layout Standard
-
-On the disk, the file you are working on will look exactly as you expect
- and hasn't got a single bit different that what you would get using the
- regular API.
- But, besides the working file, you will find a directory named after it
- where the journaling information lives.
- 
-\layout Standard
-
-Inside, there are two kind of files: the lock file and transaction files.
- The first one is used as a general lock and holds the next transaction
- ID to assign, and there is only one; the second one holds one transaction,
- which is composed by a header of fixed size and a variable-size payload,
- and can be as many as in-flight transactions.
- 
-\layout Standard
-
-This impose some restrictions to the kind of operations you can perform
- over a file while it's currently being used: you can't move it (because
- the journal directory name depends on the filename) and you can't unlink
- it (for similar reasons).
- 
-\layout Standard
-
-This warnings are no different from a normal simultaneous use under classic
- UNIX environments, but they are here to remind you that even tho the library
- warantees a lot and eases many things from its user (specially from complex
- cases, like multiple threads using the file at the same time), you should
- still be careful when doing strange things with files while working on
- them.
- 
-\layout Subsection
-
-The transaction file
-\layout Standard
-
-The transaction file is composed of two main parts: the header and the payload.
-\layout Standard
-
-The header holds basic information about the transaction itself, including
- the ID, some flags, and the amount of operations it includes.
- Then the payload has all the operations one after the other, divided in
- two parts: the first one includes static information about the operation
- (the lenght of the data, the offset of the file where it should be applied,
- etc.) and the data itself, which is saved by the library prior applying
- the commit, so transactions can be rollbacked.
-\layout Section
-
-The commit procedure
-\layout Standard
-
-We call "commit" to the action of 
-\emph on 
-safely
-\emph default 
- and 
-\emph on 
-atomically
-\emph default 
- write some given data to the disk.
-\layout Standard
-
-The former, 
-\emph on 
-safely
-\emph default 
-, means that after a commit has been done we can assume the data will not
- get lost and can be retrieved, unless of course some major event happens
- (like a physical hard disk crash).
- For us, this means that the data was effectively written to the disk and
- if a crash occurs after the commit operation has returned, the operation
- will be complete and data will be available from the file.
-\layout Standard
-
-The latter, 
-\emph on 
-atomically
-\emph default 
-, guarantees that the operation is either completely done, or not done at
- all.
- This is a really common word, specially if you have worked with multiprocessing
-, and should be quite familiar.
- We implement atomicity by combining fine-grained locks and journaling,
- which can assure us both to be able to recover from crashes, and to have
- exclusive access to a portion of the file without having any other transaction
- overlap it.
-\layout Standard
-
-Well, so much for talking, now let's get real; libjio applies commits in
- a very simple and straightforward way, inside 
-\emph on 
-jtrans_commit()
-\emph default 
-:
-\layout Itemize
-
-Lock the file offsets where the commit takes place
-\layout Itemize
-
-Open the transaction file
-\layout Itemize
-
-Write the header
-\layout Itemize
-
-Read all the previous data from the file
-\layout Itemize
-
-Write the previous data in the transaction
-\layout Itemize
-
-Write the data to the file
-\layout Itemize
-
-Mark the transaction as commited by setting a flag in the header
-\layout Itemize
-
-Unlink the transaction file
-\layout Itemize
-
-Unlock the offsets where the commit takes place
-\layout Standard
-
-This may look as a lot of steps, but they're not as much as it looks like
- inside the code, and allows a recovery from interruptions in every step
- of the way (or even in the middle of a step).
-\layout Section
-
-The rollback procedure
-\layout Standard
-
-First of all, rollbacking is like 
-\begin_inset Quotes eld
-\end_inset 
-
-undo
-\begin_inset Quotes erd
-\end_inset 
-
- a commit: return the data to the state it had exactly before a given commit
- was applied.
- Due to the way we handle commits, doing this operation becomes quite simple
- and straightforward.
-\layout Standard
-
-In the previous section we said that each transaction held the data that
- was on it before commiting.
- That data is saved precisely to be able to rollback.
- So, to rollback a transaction all that has to be done is recover that 
-\begin_inset Quotes eld
-\end_inset 
-
-previous data
-\begin_inset Quotes erd
-\end_inset 
-
- from the transaction we want to rollback, and save it to the disk.
- In the end, this ends up being a new transaction with the previous data
- as the new one, so we do that: create a new transaction structure, fill
- in the data from the transaction we want to rollback, and commit it.
- All this is performed by 
-\emph on 
-jtrans_rollback()
-\emph default 
-.
-\layout Standard
-
-By doing this we can provide the same warranties a commit has, it's really
- fast, eases the recovery, and the code is simple and clean.
- What a deal.
-\layout Standard
-
-But be aware that rollbacking is dangerous.
- And I really mean it: you should 
-\series bold 
-\emph on 
-only
-\series default 
-\emph default 
- do it if you're really sure it's ok.
- Consider, for instance, that you commit transaction A, then B, and then
- you rollback A.
- If A and B happen to touch the same portion of the file, the rollback will,
- of course, not return the state previous to B, but previous to A.
- If it's not done safely, this can lead to major corruption.
- Now, if you add to this transactions that extend the file (and thus rollbacking
- truncates it back), you not only have corruption but data loss.
- So, again, be aware, I can't stress this enough, 
-\series bold 
-\emph on 
-rollback only if you really really know what you are doing
-\series default 
-\emph default 
-.
-\layout Section
-
-The recovery procedure
-\layout Standard
-
-Recovering from crashes is done by the 
-\emph on 
-jfsck()
-\emph default 
- call (or the program 
-\emph on 
-jiofsck
-\emph default 
- which is just a simple invocation to that function), which opens the file
- and goes through all transactions in the journal (remember that transactions
- are removed from the journal directory after they're applied), loading
- and rollbacking them if necessary.
- There are several steps where it can fail: there could be no journal, a
- given transaction file might be corrupted, incomplete, and so on; but in
- the end, there are two cases regarding each transaction: either it's complete
- and can be rollbacked, or not.
-\layout Standard
-
-In the case the transaction is not complete, there is no possibility that
- it has been partially applied to the disk, remember that, from the commit
- procedure, we only apply the transaction 
-\emph on 
-after
-\emph default 
- saving it in the journal, so there is really nothing left to be done.
- So if the transaction is complete, we only need to rollback.
-\layout Standard
-
-In any case, after making the recovery you can simply remove the journal
- entirely and let the library create a new one, and you can be sure that
- transaction atomicity was preserved.
-\layout Section
-
-UNIX API
-\layout Standard
-
-We call 
-\emph on 
-UNIX API
-\emph default 
- to the functions provided by the library that emulate the good old UNIX
- file manipulation calls.
- Most of them are just wrappers around commits, and implement proper locking
- when operating in order to allow simultaneous operations (either across
- threads or processes).
- They are described in detail in the manual pages, we'll only list them
- here for completion:
-\layout Itemize
-
-jopen()
-\layout Itemize
-
-jread(), jpread(), jreadv()
-\layout Itemize
-
-jwrite(), jpwrite(), jwritev()
-\layout Itemize
-
-jtruncate()
-\layout Itemize
-
-jclose()
-\layout Section
-
-ACID (or How does libjio fit into theory)
-\layout Standard
-
-I haven't read much theory about this, and the library was implemented basically
- by common sense and not theorethical study.
- 
-\layout Standard
-
-However, I'm aware that database people like ACID (well, that's not news
- for anybody ;), which they say mean "Atomicity, Consistency, Isolation,
- Durability" (yeah, right!).
- 
-\layout Standard
-
-So, even libjio is not a purely database thing, it can be used to achieve
- those attributes in a simple and efficient way.
- 
-\layout Standard
-
-Let's take a look one by one:
-\layout Itemize
-
-Atomicity: In a transaction involving two or more discrete pieces of information
-, either all of the pieces are committed or none are.
- This has been talked before and we've seen how the library achieves this
- point, mostly based on locks and relying on a commit procedure.
-\layout Itemize
-
-Consistency: A transaction either creates a new and valid state of data,
- or, if any failure occurs, returns all data to its state before the transaction
- was started.
- This, like atomicity, has been discussed before, specially in the recovery
- section, when we saw how in case of a crash we end up with a fully applied
- transaction, or no transaction applied at all.
-\layout Itemize
-
-Isolation: A transaction in process and not yet committed must remain isolated
- from any other transaction.
- This comes as a side effect of doing proper locking on the sections each
- transaction affect, and guarantees that there can't be two transactions
- working on the same section at the same time.
-\layout Itemize
-
-Durability: Committed data is saved by the system such that, even in the
- event of a failure and system restart, the data is available in its correct
- state.
- For this point we rely on the disk as a method of permanent storage, and
- expect that when we do syncronous I/O, data is safely written and can be
- recovered after a crash.
-\layout Section
-
-Working from outside
-\layout Standard
-
-If you want, and are careful enough, you can safely do I/O without using
- the library.
- Here I'll give you some general guidelines that you need to follow in order
- to prevent corruption.
- Of course you can bend or break them according to your use, this is just
- a general overview on how to interact from outside.
- 
-\layout Itemize
-
-Lock the sections you want to use: the library, as we have already exposed,
- relies on fcntl locking; so, if you intend to operate on parts on the file
- while using it, you should lock them.
- 
-\layout Itemize
-
-Don't tuncate, unlink or rename: these operations have serious implications
- when they're done while using the library, because the library itself assumes
- that names don't change, and files don't dissapear beneath it.
- It could potentially lead to corruption, although most of the time you
- would just get errors from every call.
-\the_end
diff --git a/doc/libjio.rst b/doc/libjio.rst
new file mode 100644
index 0000000..32de123
--- /dev/null
+++ b/doc/libjio.rst
@@ -0,0 +1,244 @@
+
+libjio - A library for journaled I/O
+======================================
+
+Introduction
+------------
+
+libjio is a library for doing journaled, transaction-oriented I/O, providing
+atomicity warantees and a simple to use but powerful API.
+
+This document explains the design of the library, how it works internally and
+why it works that way. You should read it even if you don't plan to do use the
+library in strange ways, it provides (or at least tries to) an insight view on
+how the library performs its job, which can be very valuable knowledge when
+working with it. It assumes that there is some basic knowledge about how the
+library is used, which can be found in the manpage or in the programmer's
+guide.
+
+To the user, libjio provides two groups of functions, one UNIX-alike that
+implements the journaled versions of the classic functions (open(), read(),
+write() and friends); and a lower-level one that center on transactions and
+allows the user to manipulate them directly by providing means of commiting
+and rollbacking. The former, as expected, are based on the latter and interact
+safely with them. Besides, it's designed in a way that allows efficient and
+safe interaction with I/O performed from outside the library in case you want
+to.
+
+The following sections describe different concepts and procedures that the
+library bases its work on. It's not intended to be a replace to reading the
+source code: please do so if you have any doubts, it's not big at all (less
+than 1500 lines, including comments) and I hope it's readable enough. If you
+think that's not the case, please let me know and I'll try to give you a hand.
+
+
+General on-disk data organization
+---------------------------------
+
+On the disk, the file you are working on will look exactly as you expect and
+hasn't got a single bit different that what you would get using the regular
+UNIX API. But, besides the working file, you will find a directory named after
+it where the journaling information lives.
+
+Inside, there are two kind of files: the lock file and transaction files. The
+first one is used as a general lock and holds the next transaction ID to
+assign, and there is only one; the second one holds one transaction, which is
+composed by a header of fixed size and a variable-size payload, and can be as
+many as in-flight transactions.
+
+This impose some restrictions to the kind of operations you can perform over a
+file while it's currently being used: you can't move it (because the journal
+directory name depends on the filename) and you can't unlink it (for similar
+reasons).
+
+This warnings are no different from a normal simultaneous use under classic
+UNIX environments, but they are here to remind you that even tho the library
+warranties a lot and eases many things from its user, you should still be
+careful when doing strange things with files while working on them.
+
+The transaction file
+~~~~~~~~~~~~~~~~~~~~
+
+The transaction file is composed of two main parts: the header and the
+payload.
+
+The header holds basic information about the transaction itself, including the
+ID, some flags, and the amount of operations it includes. Then the payload has
+all the operations one after the other, divided in two parts: the first one
+includes static information about the operation (the length of the data, the
+offset of the file where it should be applied, etc.) and the data itself,
+which is saved by the library prior applying the commit, so transactions can
+be rollbacked.
+
+At the end of the transaction file, a checksum is stored, to detect journal
+corruption.
+
+
+The commit procedure
+--------------------
+
+We call *commit* to the action of safely and atomically write some given data
+to the disk.
+
+The former, "safely", means that after a commit has been done we can assume
+the data will not get lost and can be retrieved, unless of course some major
+event happens (like a physical hard disk crash). For us, this means that the
+data was effectively written to the disk and if a crash occurs after the
+commit operation has returned, the operation will be complete and data will be
+available from the file.
+
+The latter, "atomically", guarantees that the operation is either completely
+done, or not done at all. This is a really common word, specially if you have
+worked with multiprocessing, and should be quite familiar. We implement
+atomicity by combining fine-grained locks and journaling, which can assure us
+both to be able to recover from crashes, and to have exclusive access to a
+portion of the file without having any other transaction overlap it.
+
+Well, so much for talking, now let's get real; libjio applies commits in a
+very simple and straightforward way, inside jtrans_commit():
+
+ - Lock the file offsets where the commit takes place
+ - Open the transaction file
+ - Write the header
+ - Read all the previous data from the file
+ - Write the previous data in the transaction
+ - Write the data to the file
+ - Mark the transaction as committed by setting a flag in the header
+ - Unlink the transaction file
+ - Unlock the offsets where the commit takes place
+
+This may seem like a lot of steps, but they're not as much as it looks like
+inside the code, and allows a recovery from interruptions in every step of the
+way, and even in the middle of a step.
+
+
+The rollback procedure
+----------------------
+
+First of all, rollbacking is like "undo" a commit: returns the data to the
+state it had exactly before a given commit was applied. Due to the way we
+handle commits, doing this operation becomes quite simple and straightforward.
+
+In the previous section we said that each transaction held the data that was
+on it before commiting. That data saved is precisely the one we need to be
+able to rollback.
+
+So, to rollback a transaction all that has to be done is recover the
+previous data from the transaction we want to rollback, and save it to the
+disk. In the end, this ends up being a new transaction with the previous data
+as the new one, and that's how it's done: create a new transaction structure,
+fill in the data from the transaction we want to rollback, and commit it. All
+this is performed by jtrans_rollback().
+
+By doing this we can provide the same warranties a commit has, it's really
+fast, eases the recovery, and the code is simple and clean. What a deal.
+
+But be aware that rollbacking is dangerous. And I really mean it: you should
+only do it if you're really sure it's ok. Consider, for instance, that you
+commit transaction A, then B, and then you rollback A. If A and B happen to
+touch the same portion of the file, the rollback will, of course, not return
+the state previous to B, but previous to A.
+
+If it's not done safely, this can lead to major corruption. Now, if you add to
+this transactions that extend the file (and thus rollbacking truncates it
+back), it gets even worse. So, again, be aware, I can't stress this enough,
+rollback only if you really really know what you are doing.
+
+
+The recovery procedure
+----------------------
+
+Recovering from crashes is done by the jfsck() call (or the program *jiofsck*
+which is just a simple invocation to that function), which opens the file and
+goes through all transactions in the journal (remember that transactions are
+removed from the journal directory after they're applied), loading and
+rollbacking them if necessary. There are several steps where it can fail:
+there could be no journal, a given transaction file might be corrupted,
+incomplete, and so on; but in the end, there are two cases regarding each
+transaction: either it's complete and can be rollbacked, or not.
+
+In the case the transaction file was not completely written, there is no
+possibility that it has been partially applied to the disk: remember that,
+from the commit procedure, we only apply the transaction after saving it in
+the journal, so there is really nothing left to be done. So if the transaction
+is complete, we only need to rollback.
+
+In any case, after making the recovery you can simply remove the journal
+entirely and let the library create a new one, and you can be sure that
+transaction atomicity was preserved. You can use jfsck_cleanup() for that
+purpose.
+
+
+UNIX-alike API
+--------------
+
+We call UNIX-alike API to the functions provided by the library that emulate
+the good old UNIX file manipulation calls. Most of them are just wrappers
+around commits, and implement proper locking when operating in order to allow
+simultaneous operations (either across threads or processes). They are
+described in detail in the manual pages, we'll only list them here for
+completion:
+
+ - jopen()
+ - jread(), jpread(), jreadv()
+ - jwrite(), jpwrite(), jwritev()
+ - jtruncate()
+ - jclose()
+
+
+ACID warranties
+---------------
+
+Database people like ACID (well, that's not news for anybody), which they say
+mean "Atomicity, Consistency, Isolation, Durability".
+
+So, even when libjio is not a purely database thing, its transactions provide
+those properties. Let's take a look one by one:
+
+Atomicity
+  In a transaction involving two or more discrete pieces of information,
+  either all of the pieces are committed or none are. This has been talked
+  before and we've seen how the library achieves this point, mostly based on
+  locks and relying on a commit procedure.
+
+Consistency
+  A transaction either creates a new and valid state of data, or, if any
+  failure occurs, returns all data to its state before the transaction was
+  started. This, like atomicity, has been discussed before, specially in the
+  recovery section, when we saw how in case of a crash we end up with a fully
+  applied transaction, or no transaction applied at all.
+
+Isolation
+  A transaction in process and not yet committed must remain isolated from any
+  other transaction. This comes as a side effect of doing proper locking on
+  the sections each transaction affect, and guarantees that there can't be two
+  transactions working on the same section at the same time.
+
+Durability
+  Committed data is saved by the system such that, even in the event of a
+  failure, the data is available in a correct state. To provide this, libjio
+  relies on the disk as a method of permanent storage, and expects that when
+  it does syncronous I/O, data is safely written and can be recovered after a
+  crash.
+
+
+Working from outside
+--------------------
+
+If you want, and are careful enough, you can safely use the library and still
+do I/O using the regular UNIX calls.
+
+This section provides some general guidelines that you need to follow in order
+to prevent corruption. Of course you can bend or break them according to your
+use, this is just a general overview on how to interact from outside.
+
+ - Lock the sections you want to use: the library, as we have already exposed,
+   relies on fcntl() locking; so, if you intend to operate on parts on the
+   file while using it, you should lock them.
+ - Don't truncate, unlink or rename: these operations have serious
+   implications when they're done while using the library, because the library
+   itself assumes that names don't change, and files don't disappear from
+   underneath it. It could potentially lead to corruption, although most of
+   the time you would just get errors from every call.
+
+
diff --git a/doc/libjio.txt b/doc/libjio.txt
deleted file mode 100644
index 10797f8..0000000
--- a/doc/libjio.txt
+++ /dev/null
@@ -1,305 +0,0 @@
-libjio - A library for journaled I/O 
-
-Alberto Bertogli (albertito@blitiri.com.ar)
-
-Table of Contents
-
-1 Introduction
-2 General on-disk data organization
-    2.1 The transaction file
-3 The commit procedure
-4 The rollback procedure
-5 The recovery procedure
-6 UNIX API
-7 ACID (or How does libjio fit into theory)
-8 Working from outside
-
-
-
-1 Introduction
-
-libjio is a library for doing journaled 
-transaction-oriented I/O, providing atomicity warantees 
-and a simple to use but powerful API.
-
-This document explains the design of the library, how 
-it works internally and why it works that way. You 
-should read it even if you don't plan to do use the 
-library in strange ways, it provides (or at least tries 
-to =) an insight view on how the library performs its 
-job, which can be very valuable knowledge when working 
-with it. It assumes that there is some basic knowledge 
-about how the library is used, which can be found in 
-the manpage or in the programmer's guide.
-
-To the user, libjio provides two groups of functions, 
-one UNIX-alike that implements the journaled versions 
-of the classic functions (open(), read(), write() and 
-friends); and a lower-level one that center on 
-transactions and allows the user to manipulate them 
-directly by providing means of commiting and 
-rollbacking. The former, as expected, are based on the 
-latter and interact safely with them. Besides, it's 
-designed in a way that allows efficient and safe 
-interaction with I/O performed from outside the library 
-in case you want to.
-
-The following sections describe different concepts and 
-procedures that the library bases its work on. It's not 
-intended to be a replace to reading the source code: 
-please do so if you have any doubts, it's not big at 
-all (less than 1500 lines, including comments) and I 
-hope it's readable enough. If you think that's not the 
-case, please let me know and I'll try to give you a hand.
-
-2 General on-disk data organization
-
-On the disk, the file you are working on will look 
-exactly as you expect and hasn't got a single bit 
-different that what you would get using the regular 
-API. But, besides the working file, you will find a 
-directory named after it where the journaling 
-information lives. 
-
-Inside, there are two kind of files: the lock file and 
-transaction files. The first one is used as a general 
-lock and holds the next transaction ID to assign, and 
-there is only one; the second one holds one 
-transaction, which is composed by a header of fixed 
-size and a variable-size payload, and can be as many as 
-in-flight transactions. 
-
-This impose some restrictions to the kind of operations 
-you can perform over a file while it's currently being 
-used: you can't move it (because the journal directory 
-name depends on the filename) and you can't unlink it 
-(for similar reasons). 
-
-This warnings are no different from a normal 
-simultaneous use under classic UNIX environments, but 
-they are here to remind you that even tho the library 
-warantees a lot and eases many things from its user 
-(specially from complex cases, like multiple threads 
-using the file at the same time), you should still be 
-careful when doing strange things with files while 
-working on them. 
-
-2.1 The transaction file
-
-The transaction file is composed of two main parts: the 
-header and the payload.
-
-The header holds basic information about the 
-transaction itself, including the ID, some flags, and 
-the amount of operations it includes. Then the payload 
-has all the operations one after the other, divided in 
-two parts: the first one includes static information 
-about the operation (the lenght of the data, the offset 
-of the file where it should be applied, etc.) and the 
-data itself, which is saved by the library prior 
-applying the commit, so transactions can be rollbacked.
-
-3 The commit procedure
-
-We call "commit" to the action of safely and atomically 
-write some given data to the disk.
-
-The former, safely, means that after a commit has been 
-done we can assume the data will not get lost and can 
-be retrieved, unless of course some major event happens 
-(like a physical hard disk crash). For us, this means 
-that the data was effectively written to the disk and 
-if a crash occurs after the commit operation has 
-returned, the operation will be complete and data will 
-be available from the file.
-
-The latter, atomically, guarantees that the operation 
-is either completely done, or not done at all. This is 
-a really common word, specially if you have worked with 
-multiprocessing, and should be quite familiar. We 
-implement atomicity by combining fine-grained locks and 
-journaling, which can assure us both to be able to 
-recover from crashes, and to have exclusive access to a 
-portion of the file without having any other 
-transaction overlap it.
-
-Well, so much for talking, now let's get real; libjio 
-applies commits in a very simple and straightforward 
-way, inside jtrans_commit():
-
-* Lock the file offsets where the commit takes place
-
-* Open the transaction file
-
-* Write the header
-
-* Read all the previous data from the file
-
-* Write the previous data in the transaction
-
-* Write the data to the file
-
-* Mark the transaction as commited by setting a flag in 
-  the header
-
-* Unlink the transaction file
-
-* Unlock the offsets where the commit takes place
-
-This may look as a lot of steps, but they're not as 
-much as it looks like inside the code, and allows a 
-recovery from interruptions in every step of the way 
-(or even in the middle of a step).
-
-4 The rollback procedure
-
-First of all, rollbacking is like "undo" a commit: return 
-the data to the state it had exactly before a given 
-commit was applied. Due to the way we handle commits, 
-doing this operation becomes quite simple and straightforward.
-
-In the previous section we said that each transaction 
-held the data that was on it before commiting. That 
-data is saved precisely to be able to rollback. So, to 
-rollback a transaction all that has to be done is 
-recover that "previous data" from the transaction we want 
-to rollback, and save it to the disk. In the end, this 
-ends up being a new transaction with the previous data 
-as the new one, so we do that: create a new transaction 
-structure, fill in the data from the transaction we 
-want to rollback, and commit it. All this is performed 
-by jtrans_rollback().
-
-By doing this we can provide the same warranties a 
-commit has, it's really fast, eases the recovery, and 
-the code is simple and clean. What a deal.
-
-But be aware that rollbacking is dangerous. And I 
-really mean it: you should only do it if you're really 
-sure it's ok. Consider, for instance, that you commit 
-transaction A, then B, and then you rollback A. If A 
-and B happen to touch the same portion of the file, the 
-rollback will, of course, not return the state previous 
-to B, but previous to A. If it's not done safely, this 
-can lead to major corruption. Now, if you add to this 
-transactions that extend the file (and thus rollbacking 
-truncates it back), you not only have corruption but 
-data loss. So, again, be aware, I can't stress this 
-enough, rollback only if you really really know what 
-you are doing.
-
-5 The recovery procedure
-
-Recovering from crashes is done by the jfsck() call (or 
-the program jiofsck which is just a simple invocation 
-to that function), which opens the file and goes 
-through all transactions in the journal (remember that 
-transactions are removed from the journal directory 
-after they're applied), loading and rollbacking them if 
-necessary. There are several steps where it can fail: 
-there could be no journal, a given transaction file 
-might be corrupted, incomplete, and so on; but in the 
-end, there are two cases regarding each transaction: 
-either it's complete and can be rollbacked, or not.
-
-In the case the transaction is not complete, there is 
-no possibility that it has been partially applied to 
-the disk, remember that, from the commit procedure, we 
-only apply the transaction after saving it in the 
-journal, so there is really nothing left to be done. So 
-if the transaction is complete, we only need to rollback.
-
-In any case, after making the recovery you can simply 
-remove the journal entirely and let the library create 
-a new one, and you can be sure that transaction 
-atomicity was preserved.
-
-6 UNIX API
-
-We call UNIX API to the functions provided by the 
-library that emulate the good old UNIX file 
-manipulation calls. Most of them are just wrappers 
-around commits, and implement proper locking when 
-operating in order to allow simultaneous operations 
-(either across threads or processes). They are 
-described in detail in the manual pages, we'll only 
-list them here for completion:
-
-* jopen()
-
-* jread(), jpread(), jreadv()
-
-* jwrite(), jpwrite(), jwritev()
-
-* jtruncate()
-
-* jclose()
-
-7 ACID (or How does libjio fit into theory)
-
-I haven't read much theory about this, and the library 
-was implemented basically by common sense and not 
-theorethical study. 
-
-However, I'm aware that database people like ACID 
-(well, that's not news for anybody ;), which they say 
-mean "Atomicity, Consistency, Isolation, Durability" 
-(yeah, right!). 
-
-So, even libjio is not a purely database thing, it can 
-be used to achieve those attributes in a simple and 
-efficient way. 
-
-Let's take a look one by one:
-
-* Atomicity: In a transaction involving two or more 
-  discrete pieces of information, either all of the 
-  pieces are committed or none are. This has been 
-  talked before and we've seen how the library achieves 
-  this point, mostly based on locks and relying on a 
-  commit procedure.
-
-* Consistency: A transaction either creates a new and 
-  valid state of data, or, if any failure occurs, 
-  returns all data to its state before the transaction 
-  was started. This, like atomicity, has been discussed 
-  before, specially in the recovery section, when we 
-  saw how in case of a crash we end up with a fully 
-  applied transaction, or no transaction applied at all.
-
-* Isolation: A transaction in process and not yet 
-  committed must remain isolated from any other 
-  transaction. This comes as a side effect of doing 
-  proper locking on the sections each transaction 
-  affect, and guarantees that there can't be two 
-  transactions working on the same section at the same time.
-
-* Durability: Committed data is saved by the system 
-  such that, even in the event of a failure and system 
-  restart, the data is available in its correct state. 
-  For this point we rely on the disk as a method of 
-  permanent storage, and expect that when we do 
-  syncronous I/O, data is safely written and can be 
-  recovered after a crash.
-
-8 Working from outside
-
-If you want, and are careful enough, you can safely do 
-I/O without using the library. Here I'll give you some 
-general guidelines that you need to follow in order to 
-prevent corruption. Of course you can bend or break 
-them according to your use, this is just a general 
-overview on how to interact from outside. 
-
-* Lock the sections you want to use: the library, as we 
-  have already exposed, relies on fcntl locking; so, if 
-  you intend to operate on parts on the file while 
-  using it, you should lock them. 
-
-* Don't tuncate, unlink or rename: these operations 
-  have serious implications when they're done while 
-  using the library, because the library itself assumes 
-  that names don't change, and files don't dissapear 
-  beneath it. It could potentially lead to corruption, 
-  although most of the time you would just get errors 
-  from every call.
diff --git a/doc/layout b/doc/source_layout
similarity index 100%
rename from doc/layout
rename to doc/source_layout
diff --git a/doc/threads b/doc/threads
deleted file mode 100644
index bf4b6fb..0000000
--- a/doc/threads
+++ /dev/null
@@ -1,20 +0,0 @@
-
-The library is entirely threadsafe.
-
-This will make some people who worked with threads a bit concerned, because
-everybody knows that if a file descriptor is shared among threads, and two
-threads decide to read/write/perform any op that moves the file pointer, a
-mess is waiting to happen. And almost operations do touch the file pointer.
-
-But don't worry, the library is _truly_ threadsafe: it uses pread/pwrite,
-which do not touch the file pointer, and allows working on the same file
-simultaneously without concerns. Besides, it slightly improves performance by
-having less locking, less system calls, lower overhead and less calculation to
-perform the operation.
-
-
-Still, bear in mind that if you decide to work on the file outside libjio you
-need to lockf() the sections you're going to work on, because libjio relies on
-lockf() locking to warantee atomicity.
-
-
diff --git a/doc/tids b/doc/tids
deleted file mode 100644
index 43f831f..0000000
--- a/doc/tids
+++ /dev/null
@@ -1,83 +0,0 @@
-
-Transaction ID assignment procedure
-Alberto Bertogli (albertito@blitiri.com.ar)
-4/October/2004
----------------------------------------------
-
-This brief document describes how libjio assigns an unique number to each
-transaction that identifies it univocally during its lifetime.
-
-It is a very delicate issue, because the rest of the library depends on the
-uniqueness of the ID; it has to be coherent across threads and procesess; and
-it can't take long: it serializes transaction creation (and it's the only
-contention point for independent non-overlapping transactions).
-
-
-Description
------------
-
-We have two functions: get_tid() and free_tid(), which return a new
-transaction ID, and mark a given transaction ID as no longer in use,
-respectively.
-
-The main piece of the mechanism is the lockfile: a file named "lock" which
-holds the maximum transaction ID in use. This file gets opened and mmap()'ed
-for faster use inside jopen(). That way, we can treat it directly as an
-integer holding the max tid.
-
-To avoid parallel modifications, we will always lock the file with fcntl()
-before accessing it.
-
-Let's begin by describing how get_tid() works, because it's quite simple: it
-locks the lockfile, gets the max tid, adds 1 to it, unlock the file and return
-that value. That way, the new tid is always the new max, and with the locking
-we can be sure it's impossible to assign the same tid to two different
-transactions.
-
-After a tid has been assigned, the commit process will create a file named
-after it inside the journal directory. Then, it will operate on that file all
-it wants, and when the moment comes, the transaction is no longer needed and
-has to be freed.
-
-The first thing we do is to unlink that transaction file. And then, we call
-free_tid(), which will update the lockfile to represent the new max tid, in
-case it has changed.
-
-free_tid() begins by checking that if the transaction we're freeing is the
-greatest, and if not, just returns.
-
-But if it is, we need to find out the new max tid. We do it by "walking" the
-journal directory looking for the file with the greatest number, and that's
-our new max tid. If there are no files, we use 0.
-
-
-Things to notice
-----------------
-
-The following is a list of small things to notice about the mechanism. They're
-useful because races tend to be subtle, and I _will_ forget about them. The
-descriptions are not really detailed, just enough to give a general idea.
-
-
-* It is possible that we get in free_tid() and the transaction we want to free
-is greater than the max tid. In that case, we do nothing: it's a valid
-situation. How to get there: two threads about to free two tids. The first one
-calls unlink() and just after its return (before it gets a chance to call
-free_tid()), another thread, the holder of the current max, steps in and
-performs both the unlink() and free_tid(), which would force a lookup to find
-a new tid, and as in the first thread we have removed the file, the max tid
-could be lower (in particular, it could be 0). This is why we only test for
-equalty.
-
-* Unlink after free_tid() is not desirable: in that case, it'd be normal for
-the tid to increment even if we have only one thread writing. It overflows
-quite easily.
-
-* The fact that new tids are always bigger than the current max is not only
-because the code is cleaner and faster: that way when recovering we know the
-order to apply transactions. A nice catch: this doesn't matter if we're
-working with non-overlapping transactions, but if they overlap, we know that
-it's impossible that transaction A and B (B gets committed after A) get
-applied in the wrong order, because B will only begin to commit _after_ A has
-been worked on.
-
diff --git a/doc/tids.rst b/doc/tids.rst
new file mode 100644
index 0000000..4b21416
--- /dev/null
+++ b/doc/tids.rst
@@ -0,0 +1,76 @@
+Transaction ID assignment procedure
+===================================
+
+This brief document describes how libjio assigns an unique number to each
+transaction that identifies it univocally during its lifetime.
+
+It is a very delicate issue, because the rest of the library depends on the
+uniqueness of the ID. An ID has to be coherent across threads and procesess,
+and choosing one it can't take long: it serializes transaction creation (and
+it's the only contention point for independent non-overlapping transactions).
+
+
+Description
+-----------
+
+We have two functions: *get_tid()* and *free_tid()*, which respectively return
+a new transaction ID, and mark a given transaction ID as no longer in use.
+
+The main piece of the mechanism is the lockfile: a file named *lock* which
+holds the maximum transaction ID in use. This file gets opened and mmap()'ed
+for faster use inside *jopen()*. That way, we can treat it directly as an
+integer holding the max tid.
+
+To avoid parallel modifications, we will always lock the file with *fcntl()*
+before accessing it.
+
+Let's begin by describing how *get_tid()* works, because it's quite simple: it
+locks the lockfile, gets the max tid, adds 1 to it, unlock the file and return
+that value. That way, the new tid is always the new max, and with the locking
+we can be sure it's impossible to assign the same tid to two different
+transactions.
+
+After a tid has been assigned, the commit process will create a file named
+after it inside the journal directory. Then, it will operate on that file all
+it wants, and when the moment comes, the transaction is no longer needed and
+has to be freed.
+
+The first thing we do is to unlink that transaction file. And then, we call
+*free_tid()*, which will update the lockfile to represent the new max tid, in
+case it has changed.
+
+*free_tid()* begins by checking that if the transaction we're freeing is the
+greatest, and if not, just returns.
+
+But if it is, we need to find out the new max tid. We do it by "walking" the
+journal directory looking for the file with the greatest number, and that's
+our new max tid. If there are no files, we use 0.
+
+
+Things to notice
+----------------
+
+The following is a list of small things to notice about the mechanism. They're
+useful because races tend to be subtle, and I *will* forget about them. The
+descriptions are not really detailed, just enough to give a general idea.
+
+ - It is possible that we get in *free_tid()* and the transaction we want to
+   free is greater than the max tid. In that case, we do nothing: it's a valid
+   situation. How to get there: two threads about to free two tids. The first
+   one calls *unlink()* and just after its return (before it gets a chance to
+   call *free_tid()*), another thread, the holder of the current max, steps in
+   and performs both the *unlink()* and *free_tid()*, which would force a
+   lookup to find a new tid, and as in the first thread we have removed the
+   file, the max tid could be lower (in particular, it could be 0). This is
+   why we only test for equalty.
+ - Unlink after *free_tid()* is not desirable: in that case, it'd be normal
+   for the tid to increment even if we have only one thread writing. It
+   overflows quite easily.
+ - The fact that new tids are always bigger than the current max is not only
+   because the code is cleaner and faster: that way when recovering we know
+   the order to apply transactions. A nice catch: this doesn't matter if we're
+   working with non-overlapping transactions, but if they overlap, we know
+   that it's impossible that transaction A and B (B gets committed after A)
+   get applied in the wrong order, because B will only begin to commit *after*
+   A has been worked on.
+