Following a discussion with kirill and sthen, the latter sent some text
along the lines of "DIST_TUPLE probably should be documented there..."
and some text, which I bent, folded, spindled and mutilated into the
following. OKs or comments?
Index: guide.html
===================================================================
RCS file: /cvs/www/faq/ports/guide.html,v
diff -u -p -r1.115 guide.html
--- guide.html 2 Jul 2026 11:51:57 -0000 1.115
+++ guide.html 20 Sep 2026 16:08:13 -0000
@@ -181,6 +181,51 @@ You can check to see if you have filled
</ul>
<p>
+An alternative way of specifying downloads is <code>DIST_TUPLE</code>.
+This is useful in setting up downloads from the git code repositories
+listed under "sitecode" below.
+
+<p>
+The format of a <code>DIST_TUPLE</code> is five tab-separated fields:
+<p>
+<code>sitecode account repository version-or-hash target-dir</code>
+</p>
+<ul>
+<li><code>sitecode</code> is one of
+github, gitlab, codelab, codeberg, fdo, srht, kde, or gnome.
+/li>
+<li><code>account</code> is the repository owner's account name on that
site</li>
+<li><code>repository</code> is the name of the repository within that
user's account</li>
+<li><code>version-or-hash</code> is either a release or tag version
number, or else a
+full (40-character) git commit hash.</li>
+<li><code>target_dir</code> is usually "." for the current work directory,
+but may also be used to download the file into a subdirectory.</li>
+</ul>
+<p>
+For example:
+<p>
+<code>DIST_TUPLE = github someuser greatlib v4.0.4 .</code>
+</p>
+
+<p>
+Some projects require more than one distfile.
+If you need more than one entry in <code>DIST_TUPLE</code>,
+enter one per line with "+=" on all but the first.
+For GitHub, the use of the <code>GH_*</code> parameters is preferred
+over <code>DIST_TUPLE</code> for the "main" distfile;
+<code>DIST_TUPLE</code> can be used with any secondary distfiles.
+For the other sites listed, <code>DIST_TUPLE</code> can be used
+for all distfiles.
+
+<p>
+With some of the sites, <code>DIST_TUPLE</code> doesn't set
+<code>WRKDIST</code> properly.
+In this case <code>WRKDIST</code> needs to be overridden.
+A common example is gitlab when using commit hashes instead of version
numbers.
+Some sites may need the hash added to the dirname even for a tagged
release.
+Some trial and error, as well as examining working ports, may be needed.
+
+<p>
For more complex ports, you have more options and tools available to you:
<ul><li>
@@ -366,11 +411,11 @@ Try building the port with <code>make bu
If you're lucky, the port will go all the way through without errors.
<li>
-If it exits with an error, you will need to generate patches for your port.
+If it exits with an error, you will likely need to generate patches for
your port.
Figure out what needs to be changed and make a patch for it.
<li>
-the sequence to make a patch for a file is usually:
+The sequence to make a patch for a file is usually:
<ul><li>
<code>cd `make show=WRKSRC` ; cp foo/bar.c{,.orig.port}</code>
