drasil-docLang-0.1.26.0: A framework for code and document generation for scientific software - Document Language SubPackage
Safe HaskellSafe-Inferred
LanguageHaskell2010

Drasil.DocLang

Description

Re-export document language types and functions for easy use in other packages.

Synopsis

Document Language

SRS

For generating Software Requirements Specifications.

Types

type SRSDecl = [DocSection] Source #

A Software Requirements Specification Declaration is made up of all necessary sections (DocSections).

data DocSection Source #

Contains all the different sections needed for a full SRS (SRSDecl).

Constructors

TableOfContents

Table of Contents

RefSec RefSec

Reference.

IntroSec IntroSec

Introduction.

StkhldrSec StkhldrSec

Stakeholders.

GSDSec GSDSec

General System Description.

SSDSec SSDSec

Specific System Description.

ReqrmntSec ReqrmntSec

Requirements.

LCsSec

Likely Changes.

UCsSec

Unlikely Changes.

TraceabilitySec TraceabilitySec

Traceability.

AuxConstntSec AuxConstntSec

Auxiliary Constants.

Bibliography

Bibliography.

AppndxSec AppndxSec

Appendix.

OffShelfSolnsSec OffShelfSolnsSec

Off the Shelf Solutions.

newtype ReqrmntSec Source #

Requirements section (wraps ReqsSub subsections).

Constructors

ReqsProg [ReqsSub] 

data ReqsSub where Source #

Requirements subsections.

Constructors

FReqsSub :: Sentence -> [LabelledContent] -> ReqsSub

Functional requirements. LabelledContent for tables (includes input values).

FReqsSub' :: [LabelledContent] -> ReqsSub

Functional requirements. LabelledContent for tables (no input values).

NonFReqsSub :: ReqsSub

Non-Functional requirements.

data PDSub where Source #

Problem Description subsections.

Constructors

TermsAndDefs :: Concept c => Maybe Sentence -> [c] -> PDSub

Terms and Definitions.

PhySysDesc :: Idea a => a -> [Sentence] -> LabelledContent -> [Contents] -> PDSub

Physical System Description.

Goals :: [Sentence] -> PDSub

Goals.

data ProblemDescription where Source #

Problem Description section.

Constructors

PDProg :: Sentence -> [Section] -> [PDSub] -> ProblemDescription 

newtype SSDSec Source #

Specific System Description section (wraps SSDSub subsections).

Constructors

SSDProg [SSDSub] 

data SSDSub where Source #

Specific System Description subsections.

Constructors

SSDProblem :: ProblemDescription -> SSDSub

Problem description.

SSDSolChSpec :: SolChSpec -> SSDSub

Solution characteristics.

data SCSSub where Source #

Solution Characteristics Specification subsections.

Constructors

Assumptions :: SCSSub

Assumptions.

TMs :: [Sentence] -> Fields -> SCSSub

Theory models.

GDs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub

General definitions.

DDs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub

Data definitions.

IMs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub

Instance models.

Constraints :: (HasUncertainty c, Quantity c, Constrained c, HasReasVal c, MayHaveUnit c) => Sentence -> [c] -> SCSSub

Constraints.

CorrSolnPpties :: (Quantity c, Constrained c) => [c] -> [Contents] -> SCSSub

Properties of a correct solution.

data SolChSpec where Source #

Solution Characteristics Specification section (wraps SCSSub subsections).

Constructors

SCSProg :: [SCSSub] -> SolChSpec 

newtype AppndxSec Source #

Appendix section.

Constructors

AppndxProg [Contents] 

data AuxConstntSec Source #

Values of Auxiliary Constants section.

Constructors

AuxConsProg CI [ConstQDef] 

data DerivationDisplay Source #

Choose whether to show or hide the derivation of an expression.

data Emphasis Source #

How to handle emphasis of words.

Constructors

Bold 
Italics 

Instances

Instances details
Show Emphasis Source # 
Instance details

Defined in Drasil.DocumentLanguage.Core

newtype OffShelfSolnsSec Source #

Off-The-Shelf Solutions section.

Constructors

OffShelfSolnsProg [Contents] 

newtype GSDSec Source #

General System Description section (wraps GSDSub subsections).

Constructors

GSDProg [GSDSub] 

data GSDSub where Source #

General System Description subsections.

Constructors

SysCntxt :: [Contents] -> GSDSub

System context.

UsrChars :: [Contents] -> GSDSub

User characteristics.

SystCons :: [Contents] -> [Section] -> GSDSub

System constraints.

data IntroSec Source #

Introduction section. Contents are top level followed by a list of subsections.

Constructors

IntroProg Sentence Sentence [IntroSub]

Temporary, will be modified once we've figured out more about the section.

data IntroSub where Source #

Introduction subsections.

Constructors

IPurpose :: [Sentence] -> IntroSub

