Building informational webs with PyStyler

As webs grow, sometimes so many files will be added to a directory that it becomes unwieldy—to the point where the output from ls doesn't even fit on one screen. The obvious solution is to create one or more subdirectories and migrate most of the pages down into these new subdirectories.

However, this kind of reorganization forces us to think about the nature of the links between our pages. Lots of links are important to good Web design; we want to encourage lots of cross-linking.

But how are these links set up? Suppose we say that a cross-page references uses the path name of the target page, relative to the starting directory. However, if the referenced file is moved to a different directory, all your references to the newly moved pages must be fixed up to point to the new location.

So, in order to reduce the pain of moving pages around in the directory structure, PyStyler uses the concept of a topic identifier, which is an alias for an actual pathname. References that link to some other place in your web must use this topic name, instead of the path name, and PyStyler will automatically fill in the current path name of the reference.

PyStyler's plan.xml file contains a section that defines the relationship between topic names and directory names, so that when you move a group files to a different directory, you need only change the entry that defines that relationship.

To make it easier to maintain this catalog of topics, you may use the name of any first-level subdirectory under the starting directory as its topic name. Entries in the catalog of topics are necessary, then, only for second-level and deeper subdirectories.