RubyGems - marko - Versions diffs - 0.1.0 → 0.3.0 - Mend

marko 0.1.0 → 0.3.0

Files changed (53) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +47 -0
data/Gemfile.lock +3 -2
data/README.md +16 -13
data/Rakefile +5 -0
data/STORY.md +44 -0
data/_layouts/footer.md +4 -0
data/_layouts/header.md +3 -0
data/_layouts/layout.html +73 -0
data/_layouts/robots.txt.erb +4 -0
data/_layouts/sitemap.xml.erb +20 -0
data/_layouts/styles.css +92 -0
data/docs/changelog.html +74 -0
data/docs/css/styles.css +92 -0
data/docs/index.html +297 -0
data/docs/readme.html +297 -0
data/docs/robots.txt +4 -0
data/docs/sitemap.xml +30 -0
data/docs/story.html +132 -0
data/exe/marko +4 -2
data/lib/assets/demo/README.md +2 -2
data/lib/assets/demo/src/ur/uc.general.flow.md +1 -1
data/lib/assets/init/README.md +1 -1
data/lib/assets/init/Rakefile +2 -2
data/lib/assets/init/tt/custom.md.tt +19 -0
data/lib/assets/init/tt/default.md.tt +4 -0
data/lib/assets/samples/0_index.md +14 -0
data/lib/assets/samples/1_intro.md +55 -0
data/lib/assets/samples/2_stakh.md +21 -0
data/lib/assets/samples/3_actors.md +10 -0
data/lib/assets/samples/4_cases.md +53 -0
data/lib/assets/samples/5_entities.md +18 -0
data/lib/assets/samples/6_concerns.md +60 -0
data/lib/assets/samples/SRS-IEEE-830-1998.md +293 -0
data/lib/assets/samples/SRS-RUP.md +283 -0
data/lib/assets/samples/business-case.md +116 -0
data/lib/assets/samples/ears.md +112 -0
data/lib/assets/samples/gen_punch_domain.rb +183 -0
data/lib/assets/samples/requirements.md +105 -0
data/lib/assets/samples/stakeholders.png +0 -0
data/lib/assets/samples/vision.md +191 -0
data/lib/marko/artifact.rb +3 -1
data/lib/marko/assembler.rb +1 -0
data/lib/marko/cli.rb +10 -2
data/lib/marko/markup/compiler.rb +3 -9
data/lib/marko/markup/decorator.rb +45 -30
data/lib/marko/markup/storage.rb +37 -19
data/lib/marko/tree_node.rb +3 -2
data/lib/marko/version.rb +1 -1
data/lib/marko.rb +8 -0
data/sancho.yml +6 -0
metadata +35 -4
data/lib/assets/init/tt/artifact.md.tt +0 -3

data/docs/sitemap.xml ADDED Viewed

@@ -0,0 +1,30 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<urlset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"
+    xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>nvoynov.github.io/marko/</loc>
+    <lastmod>2023-02-11</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>1.0</priority>
+  </url>
+  <url>
+    <loc>nvoynov.github.io/marko/readme.html</loc>
+    <lastmod>2023-02-11</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>
+  <url>
+    <loc>nvoynov.github.io/marko/changelog.html</loc>
+    <lastmod>2023-02-11</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>
+  <url>
+    <loc>nvoynov.github.io/marko/story.html</loc>
+    <lastmod>2023-01-30</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>
+</urlset>

data/docs/story.html ADDED Viewed

