kaioa.com

There shall be structure.

Benefits

Hierarchical structures are always rather hard to explain with words alone. You've to identify the key items and then lay out their relation to each other - two at a time. This can take a couple of sentences and you'll also have to carefully check if everything is at the right place.

But it doesn't stop there. The worst part is probably that every user will have to parse your explanation very carefully. Of course that only adds a few seconds to the whole process, but those seconds accumulate. Your thousands (or even millions) of users might have done something more important during that time. They could have picked their nose for example, which is an activity many people enjoy more than reading documentation.

Yes, it's true. Reading documentation is really that exciting. So, we really should try everything possible to make it as quick and pain free as possible.

How to generate directory listings

The obvious choice is the tree command. However, Linux's tree program isn't streamlined for the process and it lacks some essential features while having lots of stuff you probably don't need (for this specific task). And the one from Windows... well, it sucks. The output doesn't look all that great and there are only two options: include files (only shows directories by default) and ASCII (instead of extended characters).

I wasn't really satisfied with this situation. The main purpose of both tools is getting an overview of the hierarchy from the command line, which is reflected by the available options or - in Windows' case - the almost complete lack thereof.

There is also the option to do the ASCII "art" yourself, but that's pretty fiddly, time consuming, and error prone. Needless to say that it gets worse if you want to use the box drawing special chars or their HTML entities. It's a mess, really.

That's why I wrote a specialized tool, which is 100% dedicated to this task. Initially I called it "ktree", then it was renamed to "tgen" and in the end I settled with "JHTree" for a minimum of SE-collisions.

JHTree

X:\>java -jar jhtree.jar
usage: java -jar jhtree.jar [options] <directory>
 FILE                                   : start directory
 -?                                     : show this help screen
 -d                                     : directories only
 -f [auto | ascii | entity | unicode]   : flavor (default:auto)
 -i                                     : ignore case
 -m [fullxhtml | inline | text | xhtml] : mode (default:inline)
 -p N                                   : padding
 -q                                     : quiet
 -sd VAL                                : dir styling
 -sp VAL                                : pre styling
 -stats                                 : statistics
 -up N                                  : parent directories to include

Mode/Flavor

JHTree is a command line tool, which can output directory listings as text, XHTML (fullxhtml), XHTML fragments (xhtml), and XHTML fragments with inlined styles (inline). For the structure characters there are 4 different flavors: auto, ASCII, entity, and Unicode.

It defaults to XHTML fragments with HTML entities for the special chars. Using entities is the safest bet. There are still many websites which don't properly deal with non-ASCII characters. Additionally, database rollbacks often break the encoding unnoticed. On many sites there are very little special chars after all and once the error is noticed it's often too late to fix it - there is already new content.

If you can guarantee non-garbled encoding you can safely use the "-f unicode" switch for a slightly lighter markup. By the way it's a good idea too put some special chars into your first post. This makes verification after a rollback easier.

Up

The "-up N" switch is a bit unusual. With this switch you can specify how many parent directories should be included in the listing. There is a little twist though: the other contents of the parent directories aren't included. This is very useful if you not only want to show the structure of your files and directories but also where they should be placed in a given hierarchy.

java -jar jhtree.jar X:\drupal_test\modules\shjsfilter -f unicode -up 2

drupal (manually renamed)
└ modules
  └ shjsfilter
    │ README.txt
    │ codeblock.css
    │ shjsfilter.info
    │ shjsfilter.module
    ├ shjs
    │ │ README.txt
    │ │ VERSION.txt
    │ │ gpl.txt
    │ │ index.html
    │ │ sh_main.min.js
    │ │ sh_style.css
    │ ├ css
    │ │   sh_*.css (manually truncated)
    │ ├ doc
    │ │   *.* (manually truncated)
    │ └ lang
    │     sh_*.min.js (manually truncated)
    └ themes
        ide-eclipse-extra.css

Pretty handy, isn't it?

Copy to clipboard

JHTree does output the listing over at stdout like Linux's and Windows' tree commands. However, this isn't the primary output. It's only there for quick checking and redirection (note: the output can look pretty garbled in the console, but it should be alright if it's redirected). The real primary output is the clipboard, which streamlines the workflow a bit. Just switch over to the document you're writing and paste it. It can't get much easier than that.

More examples

A default view (XHTML fragment with inlined styles and Unicode chars)

java -jar jhtree.jar X:\parent1\parent0\start_directory -f unicode

start_directory
│ file0A
└ sub0A
  │ file1A
  │ file1B
  ├ sub1A
  │   file2A
  └ sub1B
    └ sub2A
      └ sub3A
          file4A

Directories only (XHTML fragment with inlined styles and Unicode chars)

java -jar jhtree.jar X:\parent1\parent0\start_directory -f unicode -d

start_directory
└ sub0A
  ├ sub1A
  └ sub1B
    └ sub2A
      └ sub3A

ASCII (XHTML fragment with inlined styles)

java -jar jhtree.jar X:\parent1\parent0\start_directory -f ascii

start_directory
| file0A
+ sub0A
  | file1A
  | file1B
  + sub1A
  |   file2A
  + sub1B
    + sub2A
      + sub3A
          file4A

Directories only and 2 up (XHTML fragment with inlined styles and Unicode chars)

java -jar jhtree.jar X:\parent1\parent0\start_directory -f unicode -d -up 2

parent1
└ parent0
  └ start_directory
    └ sub0A
      ├ sub1A
      └ sub1B
        └ sub2A
          └ sub3A

Text manually wrapped in pre tags (text with ASCII chars)

java -jar jhtree.jar X:\parent1\parent0\start_directory -m text

start_directory
| file0A
+ sub0A
  | file1A
  | file1B
  + sub1A
  |   file2A
  + sub1B
    + sub2A
      + sub3A
          file4A

Custom inline styles and a 2 character padding (XHTML fragment with inlined styles and Unicode chars)

java -jar jhtree.jar X:\\parent1\parent0\start_directory -f unicode -sp "border:1px solid #000;line-height:1;padding:10px" -sd "color:#008" -p 2

start_directory
│   file0A
└── sub0A
    │   file1A
    │   file1B
    ├── sub1A
    │       file2A
    └── sub1B
        └── sub2A
            └── sub3A
                    file4A

Download/Legal/Requirements

Download: jhtree.jar (46kb)

Legal: JHTree utilizes Kohsuke Kawaguchi's excellent args4j command line parser library. JHTree itself is available under a BSD-style 0-clause license and the hideous source is included in the jar above.

Requirements: Java 1.5 or better. (It should be cross-platform.)