The most important issue is to limit the line length in .sage files. Long lines are cumbersome to work with in DSEdit, and they complicate certain activities in Code Vault, such as diffs and merging.

There is one exception to this guideline: code samples. Depending on the language in question, it may not be practical to avoid long lines in code samples.

Because horizontal space is at a premium, we do not recommend indenting .sage files to show the hierarchy of volumes, topics, articles, and sections. Among other issues, indented sections require upkeep as the article evolves. Instead, all content should start in the very first column. DSEdit will help you match [end] tags to their corresponding starting tags, as shown here…

Above, DSEdit indicates that the [end] tag on line 107 terminates the Synchronization section, which begins on line 97.

We do recommend indenting for lists, and we suggest indenting multi-line list items. These techniques make the .sage content much easier to follow. For example…

Items for sale[...] [list] #* Weapons [list] #* Mace #* Claymore #* Kris [end] #* Armor [list] #* Helm #* Boots #* Belt [end] #* Food & Drink [list] #* Mutton #* Bread #* Milk [end] [end]

For deeply nested lists, you will eventually need to refrain from indenting, to avoid long lines.

When list items span multiple lines, we recommend using two spaces after the list item symbol (## or #*)…

Important considerations[...] [list] #* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. #* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. #* Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. [end]

By using two spaces, the text starts in a odd-numbered column (otherwise, it will be frustrating to use the Tab key). This is less of an issue with lists that have only single-line items (use either one or two spaces in such lists).

We recommend wrapping lines at logical spots, and we suggest that each sentence start at the beginning of a line. This makes it easier to add a new sentence, remove a sentence, or move sentences around.

With this approach, nearly every line will have some extra space, which is handy when making minor adjustments, such as font style, punctuation, and minor wordsmithing. In contrast, if you attempt to make every line as close to 65 columns as possible, you will often succeed, ending up with lines of 63-65 columns. These are difficult to work with: even minor changes, such as bolding a word or two, often cause you to shift the last word onto the next line. That can cause a ripple effect, causing you to adjust the remaining lines in the paragraph.

We recommend against word wrapping paragraphs with automated tools (such as Edit | Wrap Text in DSEdit). There are couple of reasons…

• Automatic word wrapping will often lead to line breaks at inopportune places. For example, while line breaks are allowed in most tags, a line break may change the HTML output (the [link], [j], and [img] tags are just a few examples).

• A change early in a paragraph may cause the remainder of the lines in the paragraph to be modified. This creates a mess for Code Vault's diff view (making it difficult to see what has really changed in a given revision of the file).

For example, here's a sample paragraph with automatic word wrapping…

Fibers are deterministic, in that one fiber explicitly switches to another fiber, at specific locations in the program. By contrast, the operating system implicitly switches from one thread to an unpredictable other thread, at an unpredictable time. Thus, with threads (and not with fibers), a program often behaves differently on different hardware, or under different load conditions.

Above, two of the seven lines are 63 characters long, so even minor changes to these lines may exceed column 65. It is also difficult to scan the paragraph for sentences.

Here is the same paragraph as formatted in the relevant .sage file…

Fibers are deterministic, in that one fiber explicitly switches to another fiber, at specific locations in the program. By contrast, the operating system implicitly switches from one thread to an unpredictable other thread, at an unpredictable time. Thus, with threads (and not with fibers), a program often behaves differently on different hardware, or under different load conditions.

This version is two lines longer, but the lines have more breathing room. It is also easier to glance and see that the paragraph has three sentences (just look in the first column for capital letters).