WEEK 1

In this application, every person belongs to exactly one team.

WEEK 4

We need to manage external contractors. We could use the “person” object.

WEEK 5

Hey, we need to assign a team to every person. Let’s create an “external” team.

WEEK 127

Did you see that newspaper article about our company? They say we have an average of 30 people on every team. Do we even have 30-people teams?

Names are short. They can only convey a very limited amount of information. Even worse, that information tends to be different from its meaning in standard English: by declaring in week one that every person belongs to a team, the project designers separated the Application::Person (always in a team) from the English::Person (might be in zero, one or more teams). By week four, this separation vanished from the minds of most of the team. A developer noticed that “English::Contractor is-a English::Person” and mistakenly translated it to “Application::Contractor is-a Application::Person“.

This was the first mistake. Why didn’t he notice?

A positive property is what you can do with a thing.With the Person object, you can store a name, login, password and phone number!This is exactly we you needed! Those positive properties you need that the object doesn’t provide, you can always add them through inheritance or composition, and that’s still less work than implementing everything or having to refactor the code. A negative property is what you cannot do with an object no matter how hard you try. With the Person object, you cannot remain on your own without a team! But our brains are biased to look for positive properties first, and passively ignore negative properties until it’s too late. Positive properties are about the solution solving the problem. Negative properties are about the solution not being applicable.

The second mistake was, by far, the worst. So they finally noticed that negative property that blasted all their model away. And they went on with it, patching the issue by altering the meaning of Application::Team. It originally a project team within the company, it then represented a named group of people that could be a project team or the group of external contractors. This is refactoring: no matter how you look at it, you change the behavior of an object and let it propagate throughout the project, so you better be careful about where it propagates! In this case, they weren’t careful about propagating the change of meaning to the documentation and user interaction part of the project, who mistakenly kept the old meaning of Application::Team. This led to a naive PR team issuing a statement that included the “external” group as if it were a project team.

It’s always helpful to have an anal-retentive person in a group, preferably in a position of authority that lets them veto such changes, and who is vigilant enough to spot that “external” team early on in the design.

The real mistake was allowing a negative property to slip into the design. Negative properties hinder reuse, by definition. Sure, allowing a person to belong to zero-one-many teams is hard on every piece of code that must work on teams, because the writers have to remember to check whether the person has a team in the first place. But it has to be done. Doing it may even bring to light some issues in the original requirements (“So what happens when a person changes teams between the moment team bonuses are computed and the moment they are paid out?”) that would become annoying later on.

function summarize($text)
{
  assert (is_string($text));
  if (strlen($text) < 255) return $text;
  return substr($text,0,253).'...';
}

Yet, however simple it might be, this function contains a bug. One day, your database will return a weird error when an user tries to save the data. If you’re lucky, it will happen to a lone user who will complain and move on. If you’re unlucky, it will happen during a million-line import and crash everything, or it will display strange things on the screenof every user around.

Can you find why?

The basic assumption made here is that substr is a sane text manipulation function that reads in a valid piece of text and returns a valid, albeit shorter, piece of text. This assumption is, of course, incorrect.

Recently, the internet has migrated towards Unicode representation of text in order to take into account the variety of languages with weird letters. I happen to speak one. We have interesting letters like Œ and interesting currencies like €. And don’t even get me started on Japanese, Hindi or Korean.

PHP does not support Unicode, it only supports ISO-8859-1 and assumes that every single string in a program is an ISO-8859-1 string. If you wish to store a character like € in PHP, you need to do so using the 256 characters from the ISO-8859-1 character set, which means you will end up using a combination of those characters to represent your single € character.

Could be “EUR”. And let the huddled eastern masses use romaji, pinyin and whatever.

Could be “€” or a similar clean HTML-friendly encoding of Unicode text. But that would be using six characters for one.

Or it could be UTF-8, which was designed to let Unicode code points move unhurt through a stringent encoding environment like ISO-8859-1. It still does so by using multiple characters from ISO-8859-1 to represent a single Unicode character (this is a technically incorrect metaphor, but bear with me). So € is represented as three characters: €.

