marko 0.3.0 → 0.4.0

data/lib/assets/demo/src/fr/storage.md

@@ -1,16 +0,0 @@
-# Sources Storage
-{{id: .storage, parent: fr}}
-
-The system shall provide a storage for artifact sources. The storage must provide the following features:
-
-- Create a new project
-- Remove project
-- Get the list of project sources
-- Get project source
-
-@@skip
-
-At this stage only option will be developed - the filesystem storage. Other options that should be considered for future stages are
-
-- Database storage (SQL and NoSQL)
-- Confluence Wiki

data/lib/assets/demo/src/fr/treenode.md

@@ -1,34 +0,0 @@
-# TreeNode
-{{id: .treenode, parent: fr}}
-
-The system shall provide `Node` entity with the following properties that provide the following attributes:
-
-Property  Type   *..n Default Description
---------- ------ ---- ------- -----------
-id        String 1    ""      Node identifier
-parent    Node   1    null    Parent node reference
-title     String 1    ""      Node title
-meta      Hash   1    {}      Node metadata
-body      String 1    ""      Node body
-items     Node   0..n []      Child node reference
-
-## Tree Metadata
-{{id: .tree}}
-
-To assemble the project artifact from nodes placed among several source files, the system shall provide the following optional tree metadata attributes:
-
-Attribute   Type   0..n Description
------------ ------ ---- --------------
-id          String 0..1 Unique node id
-parent      String 0..1 Parent id
-order_index String 0..1 Children ids delimited by space
-
-## Source Metadata
-{{id: .orig}}
-
-During source file parsing, the system must store the following node origin information:
-
-Attribute   Type   0..n Description
------------ ------ ---- --------------
-origin      String 1    Source filename
-lineno      String 1    Number of line

data/lib/assets/demo/src/index.md

@@ -1,34 +0,0 @@
-# Intro
-{{id: intro}}
-
-# Users
-{{id: usr}}
-
-The users of the system are different people who play for authoring various sorts of technical documentation. It might be a technical writer, business/systems analyst, developer, etc.
-
-# User Requirements
-{{id: ur, order_index: uc}}
-
-## Use Cases
-{{id: uc, order_index: .create.project .general.flow}}
-
-# Functional Requirements
-{{id: fr, order_index: .treenode .markup .storage .assemble .compile}}
-
-# Interface Requirements
-{{id: ui, order_index: .cli .gem}}
-
-# Assumptions and Dependencies
-{{id: as}}
-
-##
-
-The system requires a user interface for managing markup sources. It is assumed that users utilize any text editor of their choice.
-
-##
-
-The system requires tools for collaboration on artifacts by several authors simultaneously. Because of the plain text nature of the markup sources, It is assumed using Git for managing the artifact sources repository.
-
-##
-
-The system requires the compilation of artifacts into deliverables in form of well-supported formats like pdf, doc, etc. It is assumed using Pandoc for creating deliverables.

data/lib/assets/demo/src/intro.md

