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

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.

Preview

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.

Buttons

• The GO button runs DocTree starting at the named Scan Folder, and writing the output to the named Output File. If the Output File's name ends with .html then the report is written in HTML, otherwise it is written in Markdown. When the scan is complete, the output file will be opened with its default viewer, typically Notepad for .txt files and your default web browser for .html files.

• The OPTIONS button opens the Format Options palette window.

• The DONE button exits the DocTree GUI.

• The HELP button opens this document in your default web browser.

Format Options Palette

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

• The "Sort by" listbox contains three choices for sorting the lists of files and folders. Choose "Name" to sort by file name, "Date" to sort by modification date, and "Size" to sort by file size. Note that both the size and date sorts order equal sized (or dated) files by name, with the effect that sorting by size will sort folders by name since all folders appear to have zero size.

• The "List annotation sources" checkbox controls whether the file identified as the folder annotation is included (checked) or excluded (unchecked) from the list of files reported to exist in its folder.

• The "Show names at left" checkbox controls whether the file and folder names are displayed at the left end of the line (checked) or at the right end of the line (unchecked) in the lists of files and folders found in each folder.

• The "Show multiple annotations" checkbox controls whether more than one of the supported annotation files are included for a single folder. If clear, then only the first named file is included. If checked, then all of the named files are included.

• The "Report Title" text entry allows the title attribute of the generated HTML document to be set, along with the content of the first heading of the report. If clear, then the title and the first heading read "Documented Directory of scan folder" and "Files and Folders in scan folder", respectively.

• The "Use styled HTML" checkbox causes a CSS style sheet to be included in the generated HTML. This has the effect of allowing a certain amount of control over the font sizes and other formatting of the HTML as seen in a web browser.

• The "Highlight ReadMe.txt content" checkbox enables a light blue background shading behind the content included from the annotation files.

• The "Font Sizes" group contains list boxes controlling the (approximate) sizes of the body text font, and the fonts used in first, second, and third level headings. Note that the report itself only uses two heading levels, but an included annotation file may use any of the six levels supported by HTML; and levels three through six all share the same font size in the style sheet.

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]])
DocTree.document(t,"programfiles.txt")


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:

DocTree.configure

DocTree.configure(options)


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

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

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.

TODO

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

• Should there should be a way to configure what files are ignored?
• Should there be other names for annotation files?
• Should another name preempt the use of ReadMe.txt?
• Should there be a way to supply annotations for individual files as well as whole folders?

BUGS

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.