Software Requirements Specification (SRS) Demo using mdBook

This project represents a manually crafted Software Requirements Specification (SRS), utilizing mdBook, for the Projectile case study within the Drasil framework. It is intended to serve as a foundational reference for future Drasil development, guiding the generation of a new SRS artifact format.

Installation

Please follow the installation instructions in the mdBook Documentation.

Demo

1. Clone the Repository: Clone this repository to your local machine.
2. Launch the Server: Open a command line interface in the cloned repository's directory and run mdbook serve --open.
3. Acces the Local Server: The terminal will display the localhost server address.

mdBook Quirks

• Have to wrap certain elements in <div id=""></div> to be able to be referenced.

  projectileSRS-mdbook/src/non-functional-req.md

  Lines 4 to 16 in f161644

  	<div id="correct">
  	Correct: The outputs of the code have the properties described in [Properties of a Correct Solution](./properties-of-solution.md).
  	</div>
  	<div id="verifiable">
  	Verifiable: The code is tested with complete verification and validation plan.
  	</div>

• Cannot add captions to tables and images. Have to use <p align="center">CAPTION</p>.

  projectileSRS-mdbook/src/table-of-symbols.md

  Lines 47 to 49 in f161644

  	**<p align="center">Table of Symbols</p>**

• Mathjax LaTeX equations do not wrap similar to LaTeX ($EQUATION$) or HTML (\(EQUATION\)). mdBook syntax is \\(EQUATION\\) for inline and \\[EQUATION\\] for block equations.
• Some elements of equations require an extra \. Ex. new line is \\\.
• \symbf does not work in Mathjax LaTeX equations, have to use \boldsymbol instead.
• Typical list syntax does not work inside tables in Markdown. Have to wrap in <ul> <li>item1</li> <li>item2</li> </ul>.

  projectileSRS-mdbook/src/data-definitions.md

  Line 13 in f161644

  |Description|<ul><li> \\(v\\) is the speed (\\(\frac{\text{m}}{\text{s}}\\)) </li><li> \\(\boldsymbol{v}\text{(}t\text{)}\\) is the velocity (\\(\frac{\text{m}}{\text{s}}\\)) </li></ul>|

• Accessible assets (Ex. images) need to be inside the src folder in order to be rendered. NOTE: There may be a way to use assets outside src through the book.toml
• Sometimes there is very little space or no space at all between components. Added </br> to add extra space.
• Need to add mathjax support in the book.toml. Not added by default.

Other Notes

• Having a page for Table of Contents may be redundant as mdBook automatically creates one for you.
• The HTML SRS for variables or short equations often uses HTML syntax, rather than LaTeX. For example, <em></em> for italicizing single variables. This creates slight differences in appearance within the SRS. The mdBook demo uses LaTeX for everything.
• Each section and subsection has its own page. As a result, some pages have very little content.
• Can format code for tables in two ways. Both formats look the same when rendered.
  • Visually readable code but longer

    projectileSRS-mdbook/src/table-of-units.md

    Lines 6 to 12 in 9cc1553

    	|Symbol |Description|SI Name|
    	|---------|-----------|-------|
    	|\\(m\\) |length |metre |
    	|\\(rad\\)|angle |radian |
    	|\\(s\\) |time |second |

  • Less readable code but shorter

    projectileSRS-mdbook/src/auxiliary-constants.md

    Lines 4 to 10 in 9cc1553

    	|Symbol|Description|Value|Unit|
    	|-|-|-|-|
    	|\\(g\\)|magnitude of gravitational acceleration|\\(9.8\\)|\\(\frac{\text{m}}{\text{s}^{2}}\\)|
    	|\\(ε\\)|hit tolerance|\\(2.0\\%\\)|--|
    	|\\(π\\)|ratio of circumference to diameter for any circle|\\(3.14159265\\)|--|