Sage
Welcome to Sage
Volume (77%) Hide Volume ☆
Topics ⬆ ⬇
Enterprise Style Guidelines
This article offers a set of guidelines for creating documentation for Enterprise tools and libraries, mostly related to the final HTML output. A separate guide discusses formatting Sage source files.

Identifiers

Identifiers, including the names of units, types, methods, constants, and variables, should be indicated using monospace: either with `...` or with [m]...⁠[end].

Note

In our Word documents, identifiers were typically indicated using italics. Thus, when converting a Word doc to Sage, most italics should be turned into monospace (except for instances of italics that were for emphasis, not to indicate an identifier).


Code Samples

Code samples should include a blank line before and after. For example, like this…

Here is a typical for loop…

for i := 0 to List.Count-1 do Writeln(List[i].Name);

Note that List.Count is only evaluated once, before the loop begins.

Not like this…

Here is a typical for loop… for i := 0 to List.Count-1 do Writeln(List[i].Name); Note that List.Count is only evaluated once, before the loop begins.

Note: the horizontal bars above are to separate the examples; we wouldn't normally use them for code samples.

Keep It Simple

In various Word docs, you may find a variety of styles for code samples: different fonts, different indenting approaches, some with boxes around the example, etc. Ignore all that, and just write code samples like this…

Here is a typical `for` loop[...] [.pas] for i := 0 to List.Count-1 do Writeln(List[i].Name); [end] Note that `List.Count` is only evaluated once, before the loop begins.

⏱ Last Modified: 7/19 1:08:04 pm
In this article (top)  View article's Sage markup
Identifiers Code Samples Keep It Simple
⏱ 7/19 1:08:04 pm