docs: add fall-back redirects for unrendered pages

There are quite a couple of pages we do not render, e.g. all of the
`howto/` ones.

The existing Rails App can get away with trying to redirect all unknown
pages in `docs/` to the git/git repository via a generic wildcard
pattern.

In the static website, we do not have that luxury. But we can at least
add corresponding redirects for missing pages that are linked to.

While at it, work around a couple incorrect constructs such as
`linkgit:../<...>` and `linkgit:technical/<...>`.

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

script/update-docs.rb

@@ -310,6 +310,8 @@ def index_doc(filter_tags, doc_list, get_content)
         new_content
       end
 
+      check_paths = Set.new([])
+
       doc_files.each do |entry|
         path, sha = entry
         ids = Set.new([])
@@ -355,6 +357,7 @@ def index_doc(filter_tags, doc_list, get_content)
             "<a href='https://curl.se/docs/manpage.html'>curl</a>"
           else
             relurl = "docs/#{x[1].gsub(/&#x2d;/, '-')}"
+            check_paths.add(relurl)
             "<a href='{{< relurl \"#{relurl}\" >}}'>#{x[1]}[#{x[2]}]</a>"
           end
         end
@@ -368,7 +371,14 @@ def index_doc(filter_tags, doc_list, get_content)
           "<dt class=\"hdlist1\" id=\"#{anchor}\"> <a class=\"anchor\" href=\"##{anchor}\"></a>#{$1} </dt>"
         end
         # Make links relative
-        html.gsub!(/(<a href=['"])\/([^'"]*)/, '\1{{< relurl "\2" >}}')
+        html.gsub!(/(<a href=['"])\/([^'"]*)/) do |relurl|
+          before = $1
+          after = $2
+          after.sub!(/^docs\/\.\.\//, 'docs/')
+          after = 'pack-format' if after == 'technical/pack-format'
+          check_paths.add(after.sub(/#.*/, ''))
+          "#{before}{{< relurl \"#{after}\" >}}"
+        end
 
         doc_versions = version_map.keys.sort{|a, b| Version.version_to_num(a) <=> Version.version_to_num(b)}
         doc_version_index = doc_versions.index(version)
@@ -456,6 +466,32 @@ def index_doc(filter_tags, doc_list, get_content)
           end
         end
       end
+
+      # In some cases, documents are skipped from git-scm.com, e.g. the
+      # `howto/` files. As a consequence, some links may point to locations
+      # that are not populated. Let's redirect to the source files in the
+      # git/git repository.
+      check_paths.each do |path|
+        doc_path = "#{SITE_ROOT}external/docs/content/#{path}.html"
+        if !File.exists?(doc_path)
+          type = 'blob'
+          target = path.sub(/^docs\//, '')
+          if target == 'api-index'
+            type = 'tree'
+            target = 'technical'
+          elsif target == 'howto-index'
+            type = 'tree'
+            target = 'howto'
+          else
+            target += '.txt'
+          end
+          front_matter = { "redirect_to" => "https://github.com/git/git/#{type}/HEAD/Documentation/#{target}" } # ltrim `docs/`
+          FileUtils.mkdir_p(File.dirname(doc_path))
+          File.open(doc_path, "w") do |out|
+            out.write(wrap_front_matter(front_matter))
+          end
+        end
+      end
     end
     data["latest-version"] = version if !data["latest-version"] || Version.version_to_num(data["latest-version"]) < Version.version_to_num(version)
   end