However, to PHP’s substr function, every UTF-8 string remains an ISO-8859-1 string. This means that if the three characters representing the euro end up being straddled across the 255-character limit, the function will slice right through them. And “â‚…” is not a valid UTF-8 code point, so anything that expects a valid UTF-8 encoding is allowed to throw up with an error, which leads to the database refusing the connection and your user wondering what the problem is.

The solution would be, of course, to use PHP’s multiple byte encoding functions, such as mb_substr. The latter is UTF-8 aware and therefore never slices up a character in mid-sequence.

• Does not work on a page that has to redirect to another page.
• Results are difficult to see if the page is queried through AJAX.
• The crash may happen so utterly that no data is actually output, or it’s well hidden, or otherwise destroyed by output buffering mishaps.
• I have to look around the page to find it, and it also destroys my page layout.

The other possibility commonly used is to use error_log or log or printing to stderr or printing to a file, all of which rely on access to the server or setting up a way of displaying the data and filtering through it to see only relevant information.

I could bring in some logging facility from a framework (such as Symphony or Zend, which has a nice one), but I’d rather not add overweight dependencies—the Zend_Log_Writer_Firebug setup is kind of scary if you’re not already using enough bits of Zend to make it worth it.

So, I set out to design a system that would make things simpler. It works by sending ‘console.log()’ instructions to Firebug to display whatever it needs to display, and keeping things in the session until they can be displayed.

The code:

 function jslog()
 {
   if (defined('NO_JSLOG'))
     return;

   $args = func_get_args();
   if (empty($args)) {
     return create_function('$x', 
       'if (strpos($x,"</head>") > 0){
         $s = "<script type=text/javascript>";
         $e = "</script></head>";
         $x = str_replace("</head>",$s.$_SESSION["jslog"].$e,$x);
         $_SESSION["jslog"] = "";
       } return $x;');
   }

   $_SESSION['jslog'] .=
     'console.log('.implode(',',array_map('json_encode',$args)).');';
 }

Nothing overly complex. Initialization happens as a simple ob_start(jslog()), and everything can be disabled with a well-timed define('NO_JSLOG','') if you don’t have Firebug running. Typical usage includes being echo-like:

jslog("Hello");

Being var_dump-like:

jslog($_POST);

Being printf-like:

jslog('Earned $%.2f today', $dollars);

Being the best of both worlds:

jslog('My session is %o and my post is %o', $_SESSION, $_POST);

Displayed objects are converted to JSON and sent to Firebug, where they can be explored with the nifty DOM explorer tab that is so much easier to use than looking at var_dumped data.

Consider a comment form on a website. Nothing too fancy: the user fills in the “Name”, “Website (optional)” and “Comment” areas on a form, clicks the “Submit” button, and the page reloads with the comment on the page. No login required, no AJAX, no special effects. There are many things that can go wrong with this setup, and will go wrong if left in the hands of an inexperienced developer. They can be inconvenient, annoying or outright dangerous.

For example,

• Double-posting. When the submit button is clicked, the form sends a request to the server with the comment to be added. The server responds with the new list of comments. The user clicks the “refresh” button while on that page, or navigates to another page and presses the “back” button. This cause the browser to send the request again, so the comment appears twice in the comment list. If using POST, this is slightly less dangerous : the user might get an annoying “Submit again?” window instead of double-posting.
• SQL Injection. It is highly probable that the comments will be stored in an SQL-accessible database. If the code constructing the SQL query is not properly written, an appropriately chosen value for the comment fields can result in nasty things happening to the database.
• Cross-Site Request Forgery. Suppose that posting the form creates a GET request like:

  http://yourdomain/postcomment?name={name}&text={text}

  Knowing this, I can include an image tag in a forum, with a source attribute that matches the posting of a spam comment on your website. Every visitor of that forum page will send that request automatically (browsers auto-fetch images by default) and spam your comment list.