@@ -1,98 +0,0 @@
-# Purpose
-{{parent: intro}}
-
-The main purpose of this document is to provide a comprehensive demo project for Marko gem. The other technical purpose is to have Marko Sandbox for testing and development.
-
-# Problem
-{{parent: intro}}
-
-There are a few alternatives for authors who work on bulky software artifacts like requirements specification. They can apply one of the following tools
-
-@@todo find a few popular requirements management tools
-@@todo find a few popular Tex alternatives
-
-- a particular requirements management tool, like Doors
-- a Word Processor, like Microsoft Word, Libra Office, or Google Docs;
-- an elaborate publishing system, like Tex;
-- or just using a simple Wiki system, like Confluence or Redmine.
-
-A requirements management tool might seem to be the best choice there because it is tailored exactly for the required process. But it certainly will be a "hard way" from a cost and time perspective, an elaborate and expensive solution requiring personnel to be trained and vendor support.
-
-Although deliverable artifacts could be seen as a usual document structured and expressed in headers and paragraphs, the meaning of each of those can be different. So word processors and wiki systems might be the perfect choice for presenting artifact deliverables, but they lack of semantic fails for content development and management. The best of them provide a scripting language for document processing, but it is usually too complicated and again lacks particular entities' semantics (stakeholders, requirements, constraints, etc.)
-
-Designing documents of hundreds of pages in word processors brings some peculiar drawbacks. The software tends to become "bulky" in operating, consuming too many system resources and responding with delays; tend to be fragile with styles.
-
-__The problem of__ the lack of simple tools and approaches for writing software artifacts __affects__ technical writers who develop and manage the artifacts __the impact of which is__ they tend to choose a publishing tool or a word processor that does not fit well to work on software artifacts causing lots of manual work and maybe other confusing things like "bulky" documents __a successful solution would be__ the tool that will provide
-
-- a plain text markup for writing artifact items, that will be easy to read for humans, and processed by machines;  
-- a "semantics" layer to distinguish artifact items (actors, requirements, etc.) from supported text
-- the ability to automate tasks based on processing content according to its semantic value;
-- the ability to build a convenient presentation of the artifact (pdf, doc, odt);
-- will not depend on OS platform and any proprietary format or software.
-
-@@skip
-
-It provides a statement summarizing the problem being solved by the project.
-
-__The problem of__ [describe the problem]
-__affects__ [the stakeholders affected by the problem]
-__the impact of which is__ [what is the impact of the problem?]
-__a successful solution would be__ [list some key benefits of a successful solution]
-
-# Product
-{{parent: intro}}
-
-@@todo redesign the product statement for "who" section
-
-__For__ authors of software artifacts __who__ need a reliable and repeatable process of managing big software artifacts __the__ Marko Markup Compiler is a free open source software __that__ brings a "docs-as-code" approach with efficient plain markup for artifact sources, @@todo templates, CLI, Rake ..
-
-@@skip
-
-__For__ [target customer]
-__Who__ [statement of the need or opportunity]
-__The__ [product name] is a [product category]
-__That__ [key benefit, compelling reason to buy]
-__Unlike__ [primary competitive alternative]
-__Our product__ [statement of primary differentiation]
-
-# Scope
-{{parent: intro}}
-
-The developing system will consist of
-
-- the simple plain markup for writing the artifact sources;
-- the repository of artifact sources;
-- the algorithm for assembling the artifact from sources;
-- the markup for templates for publishing the artifact;
-- the command line interface for compiling the artifact into deliverables based on the templates  
-- the Ruby Gem that presents the artifact as the collection o items that can be easily visited for tasks automation;
-- the demo project that will help the customers to adopt the approach and design their own solutions based on the approach.
-
-# Definitions
-{{parent: intro}}
-
-CLI
-
-:   Command-line interface
-
-ERB
-
-:   Ruby Templating system
-
-# References
-{{parent: intro}}
-
-1. [Markdown Guide](https://www.markdownguide.org/)
-2. [Pandoc User's Guide](https://pandoc.org/MANUAL.html)
-3. [Git User's Manual](https://git-scm.com/docs/user-manual.html)
-
-# Overview
-{{parent: intro}}
-
-The remaining sections of this document provide user- and functional requirements of the system.
-
-The [[usr]] chapter introduces users of the system.
-
-The next chapter [[ur]] introduces users requirements that establish the context for the functional requirements.
-
-The following chapter [[fr]] describes detailed requirements for functions and user interfaces.

data/lib/assets/demo/src/ui/cli.md

@@ -1,26 +0,0 @@
-# Command-line interface
-{{id: .cli, parent: ui}}
-
-The system shall provide a command-line interface. The interface must provide the following commands:
-
-@@list
-
-## Create a new project
-
-The system shall provide the `new PROJECT` command. When the user requests the `new PROJECT` command, the system
-
-- ensures that `PROJECT` folder does not exist or fails
-- creates `PROJECT` folder and copies required files for new project
-- reports the user about success  
-
-## Compile artifact
-
-The system shall provide the `compile [-t TEMPALTE] [-o FILENAME]` command. When the user requests the `compile` command, the system
-
-- ensures that current directory is `Marko Project` directory, or fails
-- load `template`,
-  - load from the `TEMPLATE` parameter when provided
-  - or load default template when not
-- creates `tree` by using [[fr.assemble]]
-- compiles the tree by [[fr.compile]].(`tree`, `template`, `filename`)
-- reports the user about success

data/lib/assets/demo/src/ui/gem.md

@@ -1,14 +0,0 @@
-# Gem interface
-{{id: .gem, parent: ui}}
-
-The system shall provide Ruby Gem with the following functions
-
-@@list
-
-## Marko.assemble
-
-@@todo define Marko.assemble
-
-## Marko.compile
-
-@@todo define Marko.compile

data/lib/assets/demo/src/ur/uc.create.project.md

@@ -1,8 +0,0 @@
-# Create a new project
-{{id: uc.create.project, parent: uc}}
-
-__Main Flow__
-
-1. The user requests the system to create a new project passing a project folder for new project.
-2. The system checks for project folder to be unique. When  folder with the same name exists already, the system reports it to the user and the scenario is finished.
-3. The system creates the project folder and furnish it with project structure.

data/lib/assets/demo/src/ur/uc.general.flow.md

@@ -1,14 +0,0 @@
-# General Marko Flow
-{{id: uc.general.flow, parent: uc}}
-
-__Prerequisites__
-
-1. The user inside Marko project (see [[uc.create.project]])
-
-__Main Flow__
-
-1. The user creates and makes changes to the sources of the project. [outside the system]
-2. The user requests the system to `compile` the artifact.
-3. The system assembles the artifact from source files.
-4. The system checks the artifact and reports the errors to the user if any.
-5. The system returns the assembled artifact.

data/lib/assets/init/README.md

@@ -1,61 +0,0 @@
-% Marko Demo Project
-
-Welcome to your new [Marko](https://github.com/nvoynov/marko) project!
-
-# Structure
-
-This project has the following structure:
-
-- [bin/](bin/) - output folder
-- [bin/assets/](bin/assets/) - assets folder
-- [src/](src/) - markup sources
-- [tt/](tt/) - templates
-- [marko.yml](marko.yml) - project configuration
-- [Rakefile](Rakefile) - Rakefile
-- [README.md](README.md)
-
-# Interface
-
-Run `marko` command in your console to see basic command-line interface.
-
-Extend it yourself through Rakefile
-
-# Git Repository
-
-[Git How To](https://githowto.com/)
-
-Incorporates changes from a remote repository:
-
-    git pull
-
-Create a new branch to start any activity with the repository:
-
-    git branch <branch_name>
-
-Make changes and commit your work:
-
-    git add .
-    git commit -m "branch_name - commit description"
-
-When your changes finished, incorporate changes from the remote repository and merge the `master` branch to your `branch_name`:
-
-    git checkout master
-    git pull
-    git checkout <branch_name>
-    git merge master
-
-Resolve all conflicts and commit changes:
-
-    git add .
-    git commit -m "branch_name conflicts resolved"
-
-Merge your changes to the `master` branch:
-
-    git checkout master
-    git merge <branch_name>
-
-Push your changes to the remote repository:
-
-    git push
-
-Create a merge request if you are not allowed to push to the `master` branch.

data/lib/assets/init/Rakefile

@@ -1,100 +0,0 @@
-# frozen_string_literal: true
-
-require 'marko'
-require 'marko/markup'
-
-namespace :marko do
-
-  # @todo pandoc: bin/arfifact.docx: openBinaryFile: permission denied (Permission denied)
-  #   Success! Find the artifact in bin/arfifact.docx
-  #
-  desc 'Publish the artifact'
-  task :publish do
-    output = 'bin/arfifact'
-    `marko c -o #{output}.md`
-    pandoc = `pandoc #{output}.md -o #{output}.docx`
-    File.delete("#{output}.md")
-    puts "Success! Find the artifact in #{output}.docx"
-  end
-
-  desc 'Print table of contents'
-  task :toc, :query do |t, args|
-    args.with_defaults(query: '')
-    tree = Marko.assemble
-    query = args.query
-    unless query.empty?
-      tree = tree.find_node(query)
-      unless tree
-        puts "Nothing to be printed!"
-        abort
-      end
-      tree.orphan!
-    end
-    tree.each do |n|
-      if n.root?
-        puts "% #{n.title}" if n.root?
-        next
-      end
-      title = n.title.empty? ? n.id : n.title
-      puts '#' * n.nesting_level + " #{title} ##{n.id}"
-    end
-  end
-
-  desc 'Print @@todo'
-  task :todo do
-    tree = Marko.assemble
-    tree.to_a.drop(1)
-      .select{|n| n.body =~ /@@todo/}
-      .each{|n|
-        list = n.body
-          .scan(/@@todo.*$/)
-          .map{_1.sub(/@@todo/, '')}
-          .map{"  #{_1.strip}"}
-          .join(?\n)
-        puts n[:origin]
-        puts list
-        puts
-      }
-  end
-
-  def datestamp
-    Time.new.strftime('%Y%m%d')
-  end
-
-  def timestamp
-    Time.new.to_s
-  end
-
-  desc 'Punch meeting munutes'
-  task :mm, :extra do |t, args|
-    args.with_defaults(extra: '')
-    extra = args.extra
-    Dir.mkdir('mm') unless Dir.exist?('mm')
-    body = MINUTES % timestamp
-    name = "minutes-#{datestamp}#{extra.empty? ? '' : ?_ + extra}.md"
-    name = File.join('mm', name)
-    errm = "Minutes exists already. Maybe you can provide [EXTRA]?"
-    fail errm if File.exist?(name)
-    File.write(name, body)
-  end
-
-  MINUTES = <<~EOF.freeze
-    %% Meeting Minutes %s
-
-    # Attendants
-
-    1.
-    2.
-
-    # Questions
-
-    1.
-    2.
-
-    # Decisions
-
-    1.
-    2.
-  EOF
-
-end

data/lib/assets/init/tt/custom.md.tt

@@ -1,19 +0,0 @@
-%# Marko custom template
-%
-% if !defined?(custom?)
-%   def custom?(node)
-%     %w[u s f].any?{|t| node.id == t || node.belongs_to?(t)}
-%   end
-%
-%   def custom!(node)
-%     lnkfu = proc{|e| node.find_node(e)&.ref || "[#{e}](#404)" }
-%     subfu = proc{|s| s.split(?\s).map(&lnkfu).join(', ')}
-%     node[:depend] = subfu.(node[:depend]) if node[:depend]
-%     node[:satisfy] = subfu.(node[:satisfy]) if node[:satisfy]
-%   end
-% end
-%
-% @model.each do |node|
-%   custom!(node) if custom?(node)
-<%= node.text %>
-% end

data/lib/assets/init/tt/default.md.tt

@@ -1,4 +0,0 @@
-%# Marko default template
-% @model.each do |node|
-<%= node.text %>
-% end

data/lib/assets/samples/0_index.md

@@ -1,14 +0,0 @@
-# Marko. Software Requirements Specification
-{{id: root, order_index: intro stakh actors fr nf fa as}}
-
-## Functional requirements
-{{id: fr, order_index: .uc .en}}
-
-## Interface Requirements
-{{id: fa}}
-
-## Non-functional requirements
-{{id: nf}}
-
-## Assumptions and Dependencies
-{{id: as}}

data/lib/assets/samples/1_intro.md

@@ -1,55 +0,0 @@
-# Introduction
-{{id: intro, parent: root}}
-
-## Purpose
-
-The purpose of this document is to provide software requirements specification for @@todo
-
-## Problem
-
-@@skip provide concise statements summarizing the problems that the project should solve
-
-__The problem of__ [describe the problem]
-__affects__ [the stakeholders affected by the problem]
-__the impact of which is__ [what is the impact of the problem?]
-__a successful solution would be__ [list some key benefits of a successful solution]
-
-## Product
-
-@@skip product statement
-
-__For__ [target customer]
-__Who__ [statement of the need or opportunity]
-__The__ [product name] is a [product category]
-__That__ [key benefit, compelling reason to buy]
-__Unlike__ [primary competitive alternative]
-__Our product__ [statement of primary differentiation]
-
-## Scope
-
-@@todo define the scope of the project, web-site, micorservice, etc.
-
-## Definitions
-
-@@skip place some core definitions here
-
-CLI
-
-:   Command-line interface
-
-## References
-
-@@skip provide some references
-
-- [Marko](https://github.com/nvoynov/marko)
-- [Punch](https://github.com/nvoynov/punch)
-
-## Overview
-
-The next two chapters describe stakeholders ([[stakeholders]]) and users ([[actors]]) of the system.
-
-The following section [[fr]] provides functional requirements, that starts from use cases ([[fr.uc]]), proceeds with other functional requirements and finishes with data requirements ([[fr.en]]).
-
-[[fa]] section defines required user interface.
-
-[[concern]] section provides the domain concerns.

data/lib/assets/samples/2_stakh.md

@@ -1,21 +0,0 @@
-# Stakeholders
-{{id: stakeholders, parent: root}}
-
-@@skip 
-
-- Regulator
-- Purchaser
-- Sponsor
-- Politician
-- The Public
-
-`ISO 42010`. The following stakeholders shall be considered and when applicable, identified in the architecture description:
-
-- users of the system;
-- operators of the system;
-- acquirers of the system;
-- owners of the system;
-- suppliers of the system;
-- developers of the system;
-- builders of the system;
-- maintainers of the system.

data/lib/assets/samples/3_actors.md

@@ -1,10 +0,0 @@
-# Actors
-{{id: actors, parent: root}}
-
-@@list
-
-## User
-{{id: .user}}
-
-## Admin
-{{id: .admin}}

data/lib/assets/samples/4_cases.md

@@ -1,53 +0,0 @@
-# Use Cases
-{{id: uc, parent: root}}
-
-@@tree
-
-@@skip # Some Use Case
-{{id: .some, parent: uc}}
-
-**Actors and their Goals**
-
-1. User, wants to get some value
-2. System, wants to ensure some policies
-
-**Guarantee**
-
-[Succeed]{.underline}
-
-- one
-- two
-
-[Failed]{.underline}
-
-- one
-- two
-
-**Extend**
-
-- no use case extensions
-@@todo - [\[fr.uc]]
-
-**Include**
-
-- no use case inlcusions
-@@todo - [\[fr.uc]]
-
-**Main flow**
-
-1.
-2.
-
-**Extension**
-
-[1a] something faulty
-
-1. one
-2. two
-
-**Data**
-
-[Entities:]{.underline}
-
-@@todo - [\[fr.ent.]];
-@@todo - [\[fr.ent.]].

data/lib/assets/samples/5_entities.md

@@ -1,18 +0,0 @@
-# Entities
-{{id: .en, parent: fr}}
-
-The system utilizes the following entities:
-
-@@list
-
-@@skip ## Entity "Sample"
-{{id: .sample, parent: fr.en}}
-
-The entity should provide the following properties:
-
-Property | Type | Multiplicity | Description
--------- | ---- | ------------ | -----------
-id       | UUID | 1            | unique identifier
-title    | text | 1            | title
-
-Table: Entity "Sample"

data/lib/assets/samples/6_concerns.md

@@ -1,60 +0,0 @@
-# Domain concern
-{{id: concern, parent: root}}
-
-- Mergers and acquisitions
-- Time to market
-- User satisfaction
-- Competitive advantage
-- Time and budget
-
-## Architecture Characteristics
-
-Also known as "quality characteristics" or "non-functional requirements"
-
-Domain Concern           Architecture characteristics
------------------------- -----------------------------
-Mergers and acquisitions Interoperability, scalability, adaptability, extensibility
-Time to market           Agility, testability, deployability
-User satisfaction        Performance, availability, fault tolerance, testability, deployability, agility, security
-Competitive advantage    Agility, testability, deployability, scalability, availability, fault tolerance
-Time and budget          Simplicity, feasibility
-
-### Operational
-
-Term               Definition
------------------- ---------------------------
-Availability       How long the system will need to be available (if 24/7, steps need to be in place to allow the system to be up and running quickly in case of any failure).
-Continuity         Disaster recovery capability.
-Performance        Includes stress testing, peak analysis, analysis of the frequency of functions used, capacity required, and response times. Performance acceptance sometimes requires an exercise of its own, taking months to complete.
-Recoverability     Business continuity requirements (e.g., in case of a disaster, how quickly is the system required to be online again?). This will affect the backup strategy and requirements for duplicated hardware.
-Reliability/safety Assess if the system needs to be fail-safe, or if it is mission critical in a way that affects lives. If it fails, will it cost the company large sums of money?
-Robustness         Ability to handle error and boundary conditions while running if the internet connection goes down or if there’s a power outage or hardware failure.
-Scalability        Ability for the system to perform and operate as the number of users or requests increases
-
-### Structural
-
-Term                  Definition
---------------------- ----------
-Configurability       Ability for the end users to easily change aspects of the software’s configuration (through usable interfaces).
-Extensibility         How important it is to plug new pieces of functionality in.
-Installability        Ease of system installation on all necessary platforms.
-Leverageability/reuse Ability to leverage common components across multiple products.
-Localization          Support for multiple languages on entry/query screens in data fields; on reports, multibyte character requirements and units of measure or currencies.
-Maintainability       How easy it is to apply changes and enhance the system?
-Portability           Does the system need to run on more than one platform? (For example, does the frontend need to run against Oracle as well as SAP DB?
-Supportability        What level of technical support is needed by the application? What level of logging and other facilities are required to debug errors in the system?
-Upgradeability        Ability to easily/quickly upgrade from a previous version of this application/solution to a newer version on servers and clients
-
-### Cross-cutting
-
-Term           Definition
--------------- ------------------------------
-Accessibility  Access to all your users, including those with disabilities like colorblindness or hearing loss.
-Archivability  Will the data need to be archived or deleted after a period of time? (For example, customer accounts are to be deleted after three months or marked as obsolete and archived to a secondary database for future access.)
-Authentication Security requirements to ensure users are who they say they are.
-Authorization  Security requirements to ensure users can access only certain functions within the application (by use case, subsystem, webpage, business rule, field level, etc.).
-Legal          What legislative constraints is the system operating in (data protection, Sarbanes Oxley, GDPR, etc.)? What reservation rights does the company require? Any regulations regarding the way the application is to be built or deployed?
-Privacy        Ability to hide transactions from internal company employees (encrypted transactions so even DBAs and network architects cannot see them).
-Security       Does the data need to be encrypted in the database? Encrypted for network communication between internal systems? What type of authentication needs to be in place for remote user access?
-Supportability What level of technical support is needed by the application? What level of logging and other facilities are required to debug errors in the system?
-Usability      Level of training required for users to achieve their goals with the application/solution.