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.
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.
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.
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:
DocTree-Annotations.txtRead-Me.txtRead Me.txtReadMe.txtin 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.
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.
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.
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.
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.
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.
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.
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.
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(options)
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:
ReadMe.txt?