kdwatch 0.1.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaba18036cbe879e4f88d5b74513ad4a5d36abb843234c83c35e688aaaf36e03
-  data.tar.gz: ea272b95fef2f02ec9513539dee9f4f5126b4e65c3c6a97b0603d94fa7cd37e2
+  metadata.gz: 50e6ea6a1e81ab7f17173c1251395a6fbeb1a4b4c236d1c9c6fd1731f3118ca8
+  data.tar.gz: 31235eb66b35d5c39ebd1f124e938dfcc9b3f305a020ddf05dc610b7e8832707
 SHA512:
-  metadata.gz: 603817fcb75e8b474a4f6bc7d58408c4d8fcc55f7cbd50d1cd6a48f8d21a8b2672f2b221697b9948412e2bf4825dd9925ae10f9a4be6a6360e7c5e54c94c9471
-  data.tar.gz: 4237a7b045723de06320999301e0c388d879d6f5016b12c7170702b7b24981e302848eb76aad46513cde1a0d37792811165710c865a9cb597064dca17a54eed5
+  metadata.gz: 39e2d6062ef4adf87ce11d05c2d18e4d305de91e8212d1c204bc7bd0b8c8086f3c662e59deeaa284779f326bebdbd3c06af6ec993c4bc3ad4ad0dea0a468ee80
+  data.tar.gz: 9db4d837a11aea7413de4362bc418cb56fb2f987dc926ab722bd1b8be06850a2a2e51110e78dd75caebec5b2b7280e0b14592910f00478879b127e8724d0b070

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,17 +3,77 @@ 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 ARGV[0] == "-e" || ARGV[0] == "-r"
+if options.replace || options.end
   require 'open3'
 
   status = 1
-  flag = ARGV.shift
 
-  stdout_str, stderr_str, s = Open3.capture3("lsof -ti :#{KDWATCH_PORT} -s TCP:LISTEN")
+  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
@@ -22,7 +82,7 @@ if ARGV[0] == "-e" || ARGV[0] == "-r"
            []
          end
   if pids == []
-    warn "** Nothing listening on kdwatch port" unless flag == "-r"
+    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
@@ -32,7 +92,7 @@ if ARGV[0] == "-e" || ARGV[0] == "-r"
       warn "** #{pids[0]}: #{e.inspect}"
     end
   end
-  exit(status) if flag == "-e"
+  exit(status) if options.end
 end
 
 ## Find an .mkd or a draft-*.md (excluding README.md and such)
@@ -42,8 +102,7 @@ if ARGV == []
 end
 
 if ARGV.size != 1
-   warn "** Usage: #$0 [-r] [draft-foo.md]"
-   warn "**        #$0 -e"
+   warn op
    if warn_replace
      if ARGV.size > 1
        warn "**   More than one draft file found #{ARGV.inspect}"
@@ -55,13 +114,17 @@ if ARGV.size != 1
    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 #{KDWATCH_PORT} .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.1"
+  VERSION = "0.4.1"
 end

data/lib/kdwatch-app.rb

@@ -9,25 +9,49 @@ require "rack-livereload"
 require "guard"
 require "sinatra"
 require "kramdown-rfc2629"
+ENV["KDRFC_PREPEND"] = "time" if system("time", "true", err: "/dev/null")
+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,7 +63,7 @@ get "/rfc-local.css" do
 end
 
 File.write(".Guardfile", <<GF)
-guard 'livereload' do
+guard :livereload, :port => #{ENV["KDWATCH_LRPORT"]} do
   watch("#{sfn}")
 end
 GF
@@ -49,7 +73,10 @@ 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.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Carsten Bormann
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-04 00:00:00.000000000 Z
+date: 2022-02-03 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.32
 signing_key:
 specification_version: 4
 summary: 'kdwatch: open auto-reloaded HTML for kramdown-rfc in a browser.'