andyholmes · andyholmes · Nov 8, 2025
diff --git a/.editorconfig b/.editorconfig
@@ -23,7 +23,7 @@ max_line_length = 80
 indent_size = 4
 indent_style = space
 
-[*.{css,toml,ui,xml,xml.in,yml}]
+[*.{css,page,toml,ui,xml,xml.in,yml}]
 indent_size = 2
 indent_style = space
 

diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -26,10 +26,20 @@ jobs:
           suite: test
           setup-args: |
             -Ddocumentation=true
+            -Dhelp=true
             -Dtests=true
           test-coverage: true
           lcov-include: '${{ github.workspace }}/src/*'
 
+      - name: Generate Assets
+        env:
+          WORKSPACE: ${{ github.workspace }}
+        run: |
+          mkdir -p _help
+          yelp-build html -o ${WORKSPACE}/_help \
+                          -x ${WORKSPACE}/help/valent-html.xsl \
+                          ${WORKSPACE}/help/C/
+
       - name: Coverage Report
         continue-on-error: true
         uses: JamesIves/github-pages-deploy-action@releases/v4
@@ -46,6 +56,14 @@ jobs:
           target-folder: documentation
           single-commit: true
 
+      - name: Help
+        continue-on-error: true
+        uses: JamesIves/github-pages-deploy-action@releases/v4
+        with:
+          folder: _help
+          target-folder: help
+          single-commit: true
+
   flatpak:
     name: Flatpak
     runs-on: ${{ matrix.arch == 'aarch64' && 'ubuntu-24.04-arm' || 'ubuntu-latest' }}

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -93,6 +93,7 @@ jobs:
         run: |
           meson setup --buildtype=release \
                       -Ddocumentation=true \
+                      -Dhelp=true \
                       _build
           meson compile -C _build
 
@@ -116,10 +117,12 @@ jobs:
         include:
           - suite: abidiff
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dplugins=false
           - suite: cppcheck
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dtests=true
       fail-fast: false
@@ -163,20 +166,24 @@ jobs:
         include:
           - suite: test
             setup-args: |
+              -Dhelp=false
               -Dtests=true
             test-args: |
               --repeat=3
           - suite: asan
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dtests=true
           - suite: tsan
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dtests=true
               -Dtests_libdir=/usr/tsan/lib64
           - suite: analyzer
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dtests=true
       fail-fast: false

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -38,9 +38,13 @@ This project does not yet use a translation service like Weblate or Crowdin. You
 should also expect translatable strings to change frequently until the project
 is more mature.
 
-To contribute a translation, open a pull request which adds your locale to the
-[`LINGUAS`][linguas] file and your translated `.po` file to the [`po/`][po_dir]
-directory.
+To contribute a translation of the application, open a pull request that adds
+your locale to [`po/LINGUAS`][linguas] and your translated `.po` file to
+`po/<locale>.po`.
+
+To contribute a translation of the user help, open a pull request that adds your
+locale to [`help/LINGUAS`][help-linguas] and your translated `.po` file to
+`help/<locale>/<locale>.po`.
 
 
 ## Contributing Code
@@ -121,6 +125,7 @@ already distributed under an acceptable open source license.
 [conventional-commits]: https://www.conventionalcommits.org
 [features]: https://github.com/andyholmes/valent/discussions/new?category=feature-request
 [issues]: https://github.com/andyholmes/valent/issues/new
+[help-linguas]: https://github.com/andyholmes/valent/blob/main/help/LINGUAS
 [linguas]: https://github.com/andyholmes/valent/blob/main/po/LINGUAS
 [po_dir]: https://github.com/andyholmes/valent/tree/main/po
 [gnome-coding-style]: https://developer.gnome.org/documentation/guidelines/programming/coding-style.html

diff --git a/LICENSES/CC-BY-SA-4.0.txt b/LICENSES/CC-BY-SA-4.0.txt
diff --git a/REUSE.toml b/REUSE.toml
@@ -15,6 +15,12 @@ precedence = "aggregate"
 SPDX-FileCopyrightText = "No rights reserved"
 SPDX-License-Identifier = "CC0-1.0"
 
