howdoc 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02cc27d9848b0932cc7ba10c66b8e5682c955071f2cde03f27e6c9061c52d82c
-  data.tar.gz: 1bed4d6da3860c0ea8ac1f3f680218f24941f45fbb7d8e3b0699085e70588811
+  metadata.gz: 72edea92225be55592acd2d56c732d5d82e140193b06dc276b0c691440ff2e3f
+  data.tar.gz: 2ec1eea553ec1b5ca6e23f9f320e082367ded34280cf6701e8f284f06f1ef34c
 SHA512:
-  metadata.gz: 72e52519fec7d24abdb8765aa146702ef053a627fd87e4b40e1ff77775ba69ed626db5250accbb307719bbfee68a7f12e8d1fac6d966a0ab05df9859a1b38326
-  data.tar.gz: 70208bdc3b1557985b69bbdceb70ade90a91c39b9063412ed922df7cd1cae26e5629875dd1f66a16277364af39d49eff10ede8df80695c678a1792675f0f0b42
+  metadata.gz: 9692dcfc9505fa3cf80eff5ea7a6c2dcb244619a41aa163cbab98c04a16b01bb13d82d646db46b1e98025f386a47594553abfd4b59a6e937040b555a6f9ecadb
+  data.tar.gz: 8ee1913418a639198f1134958ce9748ff83a231a5d86b8fb237675ab264d62b50ad9f5cdfd9e8433310b0c6c226bbf35ec6a21d9afd22c5eee0884b6b9042c86

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.3.0
+
+Every page now carries the menu, so a guide opened from a link is a whole page
+rather than a dead end, and a documentation set no longer needs a frame to hold
+its navigation together.
+
+- A guide leaves an empty `<nav data-howdoc-nav>`, and the index pass fills it
+  in once every guide is on disk -- a guide cannot draw a menu of guides when it
+  is written, because no other guide exists yet. A template without the
+  placeholder is left exactly as it was.
+- The same pass writes previous/next links into `<nav data-howdoc-pager>`.
+- The menu links the same guide in the other languages, matched by identifier,
+  since a translated heading gives a translated file name. Each language names
+  itself in its own language.
+- `config.group_label` now heads sections in the menu as well as the index.
+- The index carries `howdoc.index.intro` when an application translates it, so
+  the landing page can say something of its own without a hand-kept file.
+- Templates read the gem's own words through a lookup an application's I18n
+  cascade cannot answer with something unrelated.
+
+## 0.2.0
+
+Guides are now written in every language the application publishes, from a
+single test run. Previously a run produced guides in the language the suite
+happened to be running in, and the other languages were silently left behind.
+
+- `config.locales` names the languages every guide is written in, not only the
+  languages an index is built for.
+- A step is recorded as an action and its values rather than as a finished
+  sentence, and narrated once per language when the guide is written.
+- Screenshots are taken once and copied into each language's guide.
+- A guide's own heading and introduction can be translated under
+  `howdoc.documents.<permalink>`, since they come from the test rather than
+  from the engine.
+- `Howdoc::Narrator.field` defers a field label until the language is known.
+  `Howdoc.start(locale:)` still pins a guide to one language.
+- Untranslated keys are reported with the language they are missing from.
+
 ## 0.1.0
 
 First release. Extracted from a working in-house documentation helper that had

data/README.md

@@ -45,6 +45,7 @@ Howdoc.configure do |config|
   config.enabled = ENV['DOC'].present?    # off unless asked for
   config.host    = 'example.com'          # the address a reader should open
   config.formats = %i[html]
+  config.locales = %i[en et]              # languages every guide is written in
 
   config.register_locale_path 'test/howdoc/locales/*.yml'
   config.register_template_path 'test/howdoc/templates'
@@ -70,8 +71,7 @@ class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
       id: metadata[:doc],
       permalink: metadata[:permalink],
       intro: metadata[:intro],
-      title: "How to #{metadata[:description]}?",
-      locale: I18n.locale
+      title: "How to #{metadata[:description]}?"
     )
   end
 
@@ -137,6 +137,52 @@ Three actions come translated even though no wrapper records them, because
 almost every suite ends up writing a helper that needs one: `menu` (a `path`),
 `fill_in_editor` (a `value`) and `sign_in_required` (a `text`).
 
+## Languages
+
+A test runs in one language. Its guide is written in all of them.
+
+Name the languages your application publishes and every recorded guide is
+written once per language, from the same run:
+
+```ruby
+config.locales = %i[en et]
+```
+
+```
+public/docs/en/how_to_add_a_claim.html
+public/docs/et/how_to_add_a_claim.html
+```
+
+Nothing is recorded as a finished sentence, which is what makes this possible:
+a step is kept as the action and the values it happened with, and the sentence
+is composed once per language when the page is written. The screenshot is taken
+once, while the browser is still on the page, and copied into each language's
+guide -- it is a picture of the same application either way.
+
+A guide's own heading is the exception, because it comes from the test rather
+than from the engine. Translate `howdoc.documents.<permalink>.title` to give the
+same guide a heading in another language, and `.intro` for its introduction:
+
+```yaml
+et:
+  howdoc:
+    documents:
+      how_to_add_a_claim:
+        title: Kuidas lisada nõue?
+```
+
+Left untranslated, every language gets the heading the test gave it. A guide
+that belongs to one language only -- something only that language's users ever
+see -- says so: `Howdoc.start(..., locale: :et)`.
+
+A value that reads differently in different languages must not be resolved
+while the test runs, or it freezes into the language the test ran in. Field
+labels are the usual case, and `Howdoc::Narrator.field` defers one:
+
+```ruby
+Howdoc.record(:check, field: Howdoc::Narrator.field(locator))
+```
+
 ## Wording
 
 Every sentence is an I18n key under `howdoc.actions`, so the engine contains no
