lib/project-readme.rb

   1 # Nick's web site: Generate a project page from a submodule README.md
   2 #
   3 # Copyright © 2021 Nick Bowler
   4 #
   5 # This program is free software: you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation, either version 3 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  17
  18 def project_readme(item = @item)
  19     tag = item.fetch(:release, "HEAD")
  20     shortname = item.fetch(:shortname, item[:module])
  21
  22     data, status = Open3.capture2("git", "submodule", "foreach", "--quiet",
  23       "case $sm_path in */" + item[:module] + ")" +
  24       "git fetch --quiet --tags;" +
  25       "git log --max-count=1 --format=%cI #{tag}; printf '\\35';" +
  26       "git show #{tag}:NEWS 2>/dev/null; printf '\\35';" +
  27       "git remote get-url origin; printf '\\35';" +
  28       "git show #{tag}:README.md ;;" +
  29       "esac")
  30     raise "git submodule foreach failed" if status != 0
  31
  32     date, news, gituri, contents = data.split("\35", 4)
  33     intro, contents = contents.split("#", 2)
  34     contents = if contents.nil? then "" else "\n#" + contents end
  35
  36     gituri.strip!
  37     gitweb = gituri.sub(%r{^[^/]*(.*)(/.*)}, '\1/gitweb\2')
  38     date = Date.iso8601(date).to_time
  39
  40     obtaining = <<~EOF
  41         # Obtaining #{item[:title]}
  42     EOF
  43
  44     if item[:release].nil?
  45         obtaining += "\n" + <<~EOF
  46             There are presently no released versions of #{shortname}.
  47         EOF
  48     else
  49         newsver, news = news.split("\n", 2)
  50         newsver.sub!(/^.*?([[:digit:]][^:]*).*$/, '\1')
  51
  52         targz = "#{shortname}-#{newsver}.tar.gz"
  53         distbase = "/archive/#{shortname}"
  54         obtaining += <<~EOF
  55             [archive]: #{distbase}
  56
  57             All released files are available from the [#{shortname} archive
  58             directory][archive].
  59         EOF
  60     end
  61
  62     obtaining += <<~EOF
  63         The latest development sources [may be browsed online](#{gitweb}) or
  64         cloned directly using git, e.g.,
  65
  66         <kbd>git clone #{gituri}</kbd>
  67     EOF
  68
  69     unless item[:release].nil?
  70         obtaining += "\n" + <<~EOF
  71             [targz]: #{distbase}/#{targz}
  72             [targzsig]: #{distbase}/#{targz}.sig
  73
  74             The most recent release is version #{newsver}, released on
  75             #{date.getutc.strftime("%Y-%m-%d")}.  Source code for this version
  76             is available in [#{targz}][targz] ([signature][targzsig]).
  77             Noteworthy changes in this release:
  78         EOF
  79         obtaining += "\n"
  80         news.each_line do |line|
  81             break if line =~ /^[^[:space:]]/
  82             obtaining += line.lstrip
  83         end
  84
  85         obtaining += "\n\n" + <<~EOF
  86             [gpg]: https://gnupg.org/
  87
  88             Use the signature file to verify that the corresponding source
  89             bundle is intact.  After downloading both files, if [GnuPG][gpg]
  90             is installed, the signature can be verified with a command like:
  91
  92             <kbd>gpg --verify #{targz}.sig</kbd>
  93
  94             If the verification fails because you don't have the required
  95             public key, that key can be imported with a command such as:
  96
  97             <kbd>gpg --keyserver keys.gnupg.net --recv-keys 5B45D3D185B8E1F6</kbd>
  98
  99             Then run the verify command again.
 100         EOF
 101     end
 102
 103     return "#{intro}\n\n#{obtaining}\n\n#{contents}"
 104 end