pub const DATA: &'static str = r##"
# Welcome to the rst tutorial! This file is written just like
# rst toml files are.
#
# You can get to this stage in the tutorial at any time by running:
#
# rst tutorial
#
# rst is a command line, text based tool for requirements tracking.
# It aims to be easy to use by anybody and especially productive
# for developers
#
# Follow along with this file to get an idea of how you can
# easily write and track requirements in your source code
#
# Before we continue too far, why don't you try a command? Type
# the following command:
#
# rst ls REQ-learn-rst -l
#
# You should see a colorized artifact. If you do, good. If you are having
# problems try going back to the installation tutorial at github.com/vitiral/rst
##################################################
# Defining requirements
# This is how you define a requirement
[REQ-toml]
text = '''
rst files like this one are written in the TOML format
you can read more about it here: https://github.com/toml-lang/toml
All rst files must end in ".toml"
They are all flat. This means rst does not support the "[first.second]"
syntax. This means that the "." character is illegal in names
'''
[REQ-learn-rst]
text = '''
Artifacts are defined by specifying their name like so: "[REQ-NAME]"
Artifacts can be a requirement (REQ), design-specification (SPC)
risk (RSK) or test (TST)
This particular artifact is a requirement, therefore it begins with
"REQ". After REQ there is a "-" and then the name of the requirement.
Unlike many requirements tracking tools, rst encourages the use
of human-readable names. We will talk more about this later.
'''
[SPC-learn-spc]
partof = "REQ-toml"
text = '''
Anything starting with SPC is a design specification. Requirements (REQ)
should be used for detailing "what you want your application to do" and
design specifications (SPC) should be used for detailing "how your application
will do it".
There are also tests (TST) and risks (RSK) which we will learn about later.
'''
[REQ-learn-partof]
text = "see the next artifact"
[SPC-learn-partof]
partof = "REQ-learn-rst"
text = '''
rst uses the names of artifacts to automatically link them and track progress.
This makes it easy for the user to intuitively link together requirements with
specification and reduces boilerplate.
REQ-learn-rst is explicitly a "partof" this artifact because it is specified
explicitly.
REQ-learn-partof is automatically a "partof" this artifact because the names
after the type are the same.
In addition, missing parents are automatically created and linked. So
SPC-LEARN is also a partof this artifact, even though it is not even in this
document. This makes it very easy to make trees of artifacts without needing to
specify every branch.
So far we have:
```
--- SPC-LEARN <--- SPC-learn-spc
/
REQ <-- REQ-LEARN <-- REQ-learn-partof <-- SPC-learn-partof
^ |
\-------- REQ-learn-rst <----------/
* items in ALL CAPS were created automatically
```
> Note: only parents are created automatically. Auto-creating for similar-named
> artifacts would pollute your links
>
> Note: RSK artifacts are never automatically linked by name (only their parents
> are automatically created and linked)
'''
[SPC-learn-example]
text = "this is used in the next artifact"
[TST-learn-partof]
partof = "SPC-learn-[spc, example]"
text = '''
The partof field is a string that uses a simple grouping syntax. This example
does as you would expect, this artifact is a partof SPC-learn-spc and
SPC-learn-example
Note: it is also automatically a partof SPC-learn-partof and TST-LEARN because
of the name
'''
[SPC-learn-valid]
text = '''
There are only a few rules for defining artifacts:
- case is ignored for all names (except globals and settings)
- names cannot overlap, even in different files
- all items (i.e. [REQ-foo]) must start with either REQ, RSK, SPC or TST
*except* for "globals" and "settings"
- artifact names must follow SPC-learn-links (see bellow)
'''
[SPC-learn-links]
partof = "SPC-learn-partof"
text = '''
There are some rules for which artifacts can be a partof other artifacts:
- all artifacts can be a partof their own group (i.e. SPC can be a partof SPC)
- SPC and RSK can be a partof REQ
- TST can be a partof SPC and RSK
- REQ can only be a partof itself
Here is a helpful graph of valid relations:
```
REQ <-- SPC <-- TST
^ |
\---- RSK <-----/
```
In other words, you can design a spec (SPC) based on
a requirement (REQ). A requirement can also have a risk (RSK)
associated with it. Tests can test to either a spec (SPC)
or to a risk (RSK)
'''
[SPC-learn-type-rsk]
text = '''
the RSK type allows you to specify risks associated with your requirements
(RSK can be partof REQ).
Frequently (for larger projects especially) it is a good idea to do risk
analysis on which areas of your application are most likely to fail and
which would be the most catastrophic. RSK artifacts allow you to document these
and design test cases based on them.
'''
[SPC-learn-tst]
text = '''
TST is used to document test design and is the only way that an artifact can be
considered "tested".
'''
[SPC-learn-ls]
text = '''
The `ls` command is the most important component to learn in rst, as it helps
you manage the artifacts in your project, see how they are linked, and view how
completed/tested they are.
Type:
rst ls SPC-learn-ls -l
This will show you this artifact, pretty printed on your terminal.
Try:
rst ls learn -p
This searches in the "Name" field for all artifacts that have "learn"
in their name.
Let's say you wanted to find an artifact, and all you knew was that it mentioned
files in it's text field. You could run:
rst ls file -p T -T
This will search for the pattern "file" in the text field (`-p T`). It will also
display a short piece of the text field (`-T`)
Now let's say that You see that SPC-learn-valid is what you were looking for,
but you want an expanded view:
rst ls SPC-learn-valid -l
Now you see that SPC-learn-valid has not been tested or implemented and that it
is partof SPC-LEARN. From there you could decide what to do.
'''
##################################################
# That is the end part 1 of the tutorial. Run the following
# for part 2:
# rst tutorial 2
"##;