• Script Injection. The text entered by users must be displayed back to the visitors. If that text is not escaped before being output, an malicious attacker can submit a comment containing a dangerous script like:

  document.location = "http://www.youtube.com/watch?v=f2b1D5w82yU";

• Encoding Issues. What happens if the page is encoded in UTF-8 but I send you ISO-8859-1 text? Conversely, what happens if the page is encoded in ISO-8859-1 and I copy-paste my comment from Microsoft Word? For that matter, what is the encoding of the database? What is the encoding of your string literals?
• No Validation. User forgets to enter a name or a comment. No server-side check is made to determine whether the posted comment is valid and you get a mix of ugly empty comments and/or server error messages.
• Lossy Validation. You have to prevent people from posting with no name or no comment body. This means errors will be displayed on the page and, if the detection of such errors happens on the server after the initial post, it’s easy to forget displaying back the text the user entered in the first place. “Sorry, you forgot to enter a name so I’ve thrown your ten-line comment away” [#]
• Does not work in Internet Explorer. There are many possible causes for it, such as respecting W3C specifications.
• Legal Issues. If a malicious commenter uses your page as a soapbox for illegal activities, some countries will hold you responsible. For instance, in France, you can be condemned if anonymous posters engage in holocaust denial on your website.

That’s nine, just thinking about the obvious problems that would happen if following the simplest approach to this, and I have seen many of them happen in three situations: novice programmers (such as interns), freelancers and low-wage programmers. The worst offender is by far the code written in naive PHP, which has the peculiarity of “the simplest thing” being almost always “the incorrect thing” as well.

Still, if you can’t let an intern write a simple user comments page, what are you going to let interns do?

All of the above issues are easy to correct once you know about them. Always send data as POST, check the referrer, convert everything to UTF-8, validate your data, use prepared statements instead of inline SQL, respond with a 303 redirect to a GET page, include the posted data and any errors in the session and display them back in the form if present, take all your dynamic generation text through an an HTML escaping function, add “type=submit” to buttons, and add a quick moderation tool to hide unwanted messages quickly.

Knowing about the issues and acting to prevent them is the hard part, which is why every project should have at least one experienced developer who knows about the errors. Or be using a framework that prevents such errors from happening in the first place (then again, if the documentation for Zend_Form has an “user refreshes page, double-posts by mistake” error, who can we trust?)

Although it has been taken over by marketing folks, there are still good thinks to be said about “best practices”. The basic idea is to have a set of practices available for the less experienced developers to follow. Such practices are usually very simple to understand and follow (never display data in a POST controller, never change the model significantly in a GET controller), reasonably simple to verify automatically (assert that no output happened as part of a POST controller response) and have the immediate effect of preventing a classic mistake (no re-post on a page refresh).

I’m a big proponent of enforcing good code through practices first, and then code-based contraptions if developers insist on ignoring them. The problem with going for the contraptions first is you have to explain how to use the contraptions anyway, and people will be tempted to move around the contraptions and still write bad code.

If your code is reviewed by a compiler or an automatic code analysis tool, you can learn how to game the system. This results in code that does not trigger the alarms, while still being bad. Compare with having your code reviewed by a live person, who is experienced and anal-retentive about respecting practices and makes it horribly clear that if you don’t follow them, you will be forced to follow them, on your free time before you can commit your code. Such reviews leave no room for wiggling, and as long as the judgment of the reviewer is fair, will actually motivate the team to respect the standards.

• Detecting what functions are exported and building the appropriate JS code.
• Detecting what function the JS is calling.
• Transforming data between JS and PHP.

I solve these with glob(), __autoload and json_encode (respectively) in a little prototype I called JSOS (JavaScript Or Something). jQuery on the client side provides me with synchronous AJAX queries. The code (PHP with echoed Javascript) looks like this, and is placed in a controller:

<?php
 function __autoload($classname)
 {
   require_once($classname . '.inc.php');
 }

 if (!isset($_POST['cls'])) {
   echo '<html><head><title>JSOS</title>';
   echo '<script type="text/javascript" src="jquery.js"></script>';
   echo '<script type="text/javascript">var jsos={};';
   echo '$.ajaxSetup({async:false,timeout:5000});';
   echo 'jsos.$=function(c,f,a){';
   echo 'var o={exception:"Server disconnect"},';
   echo 't={cls:c,func:f};';
   echo 'for(var i in a)t[""+i]=a[i];$.post(".",t,';
   echo 'function(d){o=d},"json");if("exception" in o)throw o.exception;';
   echo 'return o.result};';

   foreach (glob('*.inc.php') as $file)
   {
     $class = str_replace('.inc.php', '', $file);
     echo 'jsos.' . strtolower($class) . '={};';
     $text = file_get_contents($file);

     preg_match_all('/public static function ([A-Za-z_0-9]+)\(([^)]*)\)/',
                    $text, $func);

     foreach ($func[1] as $id => $value) {
       echo 'jsos.'.strtolower($class).'.'.strtolower($value).'=function(';

       $args = explode(',', $func[2][$id]);

       foreach (array_keys($args) as $key) {
         $args[$key] = str_replace(array(' ', '$'), '', $args[$key]);
       }

       $args = array_filter($args);

       echo implode(',', $args).'){return jsos.$';
       echo '("'.$class.'","'.strtolower($value).'",['.implode(',',$args).'])};';
     }
   }

   echo '</script></head><body></body></html>';
   exit;
 }

 $args = array();
 foreach ($_POST as $key => $val) {
   if ($key === 'cls')
     $cls = $val;
   elseif ($key === 'func')
     $func = $val;
   else
     $args[(int)$key] = $val;
 }

 ksort($args);

 if (!class_exists($cls)) {
   echo '{exception:"No such package!"}';
   exit;
 }

 if (!method_exists($cls, $func)) {
   echo '{exception:"No such method!"}';
   exit;
 }

 try {
   $result = call_user_func_array(array($cls, $func), $args);
   echo json_encode(compact('result'));
   exit;
 }
 catch (Exception $e) {
   $exception = "$e";
   echo json_encode(compact('exception'));
   exit;
 }
 

All files in the current directory with a ‘.inc.php’ extension are assumed to contain a similarly-named class, and all public static functions of that class are exported. For example, suppose Test.inc.php contains the following definition:

class Test
{
  public static function Run($a) { return "$a$a"; }
}

Then, to call the Test::Run function from the above page, one would simply type in Javascript:

jsos.test.run('Hello');

And indeed, with only five lines of code, the result to a client request is computed on the server and displayed on the client again, without issues. Here’s the result running in Firebug:

Further work should include handling errors (right now, if the server encounters an error or outputs non-JSON data, the call will die with a “Server disconnect” exception), which makes debugging easier than having to wade through the Net tab of Firebug.

1. It forces you to express in detail what you want the unit to do (so that a computer may then test it by checking the results).
2. For an unit to be testable, its results should be checked as “correct” or “incorrect” on their own or with minimal context. This makes code easier to reuse.
3. Since it’s automatic, you do not need to test manually every time you make a change: the tests will run hourly or nightly (or for every build) and tell you what went wrong.

The cost, however, is that unit testing code must be written for every unit. That code needs to create an object, manipulate it, then check its return values for validity. And test-driven-development advocates insist that such code should be written before the actual unit (make it compile, make it fail, make it pass).

I do understand their position: if you’re thinking of very specific corner cases that you might forget about while writing the unit, you might as well write tests for these corner cases first. But what about the simple, core functionality of the units? If a programmer sets their minds to testing an unit, they can usually look at the value and decide “it’s correct” or “it’s wrong”, and that process is orders of magnitude faster than writing an assertion that checks whether the value is correct. We’re not talking about complex ten-argument dozen-property function on a deep-inherited object here, it’s more of a “this string goes in, that string goes out” concept.

An example would be a “slugify” function : plug an arbitrary string into it, and a cleaned up lowercase hyphen-separated string comes out. As long as you are mindful of corner cases (weird characters, encodings, empty strings and so on) testing this function manually is quite simple. You certainly lose the benefit of point 1 (no more expressing the details of what the function should do in advance of writing it) but you can keep the benefits of 2 (whether automatic or manual, tests make code reusable) and you can even get the benefits of 3 by saving your code as an unit test.

This is what happens in the console-like scaffold I have been working on (you can click to enlarge):

You type in code in the text box. Clicking “Run” (or pressing TAB RET) sends the code through AJAX to the server and retrieves the var_dumped result (as well as a highlighted version of the code). The mindful programmer can use this console to preemptively test and debug code. The excellent programmer will even adapt their code to make such testing easier, and being able to use any kind of code in the barren context of this console means that code can be used anywhere.

The real hit there is that little Add Cog icon from the FamFamFam Silk icon set. It’s truly beautiful and adds a touch of antialiased pixel art to an otherwise bland rounded-edges Web 2.0 console. And what it does is even better: when clicking that icon, the corresponding piece of PHP is automatically added to the database of unit tests, as a test that runs the code on the green background and asserts that the output of the code is identical to the text on the grey background.

This makes the “for every bug you find, write an unit test that finds that bug” insanely easy to do: find the bug using the console, correct the code, check with the console that the bug is dealt with, and then add the final “bug corrected” console run to the unit test database. The work spent debugging a program from this console is never lost, it all ends up being an automated test with one single click.

This also makes writing unit tests much more developer-friendly: the console lets you test your code as you write it, without having to write controllers or views or whatever other contraption you need to display the results. An excellent choice for testing-averse developers.

Being Agile, they don’t have an existing detailed specification to tell them what the URL should be. And they’re in the middle of writing something that’s quite complex, so thay can’t dedicate too much brain power to perform a proper choice. The end result is a hardcoded URL that they will need to change later on.

The problem here is that when an URL changes, everyone has to check their own files for uses of that URL, and correct it. Yes, it would be possible to add a permanent redirect (and it often is a good idea on a live website so that the search engine google references can be kept) but these do not play nice with POST requests, and what would be the point if the site has not gone live yet? So, people forget incorrect URLs in the middle of their files, and it takes a reasonable amount of examining crawler logs to find and replace them.

My usual practice is to have a central list of all URLs. Since I tend to work with an __autoload strategy, I just create an Url class and use members of that class to return properly HTML-formatted URLs : <?=htmlspecialchars(URLROOT.'/account/confirm/'.urlencode($id))?> becomes the cleaner <?=Url::ConfirmAccount($id)?>, and the actual account is hardcoded within the Url class as:

class Url
{
  const ROOT = 'http://mydomain.com';

  static function ConfirmAccount($id)
  {
    assert(is_int($id));
    return self::Local('account','confirm',$id);
  }

  private static function Local()
  {
    $url = self::ROOT;
    $get = '';

    foreach (func_get_args() as $segment)
      if (is_array($segment))
        foreach ($segment as $getkey => $getval)
          $get .= ($get === '' ? '?' : '&')
               .  urlencode($getkey)
               . '=' . urlencode($getval);
      else
        $url .= '/' . urlencode($segment);

    return htmlspecialchars($url.$get);
  }
}

So that the url-encoding of the segments, and the final cleanup of any HTML special chars that could have remained within the URL, are performed by the function automatically. Any associative arrays found in the argument list are converted to GET arguments that are also properly formatted and appended to the URL. Using the URL in a non-HTML environment, such as a text document or a Location: header, requires reversing the entity encoding beforehand, but this situation should be rare enough.

It would of course be proper to construct the ROOT constant from the requested domain name rather than hard-coding it. I have not done it here in order to keep the example short.

The benefits of this approach are many:

• Specifying the URL of the account confirmation page is not done by a random page anymore, it’s done by the Url class. The random page merely has to state that it wants to link to the account confirmation page. In case of a change of the account confirmation URL (such as /account-confirm instead of /account/confirm) all modifications will occur in a single place.
• The programmer that uses the URL does not need to remember the format used to provide the data: if an URL can be built from several arguments, those arguments can be named, documented and checked by the PHP code.
• Everything within the URL is properly escaped before it is returned : the output of an URL function is always a properly formatted URL with all special characters encoded as HTML entities. This way, no invalid URLs will ever appear within the code.

Of course, in order to work, functions of the Url class should never be called with constant arguments: that would be akin to hardcoding those addresses. While the other benefits remain, changing the meaning of these arguments would have the same rippling effects over code. So, whenever you need to call a function with constant arguments, create a new function that explains what the url-with-constant-arguments is. For instance, “ConfirmAccount(0)” might be described as “ConfirmRootAccount()”, thereby shielding you from a change in the meaning of what a root account is.

ul#navlist
{
margin: 0 0 0 30px;
padding: 0;
width: 12.5%;
}

#navlist li
{
list-style-type: none;
background-color: #191970;
color: #daa520;
border: .2em solid #daa520;
font-weight: 600;
text-align: center;
padding: .3em;
margin-bottom: .1em;
}

#navlist li a
{
color: #daa520;
text-decoration: none;
display: block;
}

#navlist li a:hover
{
background-color: #faebd7;
color: #191970;
}

And here’s the reindented version:

ul#navlist {
  margin: 0 0 0 30px;
  padding: 0;
  width: 12.5%;
}
  #navlist li {
    list-style-type: none;
    background-color: #191970;
    color: #daa520;
    border: .2em solid #daa520;
    font-weight: 600;
    text-align: center;
    padding: .3em;
    margin-bottom: .1em;
  }
    #navlist li a {
      color: #daa520;
      text-decoration: none;
      display: block;
    }
    #navlist li a:hover {
      background-color: #faebd7;
      color: #191970;
    }