Describes purpose of the system.

IScope :: Sentence -> IntroSub

Describes scope of the system.

IChar :: [Sentence] -> [Sentence] -> [Sentence] -> IntroSub

Describes characteristics of the system.

IOrgSec :: CI -> Section -> Sentence -> IntroSub

Organises the section.

data LFunc where Source #

Lens (lookup) functions (currently for TSymb).

Constructors

Term :: LFunc 
Defn :: LFunc 
TermExcept :: [DefinedQuantityDict] -> LFunc 
DefnExcept :: [DefinedQuantityDict] -> LFunc 
TAD 

Fields

  • :: LFunc

    Term and Definition.

data Literature Source #

Types of literature.

Constructors

Lit Topic

Literature (with a Topic).

Doc' Topic

Existing documentation for (plural version of topic).

Manual Topic

Manual.

data RefSec Source #

Reference section. Contents are top level followed by a list of subsections.

Constructors

RefProg Contents [RefTab] 

data RefTab where Source #

Reference subsections (tables) made out of units or symbols (can be customized).

Constructors

TUnits :: RefTab

Default table of units.

TUnits' :: [TUIntro] -> ([UnitDefn] -> LabelledContent) -> RefTab

Customized introduction.

TSymb :: [TSIntro] -> RefTab

Adds an introduction for a table of symbols.

TSymb' :: LFunc -> [TSIntro] -> RefTab

Allows Lens functions in addition to an introduction for a table of symbols.

TAandA :: RefTab

Default.

newtype StkhldrSec Source #

Stakeholders section (wraps stakeholders subsections StkhldrSub).

Constructors

StkhldrProg [StkhldrSub] 

data StkhldrSub where Source #

Stakeholders subsections.

Constructors

Client :: CI -> Sentence -> StkhldrSub

May have a client.

Cstmr :: CI -> StkhldrSub

May have a customer.

data TConvention Source #

Possible typographic conventions.

Constructors

Vector Emphasis

How vectors are emphasized.

Verb Sentence

Verbatim for specialized conventions.

newtype TraceabilitySec Source #

Traceability Matices and Graphs section. Contains configurations (TraceConfig).

Constructors

TraceabilityProg [TraceConfig] 

data TSIntro Source #

For creating a table of symbols introduction

Constructors

TypogConvention [TConvention]

Typographic conventions used.

SymbOrder

Symbol ordering (defaults to alphabetical).

SymbConvention [Literature]

Symbol conventions match specified literature.

TSPurpose

Purpose of the Table of Symbols.

VectorUnits

Definition of vector components.

data TUIntro Source #

For creating the table of units introduction.

Constructors

System

System of units (defaults to SI).

Derived

Sentence about derived units being used alongside SI.

TUPurpose

Purpose of the table of units.

Functions

mkDoc :: SRSDecl -> (IdeaDict -> IdeaDict -> Sentence) -> SystemInformation -> Document Source #

Creates a document from a document description, a title combinator function, and system information.

fillTraceSI :: SRSDecl -> SystemInformation -> SystemInformation Source #

Helper for filling in the traceability matrix and graph information into the system.

fillcdbSRS :: SRSDecl -> SystemInformation -> SystemInformation Source #

Assuming a given ChunkDB with no traces and minimal/no references, fill in for rest of system information. Currently fills in references, traceability matrix information and IdeaDicts.

findAllRefs :: Section -> [Reference] Source #

Recursively find all references in a section (meant for getting at LabelledContent).

Notebook

For generating Jupyter notebook lesson plans.

Types

type LsnDecl = [LsnChapter] Source #

A Lesson Plan notebook declaration is made up of all necessary chapters (LsnChapters).

data LsnChapter Source #

Contains all the different chapters needed for a notebook lesson plan (LsnDecl).

newtype Intro Source #

Constructors

IntrodProg [Contents] 

newtype LearnObj Source #

Constructors

LrnObjProg [Contents] 

newtype Review Source #

Constructors

ReviewProg [Contents] 

newtype CaseProb Source #

Constructors

CaseProbProg [Contents] 

newtype Example Source #

Constructors

ExampleProg [Contents] 

newtype Smmry Source #

Constructors

SmmryProg [Contents] 

newtype Apndx Source #

Constructors

ApndxProg [Contents] 

Functions

mkNb :: LsnDecl -> (IdeaDict -> IdeaDict -> Sentence) -> SystemInformation -> Document Source #

Creates a notebook from a lesson description and system information.

Subsection Functions

Definitions and Models

data Field Source #

Fields that should be displayed in definitions.

Instances

Instances details
Show Field Source #

Defines Fields as Spaces.

Instance details

Defined in Drasil.DocumentLanguage.Definitions

Methods

showsPrec :: Int -> Field -> ShowS #

show :: Field -> String #

