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][1] for a complete
description of the syntax. For example, [this file itself][2] is
written in Markdown.
[1]: http://daringfireball.net/projects/markdown/
[2]: DocTree.txt
### 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.