marko 0.1.0 → 0.3.0

data/lib/assets/samples/vision.md

@@ -0,0 +1,191 @@
+% Vision Document Template
+Company Name
+Vision Document for [Program Name]
+(r) 20XX [Company Name]
+
+# Revision History
+
+Date | Revision | Description | Author
+:--- | :------- | :---------- | :-----
+mm/dd/yy | 1.0 | Initial version | Author name
+
+# Table of Contents
+
+# 1 Introduction
+
+This section provides an overview of the Vision document.
+
+## 1.1 Purpose
+
+This document defines the strategic intent of the program. It defines high-level user needs, any applicable user personas, key stakeholders, and the general system capabilities needed by the users.
+
+## 1.2 Solution Overview
+
+State the general purpose of the product, system, application or service, and any version identification.
+
+* Identify the product or application to be created or enhanced.
+* Describe the application of the product, including its benefits, goals, and objectives.
+* Provide a general description of what the solution will and, where appropriate, will not do.
+
+## 1.3 References
+
+List other documents referenced, and specify the sources from which the references can be obtained. If a business case (Chapter 23) was developed to drive the program, refer to it or attach it.
+
+# 2 User Description
+To provide products and services that meet users’ needs, it is helpful to understand the challenges they confront when performing their jobs. This section should profile the intended users of the application and the key problems that limit the user’s productivity. This section should not be used to state specific requirements; just provide the background for why the features specified in Section 5 are needed.
+
+## 2.1 User/Market Demographics
+
+Summarize the key market demographics that motivate your solution decisions. Describe target-market segments. Estimate the market’s size and growth by the number of potential users or the amount of money your customers spend, trying to meet needs that your product/enhancement would fulfill. Review major industry trends and technologies. Refer to a market analysis, where available.
+
+## 2.2 User Personas
+
+Describe the primary and secondary user personas (see Chapter 7). A thorough analysis might cover the following topics for each persona:
+
+* Technical background and degree of sophistication  
+* Key responsibilities
+* Deliverables the user produces and for whom
+* Trends that make the user’s job easier or more difficult  
+* The user’s definition of success and how the user is rewarded
+* Problems that interfere with success
+
+## 2.3  User Environment
+
+Describe the working environment of the target user. Here are some suggestions.
+
+* How many people are involved in completing the task? Is this changing?
+* How long is a task cycle? How much time is spent in each activity? Is this changing?
+* Are there any unique environmental constraints: controlled environment, mobile, outdoors, and so on?
+* Which system platforms are in use today? Future platforms?
+* What other applications are in use? Does your application need to integrate with them?
+
+## 2.4 Key User Needs
+
+List the key problems or needs as perceived by the user. Clarify the following issues for each problem.
+
+* What are the reasons for this problem?
+* How is it solved now?
+* What solutions does the user envision?
+
+Ranking and cumulative-voting techniques for these needs indicate problems that must be solved versus issues the user would like to be solved.
+
+## 2.5 Alternatives and Competition
+
+Identify any alternatives available to the user. These can include buying a competitor’s product, building a homegrown solution, or simply maintaining the status quo. List any known competitive choices that exist. Include the major strengths and weaknesses of each competitor as perceived by the end user.
+
+### 2.5.1 Competitor 1
+
+### 2.5.2 Competitor 2
+
+# 3 Stakeholders
+
+Identify the program stakeholders, their needs, and their degree of involvement with the system. A table such as the following can be effective:
+
+Project<br/>Stakeholder | Degree of<br/> Involvement | Product Needs | Program Needs
+:---- | :---- | :---- | :----
+Stakeholder 1 | | |
+Stakeholder 2 | | |
+
+# 4 Product Overview
+
+This section provides a high-level view of the solution capabilities, interfaces to other applications, and systems configurations. This section usually consists of five subsections, as follows.
+
+## 4.1 Product Perspective
+
+This subsection should put the product in perspective to other related products and the user’s environment. If the product is independent and totally self-contained, state so. If the product is a component of a larger system, this subsection should relate how these systems interact and should identify the relevant interfaces among the systems. One easy way to display the major components of the larger system, interconnections, and external interfaces is via a system context block diagram.
+
+## 4.2 Product Position Statement
+
+Provide an overall statement summarizing, at the highest level, the unique position the product intends to fill in the marketplace. Moore [1991] calls this the product position statement and recommends the following format.
+
+For | (target customer)
+:-- | :----------------
+Who | (statement of the need or opportunity)
+The (product name) | is a (product category)
+That | (statement of key benefit, that is, compelling rea
+son to buy)
+Unlike | (primary competitive alternative)
+Our product | (statement of primary differentiation)
+
+A product position statement communicates the intent of the application and the importance of the program to all stakeholders.
+
+## 4.3 Summary of Capabilities
+
+Summarize the major benefits and features the product will provide. Organize the features so that the list is understandable to any stakeholder. A simple table listing the key benefits and their supporting features, as shown below, might suffice.
+
+Solution Features | Customer Benefit
+:---------------- | :---------------
+Feature 1         | Benefit 1
+Feature 2         | Benefit 2
+
+## 4.4 Assumptions and Dependencies
+
+List any assumptions that, if changed, will alter the vision for the product.
+
+## 4.5 Cost and Pricing
+
+Describe any relevant cost and pricing constraints, because these can directly impact the solution definition and implementation.
+
+# 5 Product Features
+
+This section describes the intended product features. Features provide the system capabilities that are necessary to deliver benefits to the users. Feature descriptions should be short and pithy, a key phrase, perhaps followed by one or two sentences of explanation.
+
+Use a level of abstraction high enough to be able to describe the system with a maximum of 25 to 50 features. Each feature should be perceivable by users, operators, or other external systems.
+
+## 5.1 Feature 1
+
+## 5.2 Feature 2
+
+# 6 Exemplary Use Cases
+
+[Optional] You may want to describe a few exemplary use cases, perhaps those that are architecturally significant or those that will most readily help the reader understand how  the system is intended to be used.
+
+# 7 Nonfunctional Requirements
+
+This section records other system requirements including nonfunctional requirements (constraints) imposed on the system (see Chapter 17).
+
+## 7.1 Usability
+
+## 7.2 Reliability
+
+## 7.3 Performance
+
+## 7.4 Supportability
+
+## 7.5 Other Requirements
+
+### 7.5.1 Applicable Standards
+
+List all standards the product must comply with, such as legal and regulatory, communications standards, platform compliance standards, and quality and safety standards.
+
+### 7.5.2 System Requirements
+
+Define any system requirements necessary to support the application. These may include the  host  operating systems  and  network  platforms,  configurations, communication, peripherals, and companion software.
+
+### 7.5.3 Licensing, Security, and Installation
+
+Licensing, security, and installation issues can also directly  impact the development effort. Installation requirements may affect coding or create the need for separate installation software.
+
+# 8 Documentation Requirements
+
+This section describes the documentation that must be developed to support successful deployment and use.
+
+## 8.1 User Manual
+
+Describe the intent of the user manual. Discuss desired length, level of detail, need for index and glossary, tutorial versus reference manual strategy, and so on. Formatting, electronic distribution, and printing constraints should also be identified.
+
+## 8.2 Online Help
+
+The nature of these systems is unique to application development since they combine aspects of programming and hosting, such as hyperlinks and web services, with aspects of technical writing, such as organization, style, and presentation.
+
+## 8.3 Installation Guides, Configuration, “Read Me” File
+
+A document that includes installation instructions and configuration guidelines is typically necessary. Also, a “read  me” file is often included as a standard component. The “read me” file may include a “What’s New with This Release” section and a discussion of compatibility issues with earlier releases. Most users also appreciate publication of any known defects and workarounds.
+
+## 8.4 Labeling and Packaging
+
+Defines the requirements for labeling to be incorporated into the code. Examples include copyright  and  patent notices,  corporate  logos,  standardized  icons,  and  other  graphic elements.
+
+## 9 Glossary
+
+The glossary defines terms that are unique to the program. Include any acronyms or abbreviations that need to be understood by users or other readers.