The idea is to combine the common prefixes in selectors as branches of a tree, and then indent each node of the tree by its depth in the tree (and place it right below its parent node or elder sibling). From what I gather, the position of the braces varies depending on personal styles, but the basic indentation rules apply as such.

The basic workflow goes like this:

• You run the “scan” command. This usually happens by clicking the desktop icon for the launcher, but you can also run it on a command line.
• The program prompts you for a document name. Aside from being different from any existing document name (to avoid accidental overwriting) you are free to choose any valid file name.
• The program starts scanning pages. Every time a page is scanned, a  preview is shown and the user can accept or try again. Every time a page is accepted, the user is allowed to scan another page or stop scanning.
• Every scanned page is saved to TIFF on the fly. Once all pages have been retrieved, they are converted to PNM, then to DJVU. This conversion step takes around two minutes per page on my computer. Then, all DJVU files are bundled together as a single file.
• The bundled DJVU is stored both locally and on a backup server through FTP.

Once the manual scan-preview-confirm process has ended, the lengthy compression and upload stage starts, but is completely non-interactive. It is therefore possible to start scanning another document (or do something else) while it finishes.

I have also reduced the resolution from 300 dpi to 150 dpi, as it remains quite readable. This has resulted in a reduction in file size from around 8MiB PNG files to 2MiB TIFF files, which are in turn compressed to 1MiB DJVU files. My current library of scanned pages (mostly administrative documents, reports and contracts) weighs in at around 150MiB instead of the previous 1.1GiB.