+[[annotations]]
+path = ["help/*.page", "help/*.tmpl", "help/*/legal.xml"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "Andy Holmes <andrew.g.r.holmes@gmail.com>"
+SPDX-License-Identifier = "CC-BY-SA-4.0"
+
 [[annotations]]
 path = "src/plugins/findmyphone/data/alert.oga"
 precedence = "aggregate"

diff --git a/help/C/.yelp-tools.cfg b/help/C/.yelp-tools.cfg
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: CC-BY-SA-3.0
+# SPDX-FileCopyrightText: GNOME Documentation Project
+# SDPX-FileContributor: Andy Holmes <andrew.g.r.holmes@gmail.com>
+
+[namespaces]
+mal = http://projectmallard.org/1.0/
+xi = http://www.w3.org/2001/XInclude
+
+[check:hrefs]
+allow = https://kdeconnect.kde.org
+
+[check:validate]
+allow = http://www.w3.org/2005/11/its http://itstool.org/extensions/ http://www.w3.org/XML/1998/namespace http://www.w3.org/1999/xlink http://www.w3.org/XML/1998/namespace http://projectmallard.org/experimental/ui/
+
+[check:gnome-info-legal-xi]
+select = /mal:page/mal:info
+assert = xi:include[@href='legal.xml']
+message = Must include legal.xml
+xinclude = false
+
+[check:gnome-info-legal-no]
+select = /mal:page/mal:info
+assert = not(mal:license)
+message = Must not include license directly
+xinclude = false
+
+[check:gnome-desc]
+select = /mal:page/mal:info
+assert = normalize-space(mal:desc) != ''
+message = Must have non-empty desc
+
+[check:gnome-desc-punc]
+select = /mal:page/mal:info/mal:desc
+assert = substring(normalize-space(.), string-length(normalize-space(.))) = '.' or substring(normalize-space(.), string-length(normalize-space(.))) = '?'
+message = Desc must end with a period or question mark
+
+[check:gnome-no-desc-link]
+desc = Stop putting links in desc elements
+select = //mal:desc
+assert = not(mal:link)
+message = Stop putting links in desc elements
+
+[check:gnome-trail-title]
+skip = hardware-auth.page
+desc = Use a short title for link trails
+select = /mal:page[@type='guide']
+assert = string-length(mal:title) <= 20 or (mal:info/mal:title[@type='link' and @role='trail'] and string-length(mal:info/mal:title[@type='link' and @role='trail']) <= 20)
+message = Use a short title for link trails
+
+[check:gnome-no-ascii-quotes]
+select = //mal:*[not(ancestor-or-self::mal:cmd or ancestor-or-self::mal:code or ancestor-or-self::mal:comment or ancestor-or-self::mal:file or ancestor-or-self::mal:input or ancestor-or-self::mal:key or ancestor-or-self::mal:output or ancestor-or-self::mal:screen or ancestor-or-self::mal:screen or ancestor-or-self::mal:sys)]
+assert = not(contains(text(), "'") or contains(text(), '"'))
+message = Use ‘curly’ “quotes” instead of 'straight' "quotes"
+
diff --git a/help/C/device-name.page b/help/C/device-name.page
@@ -0,0 +1,63 @@
+<page xmlns="http://projectmallard.org/1.0/" version="1.1"
+      xmlns:its="http://www.w3.org/2005/11/its"
+      type="topic" style="task"
+      id="device-name">
+
+  <info>
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+    <credit type="author">
+      <name>Andy Holmes</name>
+      <email>andrew.g.r.holmes@gmail.com</email>
+    </credit>
+
+    <link type="guide" xref="index#getting-started"/>
+
+    <title type="text">Change the device name</title>
+    <desc>How to set the device name.</desc>
+  </info>
+
+  <title>Change the device name</title>
+  <p>
+    The device name is what other devices will see when connecting or pairing
+    with your device. This name will be appear in the device list in the
+    Android app an other <app>KDE Connect</app> clients.
+  </p>
+
+  <steps>
+    <item>
+      <p>
+        Open the main window.
+      </p>
+    </item>
+    <item>
+      <p>
+        Open the
+        <media style="button" its:translate="no" type="image" src="figures/open-menu-symbolic.svg">
+          <gui style="menu" its:translate="yes">Main Menu</gui>
+        </media>
+        menu and select <gui style="menuitem">Preferences</gui>.
+      </p>
+    </item>
+    <item>
+      <p>
+        Select the <gui style="input">Device Name</gui> entry.
+      </p>
+    </item>
+    <item>
+      <p>
+        Choose a new name for the device and press <key>Enter</key> or click the
+        <media style="button" its:translate="no" type="image" src="figures/entry-apply-symbolic.svg">
+          <gui style="button" its:translate="yes">Apply</gui>
+        </media>
+        button.
+      </p>
+    </item>
+  </steps>
+
+  <note style="tip">
+    <p>
+      It may take time for other devices to display the new name.
+    </p>
+  </note>
+</page>
+