Minimalist Online Docmentation

Techincal

• The index will silently fail if javascript is not enabled in the browser. This is a very high priority item.

• The index will silently maintain state incorrectly if cookies are not enabled in the browser. This is a very high priority item.

• The structure of the index does not get updated when a topic (but not a filename) gets modified. This may be difficult to fix.

• Filenames that contain spaces will not get parsed correctly in the config file (they are tolerated elsewhere, including quoted on the command line).

• Adding or modifying =me_first and =me_last tags should trigger a full rebuild of the source tree (it doesn't), since the index will change. I haven't come up with an elegant way of tracking this type of modification, though.

• Filenames that contain special characters according to RFC 1738 are not encoded when they're converted to URLs. This includes whitespace. Fortunately, this seems to be handled gracefully by most browsers, although that's still no excuse.

• From the File::Find manpage: "There is no way to make find or finddepth follow symlinks.", hence the same limitation exists in mod2html. Practically speaking, this means that you can link to files and have mod2html treat them as regular files, but if you link to a directory, it will not descend into it.

  (Note: more recent versions of perl and File::Find now allow for following symbolic links, but I still think that the current behavior is safest).

• Since mod2html doesn't take the status of destination files into account, if a destination file is modified or removed, mod2html will not notice or offer to recreate it; the source file must be touched.

  I would argue that this is not a bug, since the mod2html's behavior is more consistent and predictable if it only uses the contents of the source tree to determine its actions.

Design

• The method for generating <a name=""> tags from topic names could be better. Here's how I would score it on the values that it generates:

  unique	A-
  predictable	B
  readable	B-
  of reasonable length	D

• Topics should really be specified and arranged in a tree structure, like the files and directories. Right now they're basically just levels of indentation. The problem is that I couldn't come up with a means of doing this that didn't rely on bracketing the text, which I think would be too much to have to think about.

• There is no good way of specifying the order that documents or directories appear in the index, at least without ruining the siplicity of the design. This is because mod2html generates the document hierarchy based on the arrangement of the files and directories in the filesystem, and the filesystem itself does not specify any order. Files and directories are often sorted alphabetically, but this is a function of the program displaying the directory contents, not a function of the filesystem structure itself.

  The =me_first and =me_last tags are a compromise that allow very coarse control of order of files in a direcotry, but even at that, they still don't offer any control over the order in which directories appear.

• The current model does nothing to enforce separation of automatic and human-maintained files. See the discussion under development notes.