710 South Myrtle Avenue, Ste 315, Monrovia, California 91016
DocTree is a utility written in Lua to report on the content of a folder tree. The report is written in HTML, and contains a section for each folder in the tree listing the files and folders found in that folder.
In addition, folders may have annotation text that is included in the report. The annotations for a folder are stored in a file in that folder, so that the annotations naturally stay with the folder and are likely to survive manipulations such as ZIP archival, version control systems, or even simple file system moves and renames.
DocTree is tested and developed primarily on a Windows XP system. It should run on any version of Windows capable of running Lua. It is known to install and run on Vista, and there should be no issues with Windows 7.
To install:
Download and install Lua for Windows v5.1.4.20 or newer from the LuaForge Lua for Windows download page.
Download and install the latest DocTree setup package from the LuaForge DocTree download page
If not using Windows or not using the Lua for Windows package, then in addition to the Lua interpreter itself, you will need working installations of the modules Lua File System, IUP, and CD at a minimum. Note that DocTree is not tested on platforms other than Windows, so please let us know what platform you are using and how it works for you.
Please do install Lua before installing DocTree. If DocTree is installed After Lua is installed, then when setup is complete, it will offer to launch the DocTree GUI for you and will be able to do so.
DocTree may be run interactively with full control over the report configuration via the shortcut installed in the Start menu. That shortcut runs the script DocTreeGUI.wlua using the special wlua.exe provided by Lua for Windows.
DocTree may be run from the command line, batch files, or make by running DocTree.lua from the DocTree installation folder with the "usual" lua.exe standalone interpreter. In this mode, most configuration options are taken to have their default values, and the output can be saved in either HTML or Markdown depending on the output file name specified.
DocTree may also be incorporated into other Lua programs as a module loaded by the usual require"DocTree" mechanism. Documentation on its use as a module is incomplete.
Click here for a sample report of DocTree's installation folder.
Refer to the DocTree User Guide for the rest of the details.
This version is another public alpha release with UI and reporting improvements.
Rearranged the GUI so that most options are in a modeless dialog box that is only displayed at need.
Support a choice of the directory sort order.
Support an internal HTML style sheet for the report.
New controls over the sizes used for the body text and heading fonts, if the style sheet is selected.
New control to shade the annotation text's background if the style sheet is used.
Folder section headings are now output with hyperlinks to the named
folder, using the file: protocol. This allows the user to click
on the section heading to see the folder. If the user's default
web browser is Internet Explorer, then the link opens Windows
Explorer on the folder; Firefox browses the folder in an internal
file system browser.
Fixed bug that prevented specifying . as the folder to document.
This version is the first public alpha release with working report preview, full report generation, handling of several names for per-folder annotation files, and listings sorted by name, with the object's name in the first column of the table.
This utility is obviously not complete...
BUG: It is hyper sensitive to the file extension. An exact match to ".html" is required for the format to come out HTML, but other names should also end up HTML and don't. In particular, .HTML ends up Markdown, then opens (badly) in IE.
BUG: Large trees take a long time to preview, use a lot of memory,
and lock the UI while the attempt to build the preview. Don't point
the GUI at C:\, for example.
BUG: The markdown preview text and a markdown output file may not
process to the same result as the HTML output. This is because the
HTML report is actually generated in sections, so the scope of those
markdown elements such as the [ref] links used to form the target
URl of an <a> tag will differ depending on how the markdown is handled.
Make a project or settings file type, register it to run DocTreeGUI with those settings loaded.
Also support selection of an external style sheet in place of the internal sheet.
Support HTML preview (optionally?) instead of the markdown preview.
Should there should be a way to configure what files are ignored?
Should there be a way to supply annotations for individual files? Although tempting to use NTFS alternative streams for the annotation, that would make them hard to see. Perhaps a .DocTree folder could contain per-file annotations named after the files they annotate?
Make GUI more "live", with folder tree and file panes, and some kind of a way to directly edit the content of "doctree-annotaiton.txt" for a folder.
Consider support for file types other than markdown text for the annotation content.
Implement a "Document This Folder" explorer context menu, which would run DocTreeGUI with "this folder" filled in as the folder to scan, and either the default settings or settings read from a settings file found in that folder.
Support some form of per-folder option control, possibly outof the annotation file.
Support project file templates.
DocTree is released under the following license:
This is similar to the MIT license, and is the same license applied to Lua itself. It is also approved by the Open Source Initiative.Copyright (c) 2009 Cheshire Engineering Corp. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
Cheshire Engineering Corporation 710 South Myrtle Avenue, Ste 315, Monrovia, California 91016 |
|
|
||
|
+1 626 303 1602 Cheshire Engineering | |
|
EMAIL to Inquiry@CheshireEng.Com. | |