kdwatch 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc8f8c23c6efa56df70b322eb61dc16b913fdf1a93640d3de4da1feeadfba752
-  data.tar.gz: ab67e9ebabd65974a86d65f89a0ffc20af380a1806a13501fa6ecefb07076663
+  metadata.gz: 77f59a0c0a41535d090f2b858a44759a830b7cddc4e760a39c75613f06d2b37f
+  data.tar.gz: 6c53346765beb3f0391991db58bda4f00debfed880b8dca8763462567bbcd435
 SHA512:
-  metadata.gz: c072cf5ae36599a794e6af8520f2fb0d4cb31d87441cec63c9e9137198bea04f4169b553a173787b1073759f04e27603f162b20ca8b0df745f24b2be4b1aa033
-  data.tar.gz: '012684f1584c8f9ddb902a52369510b137840d9a29bac34732cc1939821d6ae96f6598bd57eb925515f9715936935351aa123fd4c9f619c63976b99274e174fc'
+  metadata.gz: d9c2df05241e752a0d7d80e34cf8324872110a0aa4bc800bb9ef7ec1afe0ad2034b06691b56d84c14a6462c252606ef371cad1f85f021ac424046c09dcdc5182
+  data.tar.gz: 001ca06bd402115c0d63e8cd06e3558a99787f12ba97b9641c158ec8f9f8d87f99cdea3850a5121b28f53336d14c1312c13ec037ace624b97c19effba70fdea8

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/README.md