showList :: [Field] -> ShowS #

type Fields = [Field] Source #

Synonym for a list of Fields.

data InclUnits Source #

Determines whether to include or ignore units.

Constructors

IncludeUnits

In description field (for other symbols).

data Verbosity Source #

Refers to the verbosity of statements.

Constructors

Verbose

Full Descriptions.

Succinct

Simple Description (do not redefine other symbols).

ddefn :: Fields -> SystemInformation -> DataDefinition -> LabelledContent Source #

Create a data definition using a list of fields, a database of symbols, and a QDefinition (called automatically by SCSSub program).

Traceability

mkGraphInfo :: SystemInformation -> GraphInfo Source #

Extracts traceability graph inforomation from filled-in SystemInformation.

traceyGraphGetRefs :: String -> [Reference] Source #

Create references to traceability graphs given an example name. Primarily used for reference database in examples.

traceMatStandard :: SystemInformation -> [TraceConfig] Source #

Helpers to check if given argument has more than one peice of information

Contains traceability matrix assumptions, other assumptions, refinement, and other requirements.

traceMatOtherReq :: SystemInformation -> TraceConfig Source #

Records other requirements. Converts the SystemInformation into a TraceConfig.

generateTraceMap :: [DocSection] -> TraceMap Source #

Creates a traceability map from document sections.

Auxiliary Constants

tableOfConstants :: [ConstQDef] -> LabelledContent Source #

Helper that gets a table of constants from a QDefinition.

Introduction

purpDoc :: CI -> Verbosity -> [Sentence] Source #

Combines purpDocPara1 and developmentProcessParagraph. Verbosity controls if the developmentProcessParagraph is added or not.

Reference Material

intro :: Contents Source #

Default Reference Material section introduction.

emptySectSentPlu :: NamedIdea n => [n] -> Sentence Source #

Helper for variants of emptySectSent

emptySectSentSing :: NamedIdea n => [n] -> Sentence Source #

Helper for variants of emptySectSent

tsymb :: [TSIntro] -> RefTab Source #

Default is term and given introduction.

Table of symbols constructor.

tsymb'' :: [TSIntro] -> LFunc -> RefTab Source #

Table of symbols constructor. Takes a custom function and introduction.

unitTableRef :: Reference Source #

Makes a reference to the Table of Units.

tunit :: [TUIntro] -> RefTab Source #

Table of units with an SI Name.

Table of units constructors.

tunit' :: [TUIntro] -> RefTab Source #

Table of units with SI name in the description column.

Table of units constructors.

tunitNone :: [TUIntro] -> RefTab Source #

Table of units with SI name in the description column.

Table of units constructors.

Requirements

inReq :: Sentence -> ConceptInstance Source #

Creates a ConceptInstance of input values.

inTable :: (Quantity i, MayHaveUnit i) => [i] -> LabelledContent Source #

Creates a generalized input-value table for the Requirements section.

mkInputPropsTable :: (Quantity i, MayHaveUnit i, HasShortName r, Referable r) => [i] -> r -> LabelledContent Source #

Creates an Input Data Table for use in the Functional Requirments section. Takes a list of wrapped variables and something that is Referable.

mkValsSourceTable :: (Quantity i, MayHaveUnit i) => [(i, Sentence)] -> String -> Sentence -> LabelledContent Source #

Creates a table for use in the Functional Requirments section. Takes a list of tuples containing variables and sources, a label, and a caption.

reqInputsRef :: Reference Source #

Reference for the Required Inputs table.

mkMaintainableNFR :: String -> Integer -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Maintainability. Takes in a Reference Address (Space), a percent value (Space), and a label (Space).

mkPortableNFR :: String -> [String] -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Portability.

mkCorrectNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Correctness.

mkVerifiableNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Verifiability.

mkUnderstandableNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Understandability.

mkReusableNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Reusability.

mkSecurityNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Security.

Specific System Description

auxSpecSent :: Sentence Source #

General Sentence that describes some auxiliary specifications of the system.

termDefnF' :: Maybe Sentence -> [Contents] -> Section Source #

Similar to termDefnF, except does not take definitions from the list of terms.

inDataConstTbl :: (HasUncertainty c, Quantity c, Constrained c, HasReasVal c, MayHaveUnit c) => [c] -> LabelledContent Source #

Creates the input Data Constraints Table.

outDataConstTbl :: (Quantity c, Constrained c) => [c] -> LabelledContent Source #

Creates the output Data Constraints Table.

Document Extraction Function

getDocDesc :: DocDesc -> [Sentence] Source #

Extracts Sentences from a document description.

egetDocDesc :: DocDesc -> [ModelExpr] Source #

Extracts expressions from the document description (DocDesc) and default DLPlate.

References

secRefs :: [Reference] Source #

All section references used in creating a Software Requirements Specification (SRS).