@@ -0,0 +1,132 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <meta name="dcterms.date" content="2023-01-26" />
+  <title>Marko Story</title>
+  <style>
+    code{white-space: pre-wrap;}
+    span.smallcaps{font-variant: small-caps;}
+    div.columns{display: flex; gap: min(4vw, 1.5em);}
+    div.column{flex: auto; overflow-x: auto;}
+    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+    ul.task-list{list-style: none;}
+    ul.task-list li input[type="checkbox"] {
+      width: 0.8em;
+      margin: 0 0.8em 0.2em -1.6em;
+      vertical-align: middle;
+    }
+    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
+  </style>
+  <link rel="stylesheet" href="css/styles.css" />
+  <!--[if lt IE 9]>
+    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+  <![endif]-->
+</head>
+<body>
+<p class="navbar">
+<span class="smallcaps">= <strong>“Marko” Markup Compiler</strong> = <a
+href="readme.html">Readme</a> ~ <a href="changelog.html">Changelog</a> ~
+<a href="story.html">Story</a> ~ <a
+href="https://github.com/nvoynov/sancho">Github</a></span>
+</p>
+<header id="title-block-header">
+<h1 class="title">Marko Story</h1>
+<p class="date">2023-01-26</p>
+</header>
+<nav id="TOC" role="doc-toc">
+<ul>
+<li><a href="#childhood-2012" id="toc-childhood-2012">Childhood,
+2012</a></li>
+<li><a href="#adolescence-2014---2015"
+id="toc-adolescence-2014---2015">Adolescence, 2014 - 2015</a></li>
+<li><a href="#youth-since-2015" id="toc-youth-since-2015">Youth, since
+2015</a></li>
+<li><a href="#marko-2022" id="toc-marko-2022">Marko, 2022</a></li>
+</ul>
+</nav>
+<p><a href="https://github.com/nvoynov/marko">Marko</a> is the result of
+my ten-year journey with Ruby playing the Business Analyst role.</p>
+<h2 id="childhood-2012">Childhood, 2012</h2>
+<p>Somewhere in between 2011 and 2014 I was playing Software Engineer
+role in some BigKnownCo where my first and foremost working tool was
+Microsoft Word 2007. Requirements specifications and Architecture design
+documents Artifacts that I was mainly working on often consisted of one
+and more hundreds of pages and it was such a pain to deal with in MS
+Word which was the corporate standard.</p>
+<p>In simple words it just gone crazy on large documents, the program
+consumed all my RAM, document navigation was slow, the program simply
+stopped responding, which entailed restarting the process with a loss of
+changes; or even worse, the loss of style formatting that is invisible
+to the eye when you simply cannot see it that the formatting was lost
+somewhere on the 225th page.</p>
+<blockquote>
+<p>So problem was clear “<strong>The problem of</strong> the lack of
+simple reliable tools and approaches for writing software artifacts
+<strong>affects</strong> technical writers who develop and manage the
+artifacts <strong>the impact of which is</strong> they tend to
+choose..”</p>
+</blockquote>
+<p>And I come up with the idea to create something light, simple and
+reliable to eliminate the MS Word from my work experience once and for
+all. This time I was curious about using YAML for storing requirements
+just inside file system. And I regularly done some estimations and
+prioritization for requirements, so I decided that FPA, PERT, and
+Risk-Value prioritization will be valuable features here.</p>
+<p>It was my first serious diving into Ruby for few weeks. I succeeded
+in reading / writing YAML and even provided estimations algorithms. I
+fall in love with Ruby. But from user perspective (I was the user) it
+was complete failure. Writing YAML manually was just unforgivable but
+that time I was obsessed with the format.</p>
+<blockquote>
+<p>YAML was chosen just because this days I dramatically reduced time
+for load configuration of my target service provisioning system, that
+stored its configuration tree in RDBMS that causes ~5 000 000 selects
+for reading and about the same number insert/update for writing. It just
+reduced to 20 000 instead of 5 000 000.</p>
+</blockquote>
+<h2 id="adolescence-2014---2015">Adolescence, 2014 - 2015</h2>
+<p>It took two years to return to the subject, I left that job in 2014
+and got haft year off. This time I discovered Markdown and static site
+generators, and I decided on Markdown as my primary markup format, where
+each source is just a plain markdown file with some metadata
+excerpt.</p>
+<p>Things were going well and in a few months, I got something quite
+usable. Estimations algorithms were thrown out; markup sources were
+assembled in one artifact that was translated into HTML by Kramdown. I
+named it “Creq” for “console requirements” and since then I assembled
+all software artifacts in my own tool.</p>
+<h2 id="youth-since-2015">Youth, since 2015</h2>
+<p>Using my tool daily on a regular basis I discovered Pandoc and then
+can translate my artifact into any supported format; provided more
+advanced artifact templates, and provided a few templates for different
+purposes (draft, customer deliverable, etc.), added macros for tree node
+body.</p>
+<p>This time I named my tool Clerq because it just was my regular tool -
+I started my day from <code>$ git checkout -b new_feature</code> and
+finished with merging the branch, assembling new requirements increment,
+and pushing into git for my development team.</p>
+<p>In 2018 I have read The Clean Architecture I took my first clumsy
+attempts to apply it for Clerq.</p>
+<h2 id="marko-2022">Marko, 2022</h2>
+<p>The last time I used Clerq for two months in July 2022. I noticed
+that time that I use only “create a new project” and “build the
+artifact” commands. And I realized that there is nothing about
+requirements - just about artifact assembling.</p>
+<p>So I took two weeks and finished 2022 with a git commit on Dec 31,
+2022 :)</p>
+<p>The Marko purpose is assembling markup artifact from separated markup
+sources. Its interfaces are simple and clear. It could be naturally
+extended through Rakefile for any specific purpose related to visiting
+artifacts tree nodes.</p>
+<p>This is the first time I feel for a product that there are nothing I
+want to take or change. Just “Right Product, Done Right, Managed
+Messy”</p>
+<div id="footer">
+<hr />
+<p>© 2022-2023 <a href="http://nvoynov.github.io/">nvoynov</a></p>
+</div>
+</body>
+</html>