@@ -0,0 +1,142 @@
+# Kdwatch
+
+Auto-formatting, auto-reloading display of formatted [kramdown-rfc][] document in browser
+
+[kramdown-rfc]: http://rfc.space
+
+## Installation
+
+```
+$ pip3 install --upgrade xml2rfc
+$ gem update
+$ gem install kdwatch
+```
+
+* For some reason, the initial `gem install` takes a couple of minutes,
+  during the first few of which it may seem nothing happens.
+* If the above `pip3` (or `pip`) doesn't work, no problem: in a pinch,
+  kdrfc will use the IETF web service for xml2rfc processing (but that
+  may be a bit slower).
+* Depending on system configuration, add `sudo` on the pip/gem
+  commands (but don't if it isn't actually needed).
+
+## Usage
+
+* Open a separate terminal window/screen.
+* Go to a directory that has a single draft-*.md (or select one by
+  specifying the markdown file name on the command line) and run:
+
+```
+$ kdwatch
+```
+
+* After about 10 seconds, a browser will open (or an error message will
+pop up with the URL to use, which depends on the options given, but
+defaults to <http://127.0.0.1:7991/>).
+
+Now, whenever you do an editor save of the kramdown-rfc markdown file,
+kdwatch auto-formats and, after a couple of seconds(*), you see an
+updated HTML in the browser without pressing buttons or switching windows.
+
+You will need to keep the `kdwatch` terminal/screen open to see
+potential error messages, e.g., if you break the markdown in some way.
+(The author uses an Emacs "Async Shell Command" buffer for that.)
+
+(*) The latency depends on your computer and a bit on the size of the
+    file, say, around 1.6 s for my Intel Mac, 0.8 s for my M1 Mac.
+
+### There can only be one (per host/port)
+
+There can only be one kdwatch active on each host and port.  You will
+need to specify a different port (or host!) to run more than one
+kdwatch at the same time.
+
+* `-p port` to select a port number (default: 7991)
+* `-1` to `6` as a shortcut for `-p 7991` (default) to `-p 7996` (must be last
+  option because of an idiosyncrasy of the optionparser library)
+
+kdwatch has two flags to simplify handling servers that might be
+accumulating on one host/port:
+
+* `-e` to kill (SIGINT) any current holder of the port given and exit
+* `-r` to do this, and to start a new instance as well
+
+So the most likely use is going to be:
+
+```
+kdwatch -r
+```
+
+or maybe
+
+```
+kdwatch -r2
+```
+
+for the second draft you are editing at the same time,
+
+or, if your drafts are weirdly named or you need to select one out of
+many
+
+```
+kdwatch -r5 weird-draft.md
+```
+
+(Glitches are to be expected if you *start* more than one server out of
+the same directory at the same instant; TODO; for now, wait 10 seconds
+before starting another from the same directory.)
+
+### 7991, haven't I heard that number before?
+
+The default port number was chosen after [RFC 7991], the initial (no
+longer really authoritative) version of the v3 RFCXML specification,
+and the port shortcuts 1 to 6 point to this and further RFCs from this
+series.
+(7997 is a particularly lame RFC, so it cannot be chosen by a
+shortcut [actually: this port is already registered for something else].)
+
+[RFC 7991]: https://rfc-editor.org/rfc/rfc7991.html
+
+### kdwatch is a web server
+
+kdwatch essentially is a web server and can listen on any host
+interface you might have:
+
+* `-o host` to select an interface address on the serving host (default: 127.0.0.1)
+* `-i` as a shortcut for `-o :: ` (`i` stands for "on the Internet")
+
+Unless used on 127.0.0.1 (or ::1), kdwatch is accessible to anyone who
+can access your laptop over IP.  That may be a security problem -- do
+not specify a non-local interface unless you know you are not “on the
+Internet” (or trust the way I cobble together software).  If you are,
+maybe `kdwatch -e` before going there!
+
+The fun thing with the `-i` option is that you can replace the local
+URL by filling in the hostname of the laptop and use the resulting URL
+on a different browser (e.g., `http://mylaptop.local:7991` on your iPad or
+another laptop), and save some screen real-estate on your laptop.
+With a globally routable address, kdwatch even can be used for joint
+viewing in a team.
+
+## Feedback, please
+
+This has only been tested on macOS and briefly on Linux.  No idea about WSL.
+There is very little error handling yet, so restarts of the tool may
+be required, or sometimes reloading in the browser (CMD-R/F5) is all
+that is needed.
+
+If you try it, please send feedback (and, in case of an error, *all*
+output on the kdwatch terminal window, please).
+
+Bug reports, pull requests, or simple suggestions are welcome on GitHub at
+<https://github.com/cabo/kdwatch>, e.g., simply [submit an
+issue][issues] or send me [mail][].
+
+[issues]: https://github.com/cabo/kdwatch/issues
+[mail]: mailto:cabo@tzi.org?Subject=kdwatch
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][].
+
+[MIT License]: https://opensource.org/licenses/MIT

data/bin/kdwatch

@@ -3,25 +3,128 @@ ENV["LANG"]="en_US.utf-8"
 ENV["LC_CTYPE"]="en_US.utf-8"
 ENV["KRAMDOWN_PERSISTENT"]="yes"
 
