SheepText Tutorial

Tutorial

Welcome to SheepText!

SheepText is a unique and powerful tool designed to transform the way you create diagrams. By using a straightforward text-based language, SheepText allows you to quickly generate complex diagrams, particularly useful for software system visualization. Whether you are a developer, a system architect, or someone who loves organized visual representations, SheepText offers a refreshing approach to diagramming.

What You'll Learn

This tutorial is designed to take you on a journey through the core features of SheepText. By the end, you will be able to:

Create basic and complex diagrams using simple text commands.
Customize your diagrams with colors, text, and various styles.
Understand the fundamental syntax and structure of SheepText.
Utilize advanced layout techniques for intricate diagrams.

How to Use This Tutorial

Interactive Learning: On the right side of your screen, you'll find an interactive editor. As we go through examples in this tutorial, you can click a button to automatically load the example into the editor. This will render the diagram for you to see.
Experimentation: Feel free to modify the examples in the editor. Experimentation is a great way to learn, and you'll see how changes in the text alter the diagram in real-time.
Step-by-Step Approach: The tutorial is structured to gradually build your understanding. Even if some concepts seem simple at first, they form the foundation for more advanced topics later on.
Feedback and Questions: If you have questions or need clarification, remember that learning is a process. Take notes of your queries, as they might get answered in subsequent sections.

Basic Elements of SheepText

Starting with the Basics: Drawing a Box

The fundamental building block in SheepText is the "box." Boxes can represent various components in your diagrams, such as entities, nodes, or systems. Let's start by creating a simple box.

Basic Box Command: To draw a box, you use the box command. Try entering the following in the interactive editor:
```
box
```
Click the button to see a basic box appear in your diagram.
Adding Text to Your Box: Diagrams are more informative with labels. Let's add a label to our box. Modify your command as follows:
```
box "My First Box"
```
This will display a box labeled "My First Box."
Customizing Box Size: You might want your box to be a specific size. SheepText allows you to specify the width and height. Update your command like this:
```
box "Sized Box" width 100 height 50
```
Your box will now have the specified dimensions.

Understanding Syntax and Structure

SheepText has a straightforward syntax, making it easy to learn and use:

Commands and Parameters: Each element in SheepText, like a box, is created using a command followed by optional parameters, such as width and height.
Quotation Marks for Text: When adding text to an element, enclose the text in quotation marks.
Semicolons and Newlines: Each command in SheepText is considered a separate statement. You can either put them on new lines or separate them with semicolons.
For example:
```
box "Box 1";
box "Box 2"
```
This will create two boxes labeled "Box 1" and "Box 2."

Practice Exercise

Try creating a few boxes of different sizes and labels. Experiment with changing the width, height, and text. Remember, the interactive editor is there for you to see the results of your commands instantly.

Arrows

Arrows are crucial in diagrams for indicating relationships or flow directions. In SheepText, drawing arrows between elements is straightforward. Let's learn how to add arrows to our diagrams.

Basic Arrow Command: To draw an arrow, use the arrow command. It automatically connects to the previous element. For example:
```
box "Box A";
arrow;
box "Box B";
```
This sequence creates two boxes with an arrow pointing from "Box A" to "Box B."
Changing Arrow Direction: By default, arrows point to the right. You can change this by specifying a direction (up, down, left, right) after the arrow command. For instance:
```
box "Start";
arrow down;
box "Down";
```
An arrow will be drawn pointing downwards from "Start" to "Down."

Practice Exercise

Create a simple flow diagram using boxes and arrows. Try changing the direction of the arrows and observe how they connect different elements. Experiment with lines as well to see how they differ from arrows in your layout.

Adding and Formatting Text

Enhancing Diagrams with Text

Text in diagrams is crucial for conveying information clearly. SheepText allows you to place text not only within boxes but also along arrows, as standalone elements, or in relation to other components. Let's explore how to utilize text effectively.