data/lib/marko/artifact.rb

@@ -1,3 +1,5 @@
 module Marko
-  Artifact = Struct.new(:id, :title, :template, :filename)
+  Artifact = Struct.new(:title, :template, :filename)
+  NULLFACT = Artifact.new("Artifact",
+    "tt/default.md.tt", "bin/artifact.md") .freeze 
 end

data/lib/marko/assembler.rb

@@ -29,6 +29,7 @@ module Marko
       buffer, errors = Loader.(&@block)
       fail Failure.new('markup parsing errors', *errors) if errors.any?
       @block.(:stage, 'tree assemblage') if @block
+      # @todo fold first level when root note contain only one item?
       tree = assemble(buffer)
       @block.(:stage, 'tree enrichment') if @block
       injectid(tree)

data/lib/marko/cli.rb

@@ -25,12 +25,20 @@ module Marko
     def punch_demo(args = ARGV)
       # pp options(:demo, args)
       log = storage.punch_demo
-      puts "Marko Demo cloned!\n#{log}"
+      puts "Marko Demo copied!"
+      puts log.map{"  #{_1}"}.join(?\n)
+
       kwargs = options(:demo, args)
       editor = kwargs.fetch(:editor, '')
       Dir.chdir(log) { `#{editor} .` } unless editor.empty?
     end
 