Below is a scan of Papier d’Arménie made by my delightful assistant:

The Objective Caml source code for running this little baby follows below:

exception CommandFailed of int

let run command =
  print_endline command ;
  let result = Sys.command command in
    if result <> 0 then raise (CommandFailed result)

let ask request =
  print_endline ( "# " ^ request ) ;
  read_line ()

let tmp ext =
  Filename.temp_file "" ext

let say format =
  Printf.printf ("# " ^^ format)

(* Scan a page, display the result, ask if the user wants to keep it
   (tries again until it gets the scan right) and returns the filename
   where the successful scan was saved. *)
let rec scan_to_tiff () =
  let file = tmp ".tiff" in
    run ("scanimage -l 0 -t 0 -x 215 -y 297 --brightness -22 "
         ^ "--contrast 22 --resolution 150 --progress --mode Gray "
         ^ "--format=tiff > " ^ file) ;
    run ("display " ^ file) ;
    if ask "keep this page? [Yn]" <> "n" then
      file
    else
      scan_to_tiff ()

(* Scan individual pages (using scan_to_tiff) until the user decides to
   stop. If an individual scan fails due to system errors, allows retrying.
   Returns the list of all filenames the user agreed with. *)
let rec scan_list_to_tiff () =
  try
    let file = scan_to_tiff () in
      if ask "scan another page? [Yn]" <> "n" then
        file :: scan_list_to_tiff ()
      else
        [file]
  with CommandFailed i ->
    say "command failed with exit code %d\n" i ;
    if ask "try again? [Yn]" <> "n" then
      scan_list_to_tiff ()
    else
      []