@@ -161,8 +207,43 @@ own by translating `howdoc.fields.<locator>`, or replace the whole convention:
 config.field_label { |locator| MyLabels.for(locator) }
 ```
 
-Any key that is used but not translated is reported at the end of the run rather
-than leaving a silent hole in the guide.
+Any key that is used but not translated is reported at the end of the run,
+naming the language it is missing from, rather than leaving a silent hole in the
+guide. A step no language can describe is not recorded at all; a step one
+language cannot describe is left out of that language's guide only.
+
+## Navigation
+
+Every page carries the menu, and a guide links the ones before and after it:
+
+```
+public/docs/en/how_to_add_a_claim.html
+  ┌────────────┬────────────────────┐
+  │ Guides     │ 1.3. How to add a … │
+  │ EVERYDAY   │ 1. Log in …         │
+  │ 1.1 …      │ [screenshot]        │
+  │ 1.3 ●      │ ‹ Previous  Next ›   │
+  └────────────┴────────────────────┘
+```
+
+A guide cannot draw that menu when it is written: tests run in forked workers,
+each one writes its own page, and no other guide exists yet. So the guide leaves
+an empty placeholder and the index pass -- which has just read every page back
+-- fills it in:
+
+```haml
+%nav.howdoc-nav{ data: { howdoc_nav: true } }    -# the menu
+%nav.howdoc-pager{ data: { howdoc_pager: true } } -# previous / next
+```
+
+Both are optional. A template that carries neither is left exactly as it is.
+
+The menu also links the same guide in every other language the application
+publishes. Guides are matched by their identifier rather than their file name,
+because a translated heading gives a translated file name, and each language
+names itself in its own language (`howdoc.languages.<code>`).
+
+`config.group_label` heads the sections, in the menu and in the index alike.
 
 ## Templates
 

data/config/locales/howdoc.en.yml

@@ -19,6 +19,11 @@ en:
       visit: Open <strong>%{url}</strong> in your browser.
     document:
       follow_steps: 'Follow these steps:'
+    languages:
+      en: English
+    pager:
+      next: Next
+      previous: Previous
     index:
       empty: No guides have been generated yet.
       title: Guides

data/config/locales/howdoc.et.yml

@@ -19,6 +19,11 @@ et:
       visit: Palun sisesta <strong>%{url}</strong> oma brauserisse.
     document:
       follow_steps: 'Palun jälgige järgnevaid samme:'
+    languages:
+      et: Eesti
+    pager:
+      next: Järgmine
+      previous: Eelmine
     index:
       empty: Ühtegi juhendit ei ole veel loodud.
       title: Juhendid

data/lib/howdoc/capybara_actions.rb

@@ -29,9 +29,8 @@ module Howdoc
 
     def fill_in(locator = nil, with:, currently_with: nil, fill_options: {}, **options)
       doc = Howdoc.extract_options!(options)
-      label = howdoc_field_label(locator)
 
-      narrate(fill_in_action(label), doc, field: label, value: with)
+      narrate(fill_in_action(locator), doc, field: howdoc_field_label(locator), value: with)
 
       super(locator, with:, currently_with:, fill_options:, **options)
     end
@@ -114,16 +113,18 @@ module Howdoc
 
     private
 
+    # Not the label itself: a guide is written in every language the
+    # application publishes, and what a reader calls a field is a translation,
+    # so the label is settled once per language when the page is written.
     def howdoc_field_label(locator)
-      Howdoc::Narrator.field_label(locator, locale: howdoc_locale)
+      Howdoc::Narrator.field(locator)
     end
 
-    def howdoc_locale
-      Howdoc.current&.locale || I18n.locale
-    end
-
-    def fill_in_action(label)
-      case label.to_s
+    # Which sentence a fill_in gets is decided from the field's own name rather
+    # than from its label, because the name is the same in every language and
+    # the choice must be too.
+    def fill_in_action(locator)
+      case Howdoc.config.field_label.call(locator).to_s
       when 'email' then :fill_in_email
       when 'password' then :fill_in_password
       else :fill_in

data/lib/howdoc/configuration.rb

@@ -22,10 +22,13 @@ module Howdoc
     # Writers to run for every finished document, in order.
     attr_accessor :formats
 
-    # Locales to build an index for. Left nil, only the locales that actually
-    # produced a guide get one, which means a run in a single language quietly
-    # drops the other languages' indexes. Naming them keeps every index in
-    # place, empty ones included.
+    # The languages the application publishes its guides in. A test runs in one
+    # language, but every guide it records is written in all of these, so a
+    # second language costs a translation file rather than a second test run.
+    #
+    # These are also the locales an index is built for. Left nil, a guide is
+    # written only in the language the suite is running in, and only the
+    # locales that actually produced a guide get an index.
     attr_accessor :locales
 
     # Screenshots are taken at this height unless the step asked for a full

data/lib/howdoc/document.rb

@@ -4,6 +4,11 @@ module Howdoc
   # One guide: the identity a test gave it, plus the steps recorded while that
   # test ran. A document collects everything in memory and is written out once,
   # so a writer always sees the whole guide rather than a half-built page.
+  #
+  # A test runs in one language but a guide is published in all of them, so a
+  # document holds nothing that a language would change. Every such thing --
+  # the heading, the sentences, the file name -- belongs to an Edition, and a
+  # document has one per language.
   class Document
     # Letters that carry no accent to strip: they are their own character, so
     # Unicode decomposition leaves them untouched and a filename filter would
@@ -13,24 +18,44 @@ module Howdoc
       'đ' => 'd', 'ð' => 'd', 'ł' => 'l', 'þ' => 'th'
     }.freeze
 
-    attr_reader :id, :permalink, :title, :intro, :locale, :steps
+    attr_reader :id, :permalink, :steps, :locales
 
-    def initialize(id:, title:, locale:, permalink: nil, intro: nil)
+    # +title+ and +intro+ are whatever the test knew: a string in the language
+    # it was written in, or a hash keyed by locale when the test itself knows
+    # more than one. Either way a translation under howdoc.documents wins, so a
+    # guide gets a heading in a language no test speaks.
+    def initialize(id:, title:, locales:, permalink: nil, intro: nil)
       @id = id
       @title = title
-      @locale = locale.to_sym
-      @permalink = permalink
       @intro = intro
+      @permalink = permalink
+      @locales = Array(locales).map(&:to_sym)
       @steps = []
       @counter = 0
     end
 
-    def slug
-      @slug ||= (permalink || slugify(title)).to_s
+    def editions
+      @editions ||= locales.map { |locale| Edition.new(self, locale) }
+    end
+
+    # The edition a test is recording into. Screenshots are taken while the
+    # browser is still on the page, long before the other editions are written,
+    # so they are saved where this one keeps its pictures and copied across when
+    # the guides are written.
+    def primary
+      editions.first
+    end
+
+    def locale
+      primary.locale
     end
 
-    def heading
-      id.nil? ? title : "#{id}. #{title}"
+    def title_for(locale)
+      Narrator.document_text(:title, key: translation_key, locale:, default: in_locale(@title, locale))
+    end
+
+    def intro_for(locale)
+      Narrator.document_text(:intro, key: translation_key, locale:, default: in_locale(@intro, locale))
     end
 
     def new_step(**attributes)
@@ -44,23 +69,14 @@ module Howdoc
       steps.last
     end
 
-    def dir
-      File.join(Howdoc.config.root, locale.to_s)
-    end
-
-    def image_dir
-      File.join(dir, 'images')
-    end
-
-    def path(extension)
-      File.join(dir, "#{slug}.#{extension}")
-    end
-
-    def image_filename(number)
-      "#{slug}_#{number}.png"
-    end
-
-    private
+    # What the recording edition answers, asked of the document itself, because
+    # that is what a recorder has in its hand.
+    def slug = primary.slug
+    def heading = primary.heading
+    def dir = primary.dir
+    def image_dir = primary.image_dir
+    def path(extension) = primary.path(extension)
+    def image_filename(number) = primary.image_filename(number)
 
     # Deliberately not ActiveSupport's parameterize: the engine has no business
     # dragging Rails into a project that only wanted a documentation generator.
@@ -68,7 +84,7 @@ module Howdoc
     # Accents are decomposed and their marks dropped rather than deleted whole,
     # so an Estonian title turns into "kuidas_lisada_noue" instead of the
     # unreadable "kuidas_lisada_n_ue" a plain ASCII filter would leave behind.
-    def slugify(string)
+    def self.slugify(string)
       string
         .to_s
         .downcase
@@ -79,5 +95,20 @@ module Howdoc
         .gsub(/[^a-z0-9]+/, '_')
         .gsub(/\A_+|_+\z/, '')
     end
+
+    private
+
+    # The name a translation of this guide's own words is filed under. A
+    # permalink is the obvious one; without it the untranslated title has to do,
+    # since it is the only stable thing a test gave us.
+    def translation_key
+      @translation_key ||= (permalink || self.class.slugify(in_locale(@title, locales.first))).to_s
+    end
+
+    def in_locale(value, locale)
+      return value unless value.is_a?(Hash)
+
+      value[locale.to_sym] || value[locale.to_s] || value.values.first
+    end
   end
 end

data/lib/howdoc/edition.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # One language's version of a guide.
+  #
+  # A guide is recorded once -- the same clicks, the same screenshots -- and
+  # written out once per language. Everything that differs between those
+  # versions is here: the heading, the sentences, the directory the page lands
+  # in and the names of the pictures in it. A template is handed the edition for
+  # the language being written, so nothing in a template has to know that a
+  # second language exists.
+  class Edition
+    attr_reader :document, :locale
+
+    def initialize(document, locale)
+      @document = document
+      @locale = locale.to_sym
+    end
+
+    def id
+      document.id
+    end
+
+    def permalink
+      document.permalink
+    end
+
+    def title
+      @title ||= document.title_for(locale)
+    end
+
+    def intro
+      @intro ||= document.intro_for(locale)
+    end
+
+    def heading
+      id.nil? ? title : "#{id}. #{title}"
+    end
+
+    # A permalink is the same in every language, so the guides sit beside each
+    # other under one name. Without one the file is named after the heading,
+    # which means a translated heading gives a translated file name.
+    def slug
+      @slug ||= (permalink || Document.slugify(title)).to_s
+    end
+
+    def steps
+      @steps ||= document.steps.map { |step| step.narrate(self) }
+    end
+
+    def dir
+      File.join(Howdoc.config.root, locale.to_s)
+    end
+
+    def image_dir
+      File.join(dir, 'images')
+    end
+
+    def path(extension)
+      File.join(dir, "#{slug}.#{extension}")
+    end
+
+    def image_filename(number)
+      "#{slug}_#{number}.png"
+    end
+  end
+end

data/lib/howdoc/narrator.rb

@@ -7,12 +7,30 @@ module Howdoc
   # sentence itself -- every one of them is an I18n key, so the vocabulary is
   # translatable and an application can reword any instruction without touching
   # the code that records it.
+  #
+  # Nothing here is settled while a test runs. A guide is recorded once and
+  # written out in every language it is published in, so a sentence is composed
+  # at writing time, once per language.
   module Narrator
-    SCOPE = 'howdoc.actions'
+    ROOT = 'howdoc'
+    ACTIONS = :actions
+    FIELDS = :fields
+    DOCUMENTS = :documents
+
+    # A value that cannot be settled until the language is known. A form field
+    # is the usual case: what a reader calls it is a translation, so recording
+    # the resolved label would freeze the guide into the language the test
+    # happened to run in.
+    Field = Struct.new(:locator) do
+      def to_howdoc_text(locale)
+        Narrator.field_label(locator, locale:)
+      end
+    end
 
     class << self
       # Keys that were asked for but not translated, reported once at the end of
-      # a run rather than silently producing a guide with holes in it.
+      # a run rather than silently producing a guide with holes in it. A key is
+      # missing in a particular language, so the language is part of it.
       def missing_keys
         @missing_keys ||= []
       end
@@ -21,16 +39,39 @@ module Howdoc
         @missing_keys = []
       end
 
+      # Wraps a form field locator so it is named in the language of whichever
+      # edition is being written, rather than in the one the test ran in.
+      def field(locator)
+        Field.new(locator)
+      end
+
       def call(action, locale:, **payload)
-        key = "#{SCOPE}.#{action}"
-        text = I18n.t(key, locale:, default: nil, **escape(payload))
+        sentence = lookup(ACTIONS, action, locale:)
 
-        if text.nil?
-          missing_keys << key unless missing_keys.include?(key)
+        if sentence.nil?
+          record_missing(action_key(action), locale)
           return nil
         end
 
-        text
+        values = resolve(payload, locale)
+        values.empty? ? sentence : I18n.interpolate(sentence, values)
+      end
+
+      # Whether any of the languages a guide is published in has a sentence for
+      # this action. A step no language can say anything about is not recorded
+      # at all -- it would otherwise leave a numbered instruction with nothing
+      # in it, or an illustration of nothing.
+      def known?(action, locales)
+        return false if action.nil?
+
+        return true if locales.any? { |locale| translated?(action, locale) }
+
+        locales.each { |locale| record_missing(action_key(action), locale) }
+        false
+      end
+
+      def translated?(action, locale)
+        !lookup(ACTIONS, action, locale:).nil?
       end
 
       # The label a reader would recognise for a form field.
@@ -41,10 +82,25 @@ module Howdoc
       def field_label(locator, locale:)
         return '' if locator.nil?
 
-        translated = I18n.t("howdoc.fields.#{locator}", locale:, default: nil)
-        return translated if translated
+        lookup(FIELDS, locator, locale:) || Howdoc.config.field_label.call(locator)
+      end
+
+      # A guide's own words -- its title, its introduction -- come from the test
+      # that recorded it and are therefore written in one language. Translating
+      # howdoc.documents.<permalink>.title gives the same guide a heading in
+      # another language without the test knowing there is another language.
+      def document_text(field, key:, locale:, default: nil)
+        return default if key.nil? || key.empty?
+
+        lookup(DOCUMENTS, key, field, locale:) || default
+      end
 
-        Howdoc.config.field_label.call(locator)
+      # The gem's own words -- the ones its templates print rather than the ones
+      # it narrates a step with. Looked up the safe way, so an application whose
+      # I18n cascades cannot answer an untranslated "howdoc.index.intro" with
+      # some unrelated top-level "intro" of its own.
+      def phrase(*path, locale:, default: nil)
+        lookup(*path, locale:) || default
       end
 
       # Rails names fields after the model that owns them, which is noise to
@@ -63,10 +119,56 @@ module Howdoc
 
       private
 
-      # Translations carry the markup, values do not. Escaping here means a
-      # label containing an angle bracket cannot break the page it lands on.
-      def escape(payload)
+      # Nothing here asks I18n for a leaf.
+      #
+      # How a key is resolved belongs to the application, and an application
+      # that has switched cascading on answers a missing
+      # "howdoc.documents.some_guide.title" with whatever unrelated top-level
+      # "title" it happens to have. A guide would then be headed with a word
+      # from somewhere else entirely. So the gem's own tree is fetched whole --
+      # it is always there, so nothing cascades past it -- and the leaf is dug
+      # out of the result, where a key that is missing is simply missing.
+      #
+      # An application's fallback chain is still honoured, because a sentence
+      # in the wrong language reads better than a numbered step with nothing
+      # in it.
+      def lookup(*path, locale:)
+        keys = path.map(&:to_sym)
+
+        fallback_chain(locale).each do |candidate|
+          tree = I18n.t(ROOT, locale: candidate, default: nil)
+          next unless tree.is_a?(Hash)
+
+          value = tree.dig(*keys)
+          return value if value.is_a?(String)
+        end
+
+        nil
+      end
+
+      def fallback_chain(locale)
+        return [locale] unless I18n.respond_to?(:fallbacks)
+
+        I18n.fallbacks[locale]
+      rescue StandardError
+        [locale]
+      end
+
+      def action_key(action)
+        "#{ROOT}.#{ACTIONS}.#{action}"
+      end
+
+      def record_missing(key, locale)
+        entry = "#{key} (#{locale})"
+        missing_keys << entry unless missing_keys.include?(entry)
+      end
+
+      # Values that only a language can settle are settled here, and then
+      # escaped like any other: translations carry the markup, values do not, so
+      # a label containing an angle bracket cannot break the page it lands on.
+      def resolve(payload, locale)
         payload.transform_values do |value|
+          value = value.to_howdoc_text(locale) if value.respond_to?(:to_howdoc_text)
           value.is_a?(String) || value.is_a?(Symbol) ? ERB::Util.html_escape(value.to_s) : value
         end
       end

data/lib/howdoc/navigation.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # The menu, and the links from one guide to the next.
+  #
+  # A guide is written the moment its test finishes, when no other guide is
+  # known yet -- tests run in forked workers and each one writes its own page --
+  # so a guide cannot draw a menu of guides. It leaves an empty <nav> instead,
+  # and this fills it in at the end of the run, when the index has just read
+  # every page back and knows what there is.
+  #
+  # Filling in rather than re-rendering: the steps a guide was made of are long
+  # gone by then, but its page is not, and this gem wrote that page. Running the
+  # pass again simply replaces what it wrote the last time.
+  #
+  # A template that carries no placeholder is left exactly as it is, so an
+  # application with its own page chrome loses nothing by not having one.
+  module Navigation
+    module_function
+
+    # Writes the menu and the pager into every guide. +by_locale+ is the sorted
+    # records the index was built from, so the menu lists the guides in the same
+    # order the index does.
+    def install(by_locale, root: Howdoc.config.root)
+      by_locale.each_value.flat_map do |records|
+        records.each_with_index.filter_map do |record, position|
+          write(record, records:, position:, by_locale:, root:)
+        end
+      end
+    end
+
+    def write(record, records:, position:, by_locale:, root:)
+      path = File.join(root, record.locale.to_s, record.filename)
+      return nil unless File.file?(path)
+
+      markup = File.read(path)
+      filled = fill(markup, :nav) { nav(record, records, by_locale) }
+      filled = fill(filled, :pager) { pager(record, records, position) }
+      return nil if filled == markup
+
+      File.write(path, filled)
+      path
+    end
+
+    # Stripped, so that filling a page in a second time leaves it exactly as the
+    # first time left it: the pass runs once per suite and again at the end of a
+    # run, and a page that grew a blank line each time would show up as changed
+    # in a repository for no reason at all.
+    def fill(markup, name)
+      markup.sub(placeholder(name)) { yield.strip }
+    end
+
+    def placeholder(name)
+      %r{<nav[^>]*data-howdoc-#{name}[^>]*>.*?</nav>}m
+    end
+
+    def nav(record, records, by_locale)
+      Templates.render(
+        'shared/html/nav.haml',
+        locale: record.locale, records:, current: record, config: Howdoc.config,
+        languages: languages(current_locale: record.locale, record:, by_locale:)
+      )
+    end
+
+    def pager(record, records, position)
+      Templates.render(
+        'shared/html/pager.haml',
+        locale: record.locale, config: Howdoc.config,
+        previous: (records[position - 1] if position.positive?),
+        next: records[position + 1]
+      )
+    end
+
+    # The same guide in the other languages the application publishes.
+    #
+    # Matched by identifier rather than by file name: a guide with a translated
+    # heading gets a translated file name, so "1.3" is the only thing the two
+    # pages are sure to have in common. A guide that was never written in the
+    # other language points at that language's index instead of nowhere.
+    def languages(current_locale:, by_locale:, record: nil)
+      ordered(by_locale.keys).map do |locale|
+        current = locale.to_s == current_locale.to_s
+
+        {
+          code: locale.to_s,
+          label: label(locale),
+          current:,
+          href: (destination(locale, record, by_locale) unless current)
+        }
+      end
+    end
+
+    def destination(locale, record, by_locale)
+      counterpart = record && counterpart(record, by_locale[locale] || [])
+
+      "../#{locale}/#{counterpart ? counterpart.filename : Registry::INDEX_FILENAME}"
+    end
+
+    def counterpart(record, records)
+      return records.find { |other| other.id == record.id } unless record.id.nil?
+
+      records.find { |other| other.permalink == record.permalink }
+    end
+
+    # A language names itself in its own language, which is how a reader who
+    # cannot read the current page still recognises the way out of it.
+    def label(locale)
+      Narrator.phrase(:languages, locale, locale:, default: locale.to_s.upcase)
+    end
+
+    def ordered(locales)
+      configured = Howdoc.config.locales&.map(&:to_s)
+      return locales.map(&:to_s).sort if configured.nil?
+
+      (configured & locales.map(&:to_s)) | locales.map(&:to_s).sort
+    end
+  end
+end

data/lib/howdoc/recorder.rb

@@ -37,16 +37,18 @@ module Howdoc
     end
 
     # Records one instruction. +action+ names an I18n key under howdoc.actions;
-    # the remaining keyword arguments are interpolated into it. Pass
-    # <tt>html:</tt> instead to supply already-rendered markup, for the rare
-    # step no sentence describes.
+    # the remaining keyword arguments are interpolated into it when the guide is
+    # written, once per language. Pass <tt>html:</tt> instead to supply
+    # already-rendered markup, for the rare step no sentence describes.
+    #
+    # Values that read differently in different languages must not be resolved
+    # here: pass Howdoc::Narrator.field(locator) and the label is settled by
+    # each edition as it is written.
     def record(action = nil, html: nil, arrival: false, nodoc: false, **payload)
       return nil if nodoc || !recording?
+      return nil if html.nil? && !Narrator.known?(action, current.locales)
 
-      markup = html || Narrator.call(action, locale: current.locale, **payload)
-      return nil if markup.nil?
-
-      current.new_step(html: markup, arrival:)
+      current.new_step(action:, payload:, html:, arrival:)
     end
 
     # Illustrates the step recorded most recently. Separate from +record+

data/lib/howdoc/registry.rb

@@ -80,13 +80,23 @@ module Howdoc
       Howdoc.config.locales.to_h { |locale| [locale.to_s, found.fetch(locale.to_s, [])] }
     end
 
-    # Builds the index for every locale that produced at least one guide.
+    # Builds the index for every locale that produced at least one guide, and
+    # then writes the menu into the guides themselves: they were written one at
+    # a time, before there was a menu to draw.
     def write_indexes(root = Howdoc.config.root)
       Templates.install_assets(File.join(root, 'assets')) if Howdoc.config.install_assets
 
-      by_locale(root).map do |locale, records|
-        Writers::Index.call(locale:, records: sort(records), root:)
+      catalogue = by_locale(root).transform_values { |records| sort(records) }
+
+      written = catalogue.map do |locale, records|
+        Writers::Index.call(
+          locale:, records:, root:,
+          languages: Navigation.languages(current_locale: locale, by_locale: catalogue)
+        )
       end
+
+      Navigation.install(catalogue, root:)
+      written
     end
 
     def sort(records)

data/lib/howdoc/step.rb

@@ -1,21 +1,55 @@
 # frozen_string_literal: true
 
 module Howdoc
-  # One numbered instruction in a guide: a sentence, optionally an illustration,
-  # and a flag for the steps that mark the reader's arrival on a new page.
+  # One numbered instruction in a guide: what happened, optionally an
+  # illustration of it, and a flag for the steps that mark the reader's arrival
+  # on a new page.
+  #
+  # What happened is kept as the action and the values it was recorded with,
+  # not as a finished sentence, because the same step is told in every language
+  # the guide is published in.
   class Step
-    attr_reader :number
+    # A step as one language tells it: the sentence composed, the illustration
+    # named as that language's guide refers to it. This is what a template is
+    # handed, so a template never has to know which language it is rendering.
+    Narrated = Struct.new(:number, :html, :screenshot, :arrival, keyword_init: true) do
+      def empty?
+        html.nil? && screenshot.nil?
+      end
+    end
+
+    attr_reader :number, :action, :payload
     attr_accessor :html, :screenshot, :arrival
 
-    def initialize(number:, html: nil, screenshot: nil, arrival: false)
+    def initialize(number:, action: nil, payload: {}, html: nil, screenshot: nil, arrival: false)
       @number = number
+      @action = action
+      @payload = payload
       @html = html
       @screenshot = screenshot
       @arrival = arrival
     end
 
     def empty?
-      html.nil? && screenshot.nil?
+      html.nil? && action.nil? && screenshot.nil?
+    end
+
+    # Markup a caller supplied stands in every language: it was written by the
+    # application, which knew what it was doing.
+    def html_in(locale)
+      return html unless html.nil?
+      return nil if action.nil?
+
+      Narrator.call(action, locale:, **payload)
+    end
+
+    def narrate(edition)
+      Narrated.new(
+        number:,
+        html: html_in(edition.locale),
+        screenshot: (edition.image_filename(number) if screenshot),
+        arrival:
+      )
     end
   end
 end

data/lib/howdoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Howdoc
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

data/lib/howdoc/writers.rb

@@ -28,28 +28,55 @@ module Howdoc
       Howdoc.config.formats.map { |format| fetch(format).call(document) }
     end
 
-    # Writes the illustrated guide a reader actually opens.
+    # Writes the illustrated guide a reader actually opens -- one page per
+    # language the guide is published in.
     class Html
       def self.call(document)
-        FileUtils.mkdir_p(document.dir)
+        document.editions.map { |edition| write(document, edition) }
+      end
+
+      def self.write(document, edition)
+        FileUtils.mkdir_p(edition.dir)
+        copy_screenshots(document, edition)
+
         markup = Templates.render(
           'document/html/layout.haml',
-          document:, config: Howdoc.config
+          document: edition, config: Howdoc.config
         )
-        File.write(document.path('html'), markup)
-        document.path('html')
+        File.write(edition.path('html'), markup)
+        edition.path('html')
+      end
+
+      # A picture of the application is the same picture whatever language the
+      # page around it is written in, so it is taken once, while the browser is
+      # still on the page, and copied to where each edition looks for it.
+      def self.copy_screenshots(document, edition)
+        return if edition.equal?(document.primary)
+
+        document.steps.each do |step|
+          next if step.screenshot.nil?
+
+          copy_screenshot(File.join(document.image_dir, step.screenshot), edition, step.number)
+        end
+      end
+
+      def self.copy_screenshot(source, edition, number)
+        return unless File.file?(source)
+
+        FileUtils.mkdir_p(edition.image_dir)
+        FileUtils.cp(source, File.join(edition.image_dir, edition.image_filename(number)))
       end
     end
 
     # Writes one index per locale, from the guides the run just produced.
     class Index
-      def self.call(locale:, records:, root: Howdoc.config.root)
+      def self.call(locale:, records:, root: Howdoc.config.root, languages: [])
         dir = File.join(root, locale.to_s)
         FileUtils.mkdir_p(dir)
 
         markup = Templates.render(
           'index/html/layout.haml',
-          locale:, records:, config: Howdoc.config
+          locale:, records:, languages:, config: Howdoc.config
         )
         path = File.join(dir, 'index.html')
         File.write(path, markup)

data/lib/howdoc.rb

@@ -7,11 +7,13 @@ require_relative 'howdoc/version'
 require_relative 'howdoc/configuration'
 require_relative 'howdoc/narrator'
 require_relative 'howdoc/step'
+require_relative 'howdoc/edition'
 require_relative 'howdoc/document'
 require_relative 'howdoc/screenshot'
 require_relative 'howdoc/recorder'
 require_relative 'howdoc/templates'
 require_relative 'howdoc/writers'
+require_relative 'howdoc/navigation'
 require_relative 'howdoc/registry'
 
 # Generates end-user documentation from Capybara system tests.
@@ -58,11 +60,36 @@ module Howdoc
     end
 
     # Begins a guide. Everything recorded until #finish belongs to it.
-    def start(id: nil, title: nil, locale: I18n.locale, permalink: nil, intro: nil)
+    #
+    # A test runs in one language; the guide it records is written in every
+    # language the application publishes, which is config.locales unless this
+    # call names them. Pass +locale:+ for the rare guide that belongs to one
+    # language only -- a page describing something only that language's users
+    # ever see.
+    def start(id: nil, title: nil, locale: nil, locales: nil, permalink: nil, intro: nil)
       return nil unless enabled?
-      return nil if title.to_s.strip.empty?
+      return nil if blank_title?(title)
 
-      Recorder.current = Document.new(id:, title:, locale:, permalink:, intro:)
+      Recorder.current = Document.new(
+        id:, title:, permalink:, intro:,
+        locales: document_locales(locale, locales)
+      )
+    end
+
+    # Which languages a guide is written in: what the caller asked for, else
+    # what the application publishes, else the language the suite is running
+    # in, which is all a single-language application ever needs.
+    def document_locales(locale, locales)
+      chosen = locales || locale || config.locales
+      chosen = I18n.locale if chosen.nil? || Array(chosen).empty?
+
+      Array(chosen).map(&:to_sym)
+    end
+
+    def blank_title?(title)
+      return title.values.all? { |value| blank_title?(value) } if title.is_a?(Hash)
+
+      title.to_s.strip.empty?
     end
 
     # Ends the guide and writes it out. Called even when the test failed, so a

data/templates/default/assets/howdoc.css

@@ -27,7 +27,6 @@ body.howdoc {
 
 .howdoc-document,
 .howdoc-index {
-  max-width: 52rem;
   margin: 0 auto;
   padding: 3rem 1.25rem 6rem;
 }
@@ -57,12 +56,6 @@ body.howdoc {
   padding-left: 0.25rem;
 }
 
-.howdoc-step.howdoc-arrival {
-  border-left: 3px solid var(--howdoc-accent);
-  margin-left: -1rem;
-  padding-left: 1rem;
-}
-
 .howdoc-shot {
   display: block;
   max-width: 100%;
@@ -103,7 +96,114 @@ body.howdoc {
   text-decoration: underline;
 }
 
+/* The menu sits beside the page it belongs to, and above it when there is no
+   room beside. A guide written before the index pass has an empty menu, and an
+   empty menu is no menu at all. */
+.howdoc-nav:empty,
+.howdoc-pager:empty {
+  display: none;
+}
+
+.howdoc-nav {
+  padding: 1.5rem 1.25rem;
+  border-bottom: 1px solid var(--howdoc-rule);
+}
+
+@media (min-width: 60rem) {
+  body.howdoc {
+    display: grid;
+    grid-template-columns: 19rem minmax(0, 1fr);
+    align-items: start;
+  }
+
+  .howdoc-nav {
+    position: sticky;
+    top: 0;
+    max-height: 100vh;
+    overflow-y: auto;
+    padding: 2rem 1.25rem 3rem;
+    border-right: 1px solid var(--howdoc-rule);
+    border-bottom: 0;
+  }
+}
+
+.howdoc-nav-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.howdoc-nav-home {
+  color: var(--howdoc-fg);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.howdoc-languages {
+  display: flex;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-size: 0.85rem;
+}
+
+.howdoc-language a {
+  color: var(--howdoc-accent);
+  text-decoration: none;
+}
+
+.howdoc-language.howdoc-current {
+  color: var(--howdoc-muted);
+}
+
+.howdoc-toc-entry.howdoc-current > a {
+  color: var(--howdoc-fg);
+  font-weight: 600;
+}
+
+.howdoc-pager {
+  display: flex;
+  gap: 1rem;
+  margin-top: 3rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--howdoc-rule);
+}
+
+.howdoc-pager-link {
+  display: flex;
+  flex: 1 1 0;
+  flex-direction: column;
+  gap: 0.25rem;
+  padding: 0.9rem 1rem;
+  border: 1px solid var(--howdoc-rule);
+  border-radius: 8px;
+  text-decoration: none;
+}
+
+.howdoc-pager-next {
+  margin-left: auto;
+  text-align: right;
+}
+
+.howdoc-pager-label {
+  color: var(--howdoc-muted);
+  font-size: 0.8rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.howdoc-pager-heading {
+  color: var(--howdoc-accent);
+}
+
 @media print {
+  .howdoc-nav,
+  .howdoc-pager {
+    display: none;
+  }
+
   .howdoc-shot {
     box-shadow: none;
   }

data/templates/default/document/html/layout.haml

@@ -6,11 +6,16 @@
     %title= @document.heading
     %link{ rel: 'stylesheet', href: '../assets/howdoc.css' }
   %body.howdoc
+    -# Empty on purpose: the index pass writes the menu and the pager in here
+    -# once it knows what the other guides are. A page is a whole page either
+    -# way, so a guide opened straight from a link is never a dead end.
+    %nav.howdoc-nav{ data: { howdoc_nav: true } }
     %main.howdoc-document
       %h1= @document.heading
       - unless @document.intro.to_s.strip.empty?
         .howdoc-intro!= @document.intro
-      %p.howdoc-lede= I18n.t('howdoc.document.follow_steps', locale: @document.locale)
+      %p.howdoc-lede= Howdoc::Narrator.phrase(:document, :follow_steps, locale: @document.locale)
       %ol.howdoc-steps
         - @document.steps.reject(&:empty?).each do |step|
           != render('document/html/step.haml', step: step)
+      %nav.howdoc-pager{ data: { howdoc_pager: true } }

data/templates/default/index/html/layout.haml

@@ -3,20 +3,15 @@
   %head
     %meta{ charset: 'utf-8' }
     %meta{ name: 'viewport', content: 'width=device-width, initial-scale=1' }
-    %title= I18n.t('howdoc.index.title', locale: @locale)
+    %title= Howdoc::Narrator.phrase(:index, :title, locale: @locale)
     %link{ rel: 'stylesheet', href: '../assets/howdoc.css' }
   %body.howdoc
+    -# The index knows every guide already, so it draws the menu itself.
+    != render('shared/html/nav.haml', current: nil)
     %main.howdoc-index
-      %h1= I18n.t('howdoc.index.title', locale: @locale)
+      %h1= Howdoc::Narrator.phrase(:index, :title, locale: @locale)
+      - intro = Howdoc::Narrator.phrase(:index, :intro, locale: @locale)
+      - if intro
+        .howdoc-intro!= intro
       - if @records.empty?
-        %p= I18n.t('howdoc.index.empty', locale: @locale)
-      - else
-        %ul.howdoc-toc
-          - previous_group = nil
-          - @records.each do |record|
-            - group = @config.group_label.call(record)
-            - if group && group != previous_group
-              %li.howdoc-toc-group= group
-              - previous_group = group
-            %li.howdoc-toc-entry
-              %a{ href: "./#{record.filename}" }= record.heading
+        %p= Howdoc::Narrator.phrase(:index, :empty, locale: @locale)

data/templates/default/shared/html/nav.haml

@@ -0,0 +1,25 @@
+-# The menu every page carries. A guide cannot draw this when it is written --
+-# no other guide exists yet -- so a guide leaves the empty <nav> below and the
+-# index pass fills it in once every guide is on disk. The index renders it
+-# directly, because by then it knows.
+%nav.howdoc-nav{ data: { howdoc_nav: true } }
+  .howdoc-nav-head
+    %a.howdoc-nav-home{ href: './index.html' }= Howdoc::Narrator.phrase(:index, :title, locale: @locale)
+    - if @languages.size > 1
+      %ul.howdoc-languages
+        - @languages.each do |language|
+          %li.howdoc-language{ class: ('howdoc-current' if language[:current]) }
+            - if language[:href]
+              %a{ href: language[:href], lang: language[:code] }= language[:label]
+            - else
+              %span{ lang: language[:code] }= language[:label]
+  %ul.howdoc-toc
+    - previous_group = nil
+    - @records.each do |record|
+      - group = @config.group_label.call(record)
+      - if group && group != previous_group
+        %li.howdoc-toc-group= group
+        - previous_group = group
+      - current = @current && record.filename == @current.filename
+      %li.howdoc-toc-entry{ class: ('howdoc-current' if current) }
+        %a{ href: "./#{record.filename}", 'aria-current': (current ? 'page' : nil) }= record.heading

data/templates/default/shared/html/pager.haml

@@ -0,0 +1,11 @@
+-# Step-by-step guides are read in order, so each one says what comes next.
+-# Written by the same pass as the menu, for the same reason.
+%nav.howdoc-pager{ data: { howdoc_pager: true } }
+  - if @previous
+    %a.howdoc-pager-link.howdoc-pager-previous{ href: "./#{@previous.filename}", rel: 'prev' }
+      %span.howdoc-pager-label= Howdoc::Narrator.phrase(:pager, :previous, locale: @locale)
+      %span.howdoc-pager-heading= @previous.heading
+  - if @next
+    %a.howdoc-pager-link.howdoc-pager-next{ href: "./#{@next.filename}", rel: 'next' }
+      %span.howdoc-pager-label= Howdoc::Narrator.phrase(:pager, :next, locale: @locale)
+      %span.howdoc-pager-heading= @next.heading

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howdoc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Priit Tark
@@ -58,8 +58,10 @@ files:
 - lib/howdoc/capybara_actions.rb
 - lib/howdoc/configuration.rb
 - lib/howdoc/document.rb
+- lib/howdoc/edition.rb
 - lib/howdoc/minitest.rb
 - lib/howdoc/narrator.rb
+- lib/howdoc/navigation.rb
 - lib/howdoc/recorder.rb
 - lib/howdoc/registry.rb
 - lib/howdoc/screenshot.rb
@@ -72,6 +74,8 @@ files:
 - templates/default/document/html/layout.haml
 - templates/default/document/html/step.haml
 - templates/default/index/html/layout.haml
+- templates/default/shared/html/nav.haml
+- templates/default/shared/html/pager.haml
 homepage: https://github.com/priit/howdoc
 licenses:
 - MIT