+    def punch_samples(args = ARGV)
+      log = storage.punch_samples
+      puts "Marko Samples copied!"
+      puts log.map{"  #{_1}"}.join(?\n)
+    end
+
     def compile(args = ARGV)
       unless storage.marko_home?
         puts "Marko directory required!"
@@ -89,7 +97,7 @@ module Marko
     #          ||----w |
     #          ||     ||
     BANNER = <<~EOF.freeze
-      ~ Marko v0.1.3 ~ Markup Compiler
+      ~ Marko v#{Marko::VERSION} ~ Markup Compiler
       ~ https://github.io/nvoynov/marko
     EOF
 

data/lib/marko/markup/compiler.rb

@@ -19,15 +19,9 @@ module Marko
 
       def compile
         storage = StoragePlug.plugged
-        erbgen = ERB.new(@template, trim_mode: '-')
-        payload = @tree.map{|n| Decorator.new(n)}
-        storage.write(@filename){|f|
-          payload.each{|node|
-            @node = node
-            text = erbgen.result(binding)
-            f.puts text
-          }
-        }
+        @model = @tree.map{|n| Markup::Decorator.new(n)}
+        samplr = ERB.new(@template, trim_mode: '%<>')
+        storage.write(@filename, samplr.result(binding))
         @filename
       end
     end

data/lib/marko/markup/decorator.rb

@@ -12,53 +12,68 @@ module Marko
         @macroproc = MacroProcPlug.plugged
       end
 
+      def title
+        super.then{|s| s.empty? ? ".#{id.split(/\./).last}" : s}
+      end
+
+      def body
+        @macroproc.process(super, self).strip
+      end
+
+      # @return [Hash] metdata cleaned from system meta
+      def meta
+        super.dup.tap{|h| h.update(id: id)}
+          .reject{|k,_| %i[origin parent order_index].include?(k)}
+      end
+
       def find_node(ref)
         obj = super(ref)
         return nil unless obj
         self.class.new(obj)
       end
 
-      def url
-        id.downcase
-          .gsub(/\W{1,}/, '-')
-          .gsub(/^-/, '')
-          .gsub(/-$/, '')
-          .then{"##{_1}"}
-      end
-
       def ref
         "[#{title}](#{url})"
       end
 
-      def title
-        str = super
-        str = ".#{id.split(/\./).last}" if str.empty?
-        str
+      # @return [String] return header
+      def topic
+        return "% #{title}" if root?
+        "#{'#' * nesting_level} #{title.strip} {#{url}}"
       end
+      alias :header :topic
 
