Outline - Remove After Completing

• The page as the basic unit of organization
• The snippet as the basic unit of content
• Snippet types
  • Plain Text Snippets
  • File Snippets
• Finding references ??? - I think this is already covered, do we need to cover it again?

Introduction

In previous chapters we've discussed practical and pragmatic operational descriptions of how to use OpenSquiggly.

In this chapter, we delve into the less tangible, theortical aspects of the OpenSquiggly paradigm. OpenSquiggly is driven by a unified theory of content organization. This paradigm provides a highly flexible framework for organizing content that can accommodate a large variety of real world situations.

As we have emphasized previously, OpenSquiggly is heavily informed by that target market it hopes to serve, namely, software development teams, and by the perceived use cases needed by our customers. However, at its heart, OpenSquiggly is more than that. In this chapter we discuss the theory of the OpenSquiggly paradigm.

Pages as the Primary Unit of Content

All content viewed with OpenSquiggly is done through the use of pages.

There are three types of pages that we need to understand from a testing persective, as each type of page has various characteristics that need to be exercised in our test plans.

• Regular Topic Pages
• Mapped Topic Pages (most of the time referred to simply as "Mapped Pages")
• Virtual Pages

Regular Topic Pages

Regular topic pages are physical entities that are stored as records in the TopicPages collection in the database. These topic pages contain a list of table of contents entries that refer to other pages, and a list of snippets that comprise the content of the page.

Snippets are self-contained, generally small, pieces of content that can be placed on a page. When a page is rendered, the system reads all the snippets that belong to the page, and renders them vertically down the page surface from top to bottom.

The page structure in OpenSquiggly is not strictly hierarchical as one might be familiar with in an operating system file system. Pages can be referred to by multiple pages, and therefore existing at multiple points within the user's navigator.

Back references to pages are stored in the page's ReferencedBy array.

Mapped Topic Pages

Mapped topic pages are also physical entities that are also stored as records in the TopicPages collection.

Mapped pages reference a Mount Point and a starting path within that mount point.

Unlike regular topic pages, the user does not have direct control over the table of contents entries for mapped pages. Instead the table of contents for the page are dynamically generated by reading the items with the directory of the mount point using the starting path as the folder.

The list of snippets is also generated dynamically for mapped pages. When the system request's the snippets for a mapped page, the system reads the contents of the file at the mount point and the starting path, and returns a single text snippet containing that file's contents.

Because mapped pages are physical entities, they, like regular topic pages, contain back references to the pages that reference them.

Virtual Pages

Virtual pages are non-physical entities that are not stored in the database's TopicPages collection. They are dynamically-generated on demand when the user requests to view that page.

Virtual pages are very similar to mapped pages. As with mapped pages, virtual pages have an associated mount point and start path. As such, like mapped pages, the table of contents and list of snippets are generated dynamically by reading the directory list and file content of the file located within the mount point at the specified path.

There's one other subtle difference between mapped pages and virtual pages regarding page title. Mapped pages have their own page title which is stored in the record in the database. Therefore the title of a mapped page might not be the same as the title of the page to which it refers. Relative pages however always get their title from the external content (either the file or folder name).

Summary of Page Types and Characteristics

Example