(* Turn individual image into djvu image. Returns djvu filename
   if successful. *)
let rec tiff_to_djvu file =
  let pnm = tmp ".ppm" in
  let djvu = tmp ".djvu" in
    run ( "convert " ^ file ^ " " ^ pnm ) ;
    run ( "cpaldjvu " ^ pnm ^ " " ^ djvu ) ;
    djvu

(* Turn a set of images into individual djvu pages. Allow skipping
   or retrying on error during the conversion process. *)
let rec tiff_list_to_djvu_list = function
  | [] -> []
  | file :: list ->
    try
      tiff_to_djvu file :: tiff_list_to_djvu_list list
    with CommandFailed i ->
      say "command failed with exit code %d\n" i ;
      if ask "try again? [Yn]" <> "n" then
        tiff_list_to_djvu_list (file :: list)
      else
        tiff_list_to_djvu_list list

(* Turn a list of individual djvu files into a bundled djvu file. *)
let rec make_djvu_bundle file list =
  try
    if  list = [] then
      false
    else if List.tl list = [] then
      ( run ( "cp " ^ List.hd list ^ " " ^ file ) ; true )
    else
      ( run ( "djvm " ^ file ^ " " ^ String.concat " " list) ; true )
  with CommandFailed i ->
    say "command failed with exit code %d\n" i ;
    if ask "try again? [Yn]" <> "n" then
      make_djvu_bundle file list
    else
     ( say "scan aborted" ; false )