-      def header
-        return "% #{title}\n" if root?
-        "#{'#' * nesting_level} #{title.strip} {#{url}}\n"
+      # return [String] meta properties table
+      def props
+        meta.then{|h|
+          klen = h.keys.map{ _1.to_s.size }.max + 4
+          vlen = h.values.map(&:size).max
+          mark = ?- * klen + ?\s + ?- * vlen
+          h.map{|k, v| "__#{k.capitalize}__".ljust(klen) + ?\ + v }
+            .unshift(mark)
+            .push(mark)
+            .join(?\n)
+        }
       end
 
-      def meta
-        hsh = super.dup
-        hsh[:id] = id # full id will be there
-        hsh.delete(:order_index)
-        hsh.delete(:parent)
-        hsh.delete(:origin)
-        len = hsh.keys.map(&:length).max
-        [].tap{|ary|
-          ary << "key | value"
-          ary << "--- | -----"
-          hsh.each{|k,v| ary << "#{k} | #{v}"}
-        }.join(?\n) + ?\n
+      # @return [String] decorated node content
+      def text
+        [ topic, props, body
+        ].reject(&:empty?)
+         .join("\n\n") +
+         "\n\n"
       end
 
-      def body
-        text = @macroproc.process(super, self)
-        text.strip + ?\n
+      protected
+
+      def url
+        id.downcase
+          .gsub(/\W{1,}/, '-')
+          .gsub(/^-/, '')
+          .gsub(/-$/, '')
+          .then{"##{_1}"}
       end
+
     end
 
   end

data/lib/marko/markup/storage.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 require "psych"
 require 'fileutils'
-require "securerandom"
 require_relative "../storage"
 
 module Marko
@@ -17,22 +16,35 @@ module Marko
       def punch(storage)
         fail Failure, "Directory already exists" if Dir.exist?(storage)
         Dir.mkdir(storage)