+
+require 'optparse'
+require 'ostruct'
+
+require_relative "../lib/kdwatch/version"
+
+KDWATCH_PORT = 7991             # currently unregistered...
+
+options = OpenStruct.new
+
+op = OptionParser.new do |opts|
+  opts.banner = <<BANNER
+Usage: kdwatch [options] draft-foo.md|.mkd|.xml
+Version: #{Kdwatch::VERSION}
+BANNER
+  opts.on("-V", "--version", "Show version and exit") do |v|
+    puts "kdwatch #{Kdwatch::Version}"
+    exit
+  end
+  opts.on("-H", "--help", "Show option summary and exit") do |v|
+    puts opts
+    exit
+  end
+  opts.on("-e", "--[no-]end", "End existing server and exit")
+  opts.on("-r", "--[no-]replace", "Replace existing server")
+  opts.on("-oNAME", "--host=NAME", String, "Server host (127.0.0.1)")
+  opts.on("-i", "--internet", 'Abbr. "on the Internet" (host = "::")')
+  opts.on("-pNUM", "--port=NUM", Integer, "Port number (#{KDWATCH_PORT})")
+  opts.on("-[1-6]", "--[1-6]", Integer, "Abbr. port number (#{KDWATCH_PORT/10}x), must be last")
+end
+begin
+  op.parse!(into: options)
+rescue OptionParser::InvalidOption => e
+  warn "** #{e}"
+  warn op
+  exit 1
+end
+
+if options.internet
+  warn "** overriding host #{options.host} with ::" if options.host
+  options.host = "::"
+else
+  options.host ||= "127.0.0.1"
+end
+if short_port = options[""]
+  port = short_port + KDWATCH_PORT/10*10
+  warn "** overriding port #{options.port} with #{port}" if options.port
+  options.port = port
+else
+  options.port ||= KDWATCH_PORT
+end
+
+# p options
+
+## -r: Kill any previous kdwatch and continue ("restart")
+## -e: Kill any previous kdwatch and exit
+if options.replace || options.end
+  require 'open3'
+
+  status = 1
+
+  lsof_host = case options.host
+              when "::", "0.0.0.0"
+                ""              # can't do more specific with lsof; hope for the best
+              when /:/
+                "@'[#{options.host}]'"
+              else
+                "@'#{options.host}'"
+              end
+
+  stdout_str, stderr_str, s = Open3.capture3("lsof -ti #{lsof_host}:#{options.port} -s TCP:LISTEN")
+  pids = if s.success? && stdout_str =~ /\A[0-9\s]*\z/ && stderr_str
+           stdout_str.split
+         else
+           text = stdout_str + stderr_str
+           warn "** lsof, status #{s}, says: #{text}" if text != "" || s.exitstatus != 1
+           []
+         end
+  if pids == []
+    warn "** Nothing listening on kdwatch port" unless options.replace
+  elsif pids.size != 1
+    warn "** More than one process listening on kdwatch port, nothing done"
+  else
+    begin
+      status = Process.kill(2, Integer(pids[0])) - 1 # should be 1 for 1 kill, exit 0 then
+    rescue Errno => e
+      warn "** #{pids[0]}: #{e.inspect}"
+    end
+  end
+  exit(status) if options.end
+end
+
+## Find an .mkd or a draft-*.md (excluding README.md and such)
 if ARGV == []
-   ARGV.replace Dir["draft-*.md"]
+   ARGV.replace Dir.glob(["draft-*.md", "*.mkd"])
    warn_replace = 1
 end
 
 if ARGV.size != 1
-   warn "** Usage: #$0 [draft-foo.md]"
-   warn "**   More than one draft file found #{ARGV.inspect}"   if warn_replace
-   warn "**   Please select one for watching."   if warn_replace
+   warn op
+   if warn_replace
+     if ARGV.size > 1
+       warn "**   More than one draft file found #{ARGV.inspect}"
+       warn "**   Please select one for watching."
+     else
+       warn "**   No draft file draft-*.md or *.mkd found."
+     end
+   end
    exit 1
 end
 
-ENV["KD_WATCH_SRC"] = ARGV[0]
+ENV["KDWATCH_SRC"] = ARGV[0]
+ENV["KDWATCH_HOST"] = options.host
+ENV["KDWATCH_PORT"] = options.port.to_s
+live_reload_port = options.port + 51234 # move up into ephemeral space
+ENV["KDWATCH_LRPORT"] = live_reload_port.to_s
 
 File.write(".config.ru", <<HERE)
 require 'rack-livereload'
-use Rack::LiveReload, min_delay: 500, source: :vendored, no_swf: true
+use Rack::LiveReload, min_delay: 500, source: :vendored, no_swf: true, port: #{live_reload_port}, live_reload_port: #{live_reload_port}
 require 'kdwatch-app.rb'
 run Sinatra::Application
 HERE
 
-exec("rackup -E production -s thin -p 7991 .config.ru")
+exec("rackup -E production -s thin -o #{options.host} -p #{options.port} .config.ru")

