DocTree User Guide

This is a (sketchy) user guide to the DocTree utility. This guide describes the features of version 0.05 released on March 15, 2009.

DocTree is a system to document a tree of files and folders, with output in HTML or Markdown formatted text.

It produces an annotated list of the files and folders, by scanning each folder, listing the files it contains, and repeating for each folder it contains.

Getting Started

Run DocTree's GUI from the shortcut added to the Start menu. The window includes the two most important parameters at its top: the folder to process, and the name of the file to generate. If those edit controls are valid, then the GO button will process the folder, write the report, and open it in your default web browser. The bulk of the window is a preview (shown in Markdown format) of the report for the currently selected folder. Changing the folder or changing any of the formatting options will redraw the preview.

For easy entry, use the ... buttons at the right of each text entry field to navigate and select a folder and output file. The output file can be named anything, but calling it index.html and putting it in the folder processed might be a sensible choice.

To see how this works, try generating a report for your installed copy of DocTree itself, probably found at C:\Program Files\DocTree. Of course, it might not be possible (or a good idea) to save the report into that folder, so name the output something like DocTree.html in My Documents.

When finished, you will notice that the report contains a section for the DocTree folder itself, along with one for each sub-folder (in the current version there is only one subfolder, which is named DocTree\bin). The section for the DocTree folder begins with a copy of the ReadMe.txt file found in DocTree\ReadMe.txt. The bin folder currently does not have a ReadMe.txt of its own, so its section only includes lists of the files and folders it contains.

How DocTree Scans a Folder

Starting at the selected folder to scan, DocTree makes lists of all of the files and folders found. It processes these lists as described in this section, and then repeats the scan for each folder it found.

Some files are used to annotate their folder

As DocTree scans the folder and its children, it looks for certain file names and uses their contents to annotate the report for that folder. Each annotation file's content is included at the top of the document section for its folder.

To identify the annotation file, DocTree looks for one of the following file names:

  1. DocTree-Annotations.txt
  2. Read-Me.txt
  3. Read Me.txt
  4. ReadMe.txt

in that order. The first such file found is used as the folder's annotation, and any other matching files are treated as normal files in the folder.

Note that none of these file names are case sensitive.

It is generally assumed that the annotation file is written in Markdown, meaning for the most part that it is just plain ASCII text with support for some simple markup conventions such as bold and italic text. See the Markdown homepage for a complete description of the syntax. For example, this file itself is written in Markdown.

Some files and folders are ignored

Files whose names begin with a tilde (~) or end with .bak or .wbk are ignored completely. So are directories named CVS.

The logic for this is that files named like the first several patterns are usually used for backups of documents, and are not as interesting as the documents themselves.

The special case for folders named CVS is because of the version control system used by the author which hides information it needs in these folders. The CVS information is rarely of interest to anyone.

Using the DocTree GUI

DocTree Screen Shot

Launch the GUI from the Start Menu item (by default it is in All Programs, DocTree) that was created during installation. Notice that this manual is also available from that Start Menu folder.

The GUI window contains some data entry controls and a preview of the finished report.

Scan Folder

The Scan Folder control contains the name of the folder at which to start the scan. Click the ... button to browse for the folder, or type a valid folder name in the box. Either way, the folder name must be a full-qualified Windows folder name.

Output File

The Output File control names the file that will be written with the finished report when the GO button is clicked. Click the ... button to browse for the folder in which to write the file, and click the Save button to fill in the edit control. If the output file name ends with .html then the report will be written in HTML format and displayed in your web browser. Otherwise, the report is written in Markdown format, suitable for further processing with Markdown and other tools.


The large area at the bottom of the main window is a preview of the report for the currently named Scan Folder, with the current formatting options applied.

To refresh this report, change any formatting option.

The preview is displayed as Markdown text, regardless of the selected output file name.


Format Options Palette

Options Palette

The Options Palette contains controls that modify how the report is formatted, and what it contains.

Using DocTree from the Command Prompt

DocTree.lua "\path\to\folder" "reportfile.html"

Assuming that the folder where DocTree.lua is installed is added to the PATH environment variable, then DocTree can be run from the Command Prompt. This might be useful for automatically generating the report as part of a program build process.

Using DocTree as a Lua module

A quick example might be:

require "DocTree"
DocTree.configure{ writeMarkdown=true }
t = DocTree.collect([[c:\Program Files]])

which writes a (probably fairly large) text file containing a report on all the installed programs found in the C:\Program Files folder.

The public functions of the DocTree module are:



Set some runtime options for the collection and report generation. Be sure to call theis before calling DocTree.collect().


DocTree.collect(root) --> table

Collect the information needed to write the report from the folder named root, and return a table containing the whole information tree.


DocTree.document(tree, filename)

Given the information tree tree returned by DocTree.collect(), format and write the report to the file named filename.

If filename ends with .html, then the output is passed through the Markdown processor and written in HTML format ready for display in any web browser.

Otherwise, the output is left in Markdown format.


This utility is obviously not complete. Some things that might be added to future versions include:


  1. In DocTreeGUI, the destination file name is not forced to have the extension .html or .htm, and as a result the wrong thing happens when the scan completes.
  2. In DocTreeGUI, the layout is crowded.
  3. DocTreeGUI should probably disable the GO button until valid entries are made.