data/exe/marko CHANGED Viewed

@@ -11,10 +11,12 @@ when nil
 when /(n|new)/
   dir = ARGV.shift
   CLI.punch(dir)
-when /(d|demo)/
-  CLI.punch_demo
 when /(c|compile)/
   CLI.compile
+when /(d|demo)/
+  CLI.punch_demo
+when /(samples)/
+  CLI.punch_samples
 else
   CLI.banner
 end

data/lib/assets/demo/README.md CHANGED Viewed

@@ -2,12 +2,12 @@
 # Overview
-This project is an example of developing bulky technical artifacts with Marko Markup Compiler. It also serves as a sandbox for testing and features development.
+This project is an example of developing a technical artifacts with Marko. The artifact is Marko Requirements Specification that also servers as Marko Sandbox for testing and features development.
 # Usage
 Run `$ marko` to see command-line interface
-Run `$ rake marko:publish` to publish the aritfact
+Run `$ rake marko:publish` to publish the artifact
 Run `$ rake -T` to see other custom interface

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

@@ -1,4 +1,4 @@
-# General Clerq flow
+# General Marko Flow
 {{id: uc.general.flow, parent: uc}}
 __Prerequisites__

data/lib/assets/init/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 % Marko Demo Project
-Welcome to your new [Marko](https://github.com/nvoynov/clerq) project!
+Welcome to your new [Marko](https://github.com/nvoynov/marko) project!
 # Structure

data/lib/assets/init/Rakefile CHANGED Viewed

@@ -26,7 +26,7 @@ namespace :marko do
       tree = tree.find_node(query)
       unless tree
         puts "Nothing to be printed!"
-        return
+        abort
       end
       tree.orphan!
     end
@@ -71,7 +71,7 @@ namespace :marko do
     extra = args.extra
     Dir.mkdir('mm') unless Dir.exist?('mm')
     body = MINUTES % timestamp
-    name = "minutes-#{datestamp}#{extra.empty? ? '' : ?_ + extra}"
+    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)

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

@@ -0,0 +1,19 @@
+%# 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 ADDED Viewed

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

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

@@ -0,0 +1,14 @@
+# 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 ADDED Viewed

@@ -0,0 +1,55 @@
+# 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 ADDED Viewed

@@ -0,0 +1,21 @@
+# 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 ADDED Viewed

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

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

@@ -0,0 +1,53 @@
+# 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 ADDED Viewed

@@ -0,0 +1,18 @@
+# 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 ADDED Viewed

@@ -0,0 +1,60 @@
+# 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.