Table of Contents

1 TUT003 {#TUT003}

1.1 TUT001 {#TUT001}

Creating a New Document and Adding Items

Enter a VCS working copy:

$ cd /tmp/doorstop

Create a new document:

$ doorstop create REQ ./reqs

Add items:

$ doorstop add REQ
$ doorstop add REQ
$ doorstop add REQ

Edit the new items in the default text editor:

$ doorstop edit REQ1
$ doorstop edit REQ2

Parent links: REQ003 Identifiers, REQ004 Formatting

Child links: HLT001

1.2 TUT002 {#TUT002}

Creating a Child Document with Links to the Parent Document

Enter a VCS working copy:

$ cd /tmp/doorstop

Create a new child document:

$ doorstop create TST ./reqs/tests --parent REQ

Add new items:

$ doorstop add TST
$ doorstop add TST

Edit the new items in the default text editor:

$ doorstop edit TST1
$ doorstop edit TST2

Add links to item's in the parent document:

$ doorstop link TST1 REQ1
$ doorstop link TST1 REQ3
$ doorstop link TST2 REQ1
$ doorstop link TST2 REQ2

Parent links: REQ003 Identifiers, REQ004 Formatting, REQ011 Storing requirements, REQ012 Change management, REQ013 Author information

Child links: HLT001

1.3 TUT004 {#TUT004}

Removing Items and Links

Enter a VCS working copy:

$ cd /tmp/doorstop

Remove a link between two document items:

$ doorstop unlink TST1 REQ3

Remove a document's item:

$ doorstop remove REQ3

Parent links: REQ003 Identifiers, REQ011 Storing requirements, REQ012 Change management, REQ013 Author information

Child links: HLT001

1.4 TUT008 {#TUT008}

Validating the Tree

Enter a VCS working copy:

$ cd /tmp/doorstop

Build and validate the tree:

$ doorstop

Parent links: REQ003 Identifiers

Child links: HLT001

1.5 Lot's of different little examples in a single heading which is very long TUT017 {#TUT017}

Headings 3

Markdown can be used to format text.

Heading 4

Heading 5

Emphasis

Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. ~~Scratch this.~~

Paragraphs

When exporting to html using doorstop newlines are converted to line breaks.

An empty line is required to start a new paragraph.

Lists

  1. First ordered list item
  2. Another item

  3. Actual numbers don't matter, just that it's a numbers

  4. Unordered list can use asterisks

  5. Or minuses
  6. Or pluses

Tables

Colons can be used to align columns.

Tables Are Cool
col 3 is right-aligned $1600
col 2 is centered $12
zebra stripes are neat $1

There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.

Markdown Less Pretty
Still renders nicely
1 2 3

UML Diagrams

PlantUML-Guide explains the syntax for all supported diagram types. Here you see an exemplary state chart diagram:

```plantuml format="png" alt="State Diagram Loading" title="State Diagram" @startuml scale 600 width

[] -> State1 State1 --> State2 : Succeeded State1 --> [] : Aborted State2 --> State3 : Succeeded State2 --> [] : Aborted state State3 { state "Accumulate Enough Data\nLong State Name" as long1 long1 : Just a test [] --> long1 long1 --> long1 : New Data long1 --> ProcessData : Enough Data } State3 --> State3 : Failed State3 --> [] : Succeeded / Save Result State3 --> [] : Aborted

@enduml


### Math LaTex

You can use Math LaTex expressions as `$$k_{n+1} = n^2 + k_n^2 - k_{n-1}$$`
which is rendered like this:

$$k_{n+1} = n^2 + k_n^2 - k_{n-1}$$

Alternatively you can also use inline math like this: `$e=mc^2$` renders as $e=mc^2$.

### Code blocks

Code blocks are either fenced by lines with three back-ticks \`\`\`. Optionally, you can add an
identifier for the language to use for syntax highlighting. For example, this snippet
shows a Python code block and thus starts with \`\`\`python:

```python
def fibonacci(n):
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()
fibonacci(1000)

They can also be inline code by a single back-tick `.

C-code can be rendered with syntax highlighting by using the c identifier (```c):

#include <stdio.h>
int main() {
    printf("Hello, World!");
    return 0;
}

Parent links: REQ004 Formatting

Child links: HLT001

1.6 Sub headings {#TUT018}

Sub headings

1.6.1 TUT019 {#TUT019}

Sub headings can be created by a level that ends in .0

Parent links: REQ004 Formatting

Child links: HLT001

2.0 Publishing Documents {#TUT005}

Publishing Documents

2.1 TUT009 {#TUT009}

Publishing a Document as Text

Enter a VCS working copy:

$ cd /tmp/doorstop

Display the documents on standard output:

$ doorstop publish req
$ doorstop publish tst

Parent links: REQ007 Viewing documents

Child links: HLT002

2.2 TUT010 {#TUT010}

Publishing All Documents as an HTML Directory

Enter VCS working copy:

$ cd /tmp/doorstop

Create an HTML directory for all documents:

$ doorstop publish all path/to/htmldir

Parent links: REQ007 Viewing documents

Child links: HLT002

2.3 TUT020 {#TUT020}

Include custom attributes in published output

Include the custom attribute that should be published in .doorstop.yml, e.g.

settings:
  digits: 3
  prefix: TUT
  sep: ''
attributes:
  publish:
    - CUSTOM-ATTRIB

Parent links: REQ007 Viewing documents

Attribute Value
CUSTOM-ATTRIB True

3.0 Importing Content {#TUT011}

Importing Content

3.1 TUT016 {#TUT016}

Importing a File

Enter a VCS working copy:

cd /tmp/doorstop

Create a document for the import:

doorstop create HLR

Import from an exported document:

doorstop import path/to/exported.xlsx HLR

Parent links: REQ016 Importing content

Child links: HLT003

3.2 TUT012 {#TUT012}

Importing a Document

Enter a VCS working copy:

$ cd /tmp/doorstop

Import a document:

$ doorstop import --document HLR reqs/hlr

Import a document with a parent:

$ doorstop import --document LLR reqs/llr --parent HLR

Parent links: REQ016 Importing content

Child links: HLT003

3.3 TUT013 {#TUT013}

Importing an Item

Enter a VCS working copy:

$ cd /tmp/doorstop

Import an item:

$ doorstop import --item HLR HLR001

Import an item with attributes:

$ doorstop import --item LLR LLR001 --attr "{'text': 'The item text.'}"

Parent links: REQ016 Importing content

Child links: HLT003

4.0 Exporting Content {#TUT014}

Exporting Content

4.1 TUT015 {#TUT015}

Exporting a Document

Enter a VCS working copy:

$ cd /tmp/doorstop

Export a document to standard outout:

$ doorstop export LLR

Export all documents to a directory:

$ doorstop export all dirpath/to/exports

Export documents using specific formats:

$ doorstop export REQ path/to/req.xlsx

Parent links: REQ017 Exporting content

Child links: HLT004

5.0 Detailed examples {#TUT021}

Detailed examples

5.1 Lists TUT022 {#TUT022}

Parent links: REQ017 Exporting content

5.1.1 Nested list TUT023 {#TUT023}

This is an example on how to create a list: * Item 1 * Item 2 * Nested list * Item 2.1 * Item 2.2 * Deeper nesting * Item 2.2.1 * Item 2.2.2 * Item 2.2.3 + Empty + Nesting * Should work - too!

Note: The list above is not numbered, and it works with both *, + and -. It also works with two (2) or four (4) space indentation, although you should keep the same indentation in the list.

5.1.2 Ordered list with empty items TUT024 {#TUT024}

This is an example with nesting and empty list items: 1. Item 1 1. Item 2 1. Item 2.1 1. Item 2.1.1 1. Item 3

Notes:

Numered (or ordered) lists in Markdown are a bit special.

They are identified with a number followed immediatly by a . (dot).

What number does not really matter!

Therefore, the easiest way to make sure all differenct markdown renderers handles the list correctly is to use the same number for all items in the list, i.e., 1.

The indentation is also important. Whereas the unordered lists can handle different indentation, the ordered lists must have four (4) spaces indentation for each level!

IMPORTANT

Ordered lists that are nested in Markdown cannot automatically handle nested numbering! In other words, each nested level will start with the number 1!

5.1.3 Another list example TUT025 {#TUT025}

Another list example: 1. Item 1 1. Item 1.1 1. Item 1.2 1. Item 2 1. Item 2.1