-        Dir.chdir(storage) {
+        furnish(storage)
+      end
+
+      def furnish(directory)
+        Dir.chdir(directory) {
           marko_directories.each{|dir| Dir.mkdir dir }
           src = File.join(Marko.root, 'lib', 'assets', 'init', '.')
           cp_r src, Dir.pwd
+          artifact
         }
       end
 
       # create demo project
       def punch_demo
-        demo = File.join(Dir.home, DEMO)
-        unless Dir.exist?(demo)
-          punch(demo)
-          assets = File.join(Marko.root, 'lib', 'assets', 'demo', '.')
-          cp_r assets, demo
-        end
-        demo
+        return if Dir.exist?(DEMO)
+        mkdir_p DEMO
+        furnish DEMO
+        demo = File.join(Marko.demo, '.')
+        cp_r demo, DEMO
+        Dir.glob("#{DEMO}/**/*", File::FNM_DOTMATCH).tap(&:shift)
+      end
+
+      # create samples dir
+      def punch_samples
+        return if Dir.exist?(SAMPLES)
+        mkdir_p SAMPLES
+        samples = File.join(Marko.samples, '.')
+        cp_r samples, SAMPLES
+        Dir.glob("#{SAMPLES}/**/*", File::FNM_DOTMATCH).tap(&:shift)
       end
 
       # @see Storage#sources
@@ -62,14 +74,20 @@ module Marko
 
       # @see Marko::Strorage#artifact
       def artifact
-        return Psych.load_file(ARTIFACT).freeze if File.exist?(ARTIFACT)
-        art = Artifact.new(SecureRandom.uuid,
-          'Marko Artifact',
-          'tt/artifact.md.tt',
-          'tt/marko-artifact.md'
-        )
-        File.write(ARTIFACT, Psych.dump(art))
-        art.freeze
+        artf = NULLFACT
+        head, body = Psych.dump(artf).lines.then{|ln|
+          [ln.first, ln.drop(1).join]
+        }
+
+        unless File.exist?(ARTIFACT)
+          File.write(ARTIFACT, body)
+          return artf
+        end
+
+        body = File.read(ARTIFACT)
+        obj = Psych.load(head + body, freeze: true,
+          permitted_classes: [Symbol, Marko::Artifact])
+        obj.is_a?(Artifact) ? obj : artf
       end
 
       protected
@@ -79,13 +97,13 @@ module Marko
       BINARY = 'bin'.freeze
       SAMPLE = 'tt'.freeze
       ASSETS = File.join(BINARY, 'assets').freeze
-      DEMO = 'marko_demo'.freeze
+      DEMO = File.join('.marko', 'demo').freeze
+      SAMPLES = File.join('.marko', 'samples').freeze
 
       def marko_directories
         [SOURCE, BINARY, ASSETS, SAMPLE]
       end
 
-
       def marko_home!
         fail Failure, "Marko project required!" unless marko_home?
       end

data/lib/marko/tree_node.rb

@@ -85,8 +85,9 @@ module Marko
     end
 
     def belongs_to?(ref)
-      owner = root.find{|n| n.id == ref}
-      self == owner&.find{|n| n == self}
+      node = self.parent
+      node = node.parent while node && node.id != ref
+      node&.id == ref
     end
 
     # @return [Node] the root node in the node hierarchy

data/lib/marko/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Marko
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/marko.rb

@@ -21,6 +21,14 @@ module Marko
       File.dirname __dir__
     end
 
+    def demo
+      File.join(root, 'lib', 'assets', 'demo')
+    end
+
+    def samples
+      File.join(root, 'lib', 'assets', 'samples')
+    end
+
     # helper method for assemblage
     # @see Marko::Services::Assemble
     def assemble(&block)

data/sancho.yml

@@ -0,0 +1,6 @@
+domain: nvoynov.github.io/marko
+title: Marko Markup Compiler
+pages:
+- README.md
+- CHANGELOG.md
+- STORY.md

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: marko
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nikolay Voynov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-01-02 00:00:00.000000000 Z
+date: 2023-11-22 00:00:00.000000000 Z
 dependencies: []
 description: |
   Marko supplies a "docs-as-code" approach for compiling bulky software artifacts by providing source storage, original plain text markup, compiler templates, command-line and Gem interfaces.
@@ -26,6 +26,20 @@ files:
 - Gemfile.lock
 - README.md
 - Rakefile
+- STORY.md
+- _layouts/footer.md
+- _layouts/header.md
+- _layouts/layout.html
+- _layouts/robots.txt.erb
+- _layouts/sitemap.xml.erb
+- _layouts/styles.css
+- docs/changelog.html
+- docs/css/styles.css
+- docs/index.html
+- docs/readme.html
+- docs/robots.txt
+- docs/sitemap.xml
+- docs/story.html
 - exe/marko
 - lib/assets/demo/README.md
 - lib/assets/demo/src/fr/assemble.md
@@ -41,7 +55,23 @@ files:
 - lib/assets/demo/src/ur/uc.general.flow.md
 - lib/assets/init/README.md
 - lib/assets/init/Rakefile
-- lib/assets/init/tt/artifact.md.tt
+- lib/assets/init/tt/custom.md.tt
+- lib/assets/init/tt/default.md.tt
+- lib/assets/samples/0_index.md
+- lib/assets/samples/1_intro.md
+- lib/assets/samples/2_stakh.md
+- lib/assets/samples/3_actors.md
+- lib/assets/samples/4_cases.md
+- lib/assets/samples/5_entities.md
+- lib/assets/samples/6_concerns.md
+- lib/assets/samples/SRS-IEEE-830-1998.md
+- lib/assets/samples/SRS-RUP.md
+- lib/assets/samples/business-case.md
+- lib/assets/samples/ears.md
+- lib/assets/samples/gen_punch_domain.rb
+- lib/assets/samples/requirements.md
+- lib/assets/samples/stakeholders.png
+- lib/assets/samples/vision.md
 - lib/marko.rb
 - lib/marko/artifact.rb
 - lib/marko/assembler.rb
@@ -69,6 +99,7 @@ files:
 - lib/marko/validator.rb
 - lib/marko/version.rb
 - marko.gemspec
+- sancho.yml
 homepage: https://github.com/nvoynov/marko
 licenses: []
 metadata:
@@ -91,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Marko is a markup compiler that builds a tree from separated markup sources

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

@@ -1,3 +0,0 @@
-<%= @node.header %>
-<%= @node.meta   %>
-<%= @node.body   %>