Text in Boxes: You've already seen how to add text to boxes. Remember, the text should be enclosed in quotes. For example:
```
box "This is a box"
```
Text on Arrows: Adding text to arrows can clarify the nature of relationships or flows. Place the text in quotes right after the arrow command:
```
box "Start";
arrow "Leads to";
box "End";
```
This creates an arrow labeled "Leads to" between two boxes.
Standalone Text: To place text independently, use the text command. You can position it by specifying coordinates:
```
box "foo"
text "Independent Text" with .nw at (100, 50)
```
This places the text at the specified position on the diagram.
Text Styling: SheepText allows you to style your text with attributes like font style and color. For instance:
```
 text "Bold Text" bold;
 text "Colored Text" color red;
 text "Big text" 70.0
```
The first line creates bold text, while the second line creates red text, and the third line creates text that is point size 70.0.

Formatting and Positioning Text

The real power of SheepText lies in its ability to position and format text precisely. This is where placenames become invaluable.

Introducing Placenames: Placenames are identifiers you can assign to elements like boxes and arrows, allowing you to reference them elsewhere in your diagram. To assign a placename, prepend the element with an identifier followed by a colon:
```
MyBox: box "Box"
```
Now, MyBox is a reference to this particular box.
Positioning Text with Placenames: Once you have placenames, you can position text relative to these elements. For example, to place text above a box:
```
MyBox: box "Box";
text "Above Box" with .sw at MyBox.nw
```
This positions the text at the southwest (sw) corner of the northwest (nw) corner of MyBox, effectively placing it above the box.
Using Coordinates and Corners: The with .<corner> at <placename>.<corner> syntax lets you control the positioning of text relative to the corners of other elements. You can use corners like nw (northwest), se (southeast), c (center), etc., to position elements precisely.

Practice Exercise

Create a diagram with a few boxes and arrows. Add descriptive text to each element and experiment with different text styles and positions. See how the placement and styling of text can change the readability and clarity of your diagram.

Attributes and Styling

Customizing Your Diagrams

After mastering the basics of creating elements and positioning text, the next step is to learn how to customize your diagrams. SheepText allows you to modify various attributes like color, size, and style to enhance the visual appeal of your diagrams.

Coloring Elements: You can change the color of boxes, lines, arrows, and text to make your diagram more informative and visually appealing. Use the color attribute followed by a color name or hexadecimal value:
```
Box1: box "Colored Box" fill #FF5733;
text "Colored Text" color blue;
Box2: box "Outline" with .n at Box1.s stroke #ff0000
```
This will create a box with an orange color, text in blue, and an outlined box with a red stroke.
Adjusting Size: Modifying the size of elements is crucial for emphasizing certain parts of your diagram. Use width and height for boxes and size for text:
```
box "Wide Box" width 150;
text "Big Text" 20;
```
This creates a wider box and larger text.
Border and Style: To style a box, you can add borders, make lines dashed, and more. For instance:
```
box "Styled Box" dashed 2;
```
This command creates a box with a dashed border and a specified stroke width.

Advanced Styling with Placenames

Utilizing placenames, you can create more complex styling relative to other elements in your diagram:

Positioning Based on Other Elements: You can position boxes and text relative to others using their placenames. For example, to place a box to the right of another:
```
FirstBox: box "First";
SecondBox: box "Second" with .nw at FirstBox.ne + (10, 0);
```
This places SecondBox 10 pixels to the right of FirstBox.
Layering with 'Send to Back': You can manage the layering of elements, especially useful in complex diagrams:
```
Box1: box "Foo"
arrow
Box2: box "Bar"
 
Group: box from Box1.nw - (30, 30) \
           to Box2.se + (30, 30) \
           send to back dashed fill #eee
text "Group" italic with .nw at Group.nw + (5, 5)
```
This creates a box that covers the area between Box1 and Box2, with a dashed border and a light gray fill, and places the text "Group" in the northwest corner of the box. This is useful for grouping elements together and highlighting specific parts of your diagram.

Practice Exercise

Create a diagram with multiple elements and experiment with their attributes. Try changing colors, sizes, and styles. Use placenames to position elements in relation to each other, and explore layering techniques. See how these stylistic changes impact the overall look and feel of your diagram.

Using Icons in SheepText

SheepText comes equipped with a variety of icons, perfect for enhancing software system diagrams with recognizable symbols. Here's how you can utilize them:

