kdwatch 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaba18036cbe879e4f88d5b74513ad4a5d36abb843234c83c35e688aaaf36e03
-  data.tar.gz: ea272b95fef2f02ec9513539dee9f4f5126b4e65c3c6a97b0603d94fa7cd37e2
+  metadata.gz: c8a50fa7ebbda382c852684c4b440e2a75213450af0e02e68130d9fd8fccabb8
+  data.tar.gz: 366e1aef8fcc0144c8ccc6adc74ee5492fba1088febaeee9a47e699ce9f57496
 SHA512:
-  metadata.gz: 603817fcb75e8b474a4f6bc7d58408c4d8fcc55f7cbd50d1cd6a48f8d21a8b2672f2b221697b9948412e2bf4825dd9925ae10f9a4be6a6360e7c5e54c94c9471
-  data.tar.gz: 4237a7b045723de06320999301e0c388d879d6f5016b12c7170702b7b24981e302848eb76aad46513cde1a0d37792811165710c865a9cb597064dca17a54eed5
+  metadata.gz: 64ebdd540be0d137d8b436552044ec1b67f17ec7ad3eabfc9c64640fdfcc31249de52f4f9e62b1562031287908e232a815663a1d31b9be04ae80bc0d9578514a
+  data.tar.gz: 242b365d72a33ebc24f36b4743baf3af43a0018348d88dcdf1b9fbd95da72ff65c3ef670a822d7f3a34d55fd847ab574ca1f182cfc52157247482a604dbc04c5

data/README.md

@@ -0,0 +1,122 @@
+# Kdwatch
+
+Autoreloading display of [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` doesn't work: 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` (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 markdown file, after a
+couple of seconds (1.6 s for my Intel Mac, 0.8 s for my M1 Mac) you
+see an updated HTML in the browser.
+
+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.
+
+### 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 start more than one
+pkdwatch.
+
+* `-o host` to select an address on the serving host (default: 127.0.0.1)
+* `-i` as a shortcut for `-o ::`
+* `-p port` to select a port number (default: 7991)
+* `-1` to `6` as a shortcut for `-p 7991` 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
+
+So the most likely use is going to be:
+
+```
+kdwatch -r
+```
+
+or, if your drafts are weirdly named or you need to select one out of
+many
+
+```
+kdwatch -r weird-draft.md
+```
+
+### This is a web server
+
+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.
+
+kdwatch essentially is a web server and, unless used on 127.0.0.1 (or
+::1), is accessible to anyone who can access your laptop over IP.
+
+That may be a security problem -- do not specify non-local hosts
+unless you are not “on the Internet” (or trust the way I cobble
+together software).
+If you did, maybe `kdwatch -e` before going there!
+
+The web-server function may also be a feature -- it even can be used for joint viewing...
+
+### 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 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
+
+## 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,6 +28,7 @@ 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'

data/lib/kdwatch-app.rb

@@ -11,8 +11,10 @@ require "sinatra"
 require "kramdown-rfc2629"
 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")
@@ -39,7 +41,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 +51,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}")
 

data/lib/kdwatch/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kdwatch
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Carsten Bormann
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-04 00:00:00.000000000 Z
+date: 2021-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -133,6 +133,7 @@ files:
 - ".gitignore"
 - Gemfile
 - LICENSE.txt
+- README.md
 - bin/kdwatch
 - kdwatch.gemspec
 - lib/kdwatch-app.rb