data/kdwatch.gemspec

@@ -28,10 +28,11 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "bundler", '~> 2.2'
   spec.add_dependency "thin", '~> 1.8'
+  # spec.add_dependency "cabo-guard-livereload", '~> 2.5' #, require: false
   spec.add_dependency "guard-livereload", '~> 2.5' #, require: false
   spec.add_dependency "rack-livereload", '~> 0.3'
   spec.add_dependency "guard", '~> 2.17'
   spec.add_dependency "sinatra", '~> 2.1'
-  spec.add_dependency "kramdown-rfc2629", '~> 1.4'
+  spec.add_dependency "kramdown-rfc2629", '~> 1.5'
   spec.add_dependency "net-http-persistent", '~> 4.0'
 end

data/lib/kdwatch/version.rb

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

data/lib/kdwatch-app.rb

@@ -9,25 +9,49 @@ require "rack-livereload"
 require "guard"
 require "sinatra"
 require "kramdown-rfc2629"
+ENV["KDRFC_PREPEND"] = "time"
+require "kramdown-rfc/kdrfc-processor"
 require "net/http/persistent"
 
+host = ENV["KDWATCH_HOST"]
+port = ENV["KDWATCH_PORT"]
 
-sfn = ENV["KD_WATCH_SRC"]
+sfn = ENV["KDWATCH_SRC"]
 fail "No source given" unless sfn
 
 dfn = File.join(File.dirname(sfn), "#{File.basename(sfn, ".*")}.html")
 
 puts dfn
 
+kdrfc = KramdownRFC::KDRFC.new
+kdrfc.options.v3 = true
+kdrfc.options.html = true
+
 get "/" do
   sfc = File.stat(sfn).ctime
   dfc = File.stat(dfn).ctime rescue Time.at(0)
   if sfc > dfc
     warn "Rebuilding..."
-    system("time kdrfc -3h --no-txt #{sfn}")
-    warn "...done"
+    begin
+      kdrfc.process sfn
+    rescue StandardError => e
+      warn e.to_s
+    else
+      warn "...done"
+    end
+  end
+  dfc = File.stat(dfn).ctime rescue Time.at(0)
+  ret = File.read(dfn)
+  if sfc > dfc # somehow the above went wrong
+    ret.gsub!(<<CSS, <<RED)
+/* general and mobile first */
+html {
+CSS
+/* general and mobile first */
+html { border: 5px solid red;
+RED
   end
-  File.read(dfn)
+  ret
 end
 
 get "/metadata.min.js" do
@@ -39,17 +63,20 @@ get "/rfc-local.css" do
 end
 
 File.write(".Guardfile", <<GF)
-guard 'livereload' do
+guard :livereload, :port => #{ENV["KDWATCH_LRPORT"]} do
   watch("#{sfn}")
 end
 GF
 
 rd, _wr = IO.pipe
-spawn("guard -G .Guardfile", in: rd)
+spawn("guard -G .Guardfile", in: rd, close_others: true)
 
 # wrong: puts settings.port
 
-url = "http://127.0.0.1:7991"
+host = "localhost" if host == "::" # work around macOS peculiarity
+host = "[#{host}]" if host =~ /:/
+
+url = "http://#{host}:#{port}"
 
 spawn("sleep 5; open #{url} || xdg-open #{url} || echo @@@ Please open #{url}")
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kdwatch
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Carsten Bormann
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-03 00:00:00.000000000 Z
+date: 2021-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: net-http-persistent
   requirement: !ruby/object:Gem::Requirement
@@ -133,6 +133,7 @@ files:
 - ".gitignore"
 - Gemfile
 - LICENSE.txt
+- README.md
 - bin/kdwatch
 - kdwatch.gemspec
 - lib/kdwatch-app.rb
@@ -156,7 +157,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: 'kdwatch: open auto-reloaded HTML for kramdown-rfc in a browser.'