Adding Icons: To add an icon, use the icon command followed by its name and optional text. For instance:
```
icon name "aws_Res_User_Light" "User"
```
This places an AWS User icon in your diagram.
Finding Icons: If you're unsure of the icon name, start typing it out, and the editor will suggest available icons. For example:
```
icon name "dynamodb"
```
If the icon doesn't exist or is mistyped, SheepText will guide you with suggestions.
Positioning and Styling Icons: Just like boxes and text, you can position and style icons. They can be named and positioned relative to other elements:
```
LB: icon name "aws_Res_Elastic-Load-Balancing_Application-Load-Balancer_Light" "Load Balancer"
arrow
FE: icon name "aws_Res_Amazon-EC2_Instances_Light" "Frontend Instances"
```
Here, LB and FE are placenames for the respective icons.

Practice Exercise

Create a diagram incorporating different icons. Experiment with positioning them in relation to boxes or other icons. Try using the autocomplete feature to discover new icons.

Variables and Expressions

Dynamic Diagram Creation with Variables

Variables in SheepText add a dynamic aspect to your diagrams, allowing for more flexibility and complexity. You can define variables and use them to determine the size, position, and other attributes of your elements.

To define a variable, use the syntax <variable_name> = <value>:

boxWidth = 100;
boxHeight = 50;

box "Variable Sized Box" width boxWidth height boxHeight;

boxWidth and boxHeight can be used to specify dimensions of boxes.

Expressions for Dynamic Values

Expressions in SheepText allow you to perform calculations and operations on variables or numbers, providing even more control over your diagrams.

Basic Arithmetic: You can use basic arithmetic operations like addition (+), subtraction (-), multiplication (*), and division (/) in your expressions:
```
boxHeight = 50;
doubleHeight = boxHeight * 2;
box "Double Height Box" height doubleHeight;
```
This creates a box with double the height of the initial boxHeight value.
Complex Expressions: For more advanced manipulation, combine variables and arithmetic operations:
```
box
xPos = 100;
yPos = 200;
text "Positioned Text" with .nw at (xPos + 50, yPos - 100);
```
This positions the text based on calculated coordinates.

Sometimes you will want to draw arrows or place elements based on calculations. For example, you can draw a pair of arrows to and from two boxes:

Frontend: box "Frontend"
Backend: box "Backend" with .c at Frontend.c + (Frontend.width * 2, 0)
arrow from 1/3 <Frontend.ne, Frontend.se> to 1/3 <Backend.nw, Backend.sw> "(1)"
arrow from 2/3 <Backend.nw, Backend.sw> to 2/3 <Frontend.ne, Frontend.se> "(2)"

Using Built-in Variables for Enhanced Customization

In addition to defining your own variables, SheepText provides a set of built-in variables. These pre-defined variables allow you to easily adjust common attributes of your diagrams, ensuring consistency and saving time. Here are the built-in variables available in SheepText:

linesize: Sets the size of lines and arrows. Default is 100.0.
dashwid: Determines the width of dashes in dashed lines. Default is 10.0.
strokewid: Specifies the stroke width for elements. Default is 1.0.
boxwid: Sets the default width for boxes. Default is 100.0.
boxht: Defines the default height for boxes. Default is 62.0.
iconwid: Adjusts the width of icons. Default is 48.0.
iconht: Alters the height of icons. Default is 48.0.
fontsize: Sets the default font size for text. Default is 16.0.

These variables can be used as is or modified to fit the needs of your diagram.

Example Using Built-in Variables

Let's create an example that utilizes some of these built-in variables to illustrate their practical application:

// Adjusting default variables
linesize = 120.0;
dashwid = 15.0;
strokewid = 2.0;
boxwid = 120.0;
boxht = 70.0;
iconwid = 60.0;
iconht = 60.0;
fontsize = 18.0;

// Creating elements using adjusted variables
Box1: box "Custom Box";
Line: arrow dashed;
Text: text "Custom Text" with .nw at Line.ne + (5, 5);

// Adding an icon with custom size
Icon: icon name "aws_Res_Generic-database_Light" with .c at Box1.c - (0, boxht);

This example demonstrates how you can modify the built-in variables to influence the size and style of various diagram components.

Practice Exercise

Create a diagram using variables to set the size and position of your elements. Experiment with expressions to dynamically adjust these properties. Try creating a layout where the position of one element depends on the size or position of another. This will help you understand the power of variables and expressions in creating adaptive diagrams.

End of tutorial

Thank you for reading.

Loading, please wait...