(* Choose a name for the output djvu file *)
let rec choose_djvu_filename () =
  let path = "/home/arkadir/docs/" in
  let name = ask "document name (extension will be added automatically) ?" in
    if name <> "" && name <> Filename.basename name then
      ( say "incorrect filename" ; choose_djvu_filename () )
    else if Sys.file_exists (Filename.concat path (name ^ ".djvu")) then
      ( say "file already exists" ; choose_djvu_filename () )
    else
      Filename.concat path (name ^ ".djvu")

(* Upload a file to an ftp server. *)
let rec upload_file file =
  try
    run ( "ncftpput -f /home/arkadir/docs/ftp.cfg /home/www/blog/docs " ^ file )
  with CommandFailed i ->
    say "command failed with exit code %d\n" i  ;
    if ask "try again? [Yn]" <> "n" then
      upload_file file
    else
      say "upload aborted"

(* Complete process *)
let _ =
  let name = choose_djvu_filename () in
  let files = tiff_list_to_djvu_list (scan_list_to_tiff ()) in
    if make_djvu_bundle name files then
      upload_file name

This requires the classic djvuLibre utils to be installed (cpaldjvu and djvm), as well as imagemagick (convert) and ncftp (ncftpput). Scanning happens with sane (scanimage). Some files are also uploaded to my web server, where I use “convert -thumbnail” to create thumbnails from DJVU files.