app/lib/dictionary-entries.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/components/dictionary-entry.tsx, app/db/dictionary.ts, app/lib/content-pages.mjs, app/lib/dictionary/compile.mjs, app/lib/dictionary/save.server.ts, app/lib/pages/page-json-ld.ts, app/lib/pages/save.server.ts.

Source

1/**
2 * How a dictionary entry reads on each surface. The entries themselves are files, content/dictionary/<key>.md
3 * (docs/DICTIONARY.md), compiled by app/lib/dictionary/compile.mjs and drawn from D1 (the dictionary_entries
4 * table) at request time; this module only turns one entry into the page's lead, the markdown twin's lead, the
5 * search record's sentences and the DefinedTerm JSON-LD, so people and machines read the same entry.
6 *
7 * Each name is a real English word most readers rarely meet, so the page first says what the word means, then
8 * what the software is. Sense 1 follows the dictionaries; sense 2 is the software, plain and factual, and
9 * carries the subject label "software." in italics, as a dictionary marks a specialised sense.
10 */
11
12/**
13 * An etymology is text with foreign words marked, so the page can set them in italics with their
14 * language and the twin can emphasise them: a string is plain text, a pair is [lang, word].
15 *
16 * @typedef {string | [string, string]} EtymologyPart
17 * @typedef {{
18 *   path: string,
19 *   term: string,
20 *   syllables: string,
21 *   ipa: string,
22 *   respelling: string,
23 *   partOfSpeech: string,
24 *   plural: string[] | null,
25 *   etymology: EtymologyPart[],
26 *   senses: [string, string],
27 *   senseLabels: [string | null, string | null],
28 *   audio: string,
29 * }} DictionaryEntry
30 */
31
32/** The subject label on each software sense (Dustin, 2026-09-28), set in italics before it. */
33export const SOFTWARE_LABEL = "software";
34
35/** @param {string | null | undefined} label */
36function labelPrefix(label) {
37  return label ? `${label}. ` : "";
38}
39
40/** @param {string} term */
41export function listenLabel(term) {
42  return `Listen to the pronunciation of ${term}`;
43}
44
45/** @param {DictionaryEntry} entry */
46function etymologyText(entry) {
47  return entry.etymology.map((part) => (typeof part === "string" ? part : part[1])).join("");
48}
49
50/**
51 * The entry as plain sentences, for the search record, where markup would be noise.
52 *
53 * @param {DictionaryEntry} entry
54 */
55export function dictionaryEntryText(entry) {
56  const plural = entry.plural ? `; plural ${entry.plural.join(" or ")}` : "";
57  return [
58    `${entry.term} (${entry.syllables}), ${entry.ipa}, ${entry.respelling}, ${entry.partOfSpeech}${plural}.`,
59    ...entry.senses.map((sense, i) => `${i + 1}. ${labelPrefix(entry.senseLabels[i])}${sense}`),
60    `Etymology: ${etymologyText(entry)}`,
61  ].join(" ");
62}
63
64/**
65 * The entry in the markdown twin, directly under the title, the same place the page shows it.
66 *
67 * @param {DictionaryEntry} entry
68 * @param {string} origin absolute origin for the audio link, so the twin read alone still resolves
69 */
70export function dictionaryEntryMarkdown(entry, origin = "") {
71  const plural = entry.plural ? `; plural ${entry.plural.map((form) => `*${form}*`).join(" or ")}` : "";
72  const etymology = entry.etymology.map((part) => (typeof part === "string" ? part : `*${part[1]}*`)).join("");
73  return [
74    `**${entry.syllables}** ${entry.ipa} (${entry.respelling}), *${entry.partOfSpeech}*${plural}. [Pronunciation audio](${origin}${entry.audio})`,
75    "",
76    ...entry.senses.map((sense, i) => {
77      const label = entry.senseLabels[i];
78      return `${i + 1}. ${label ? `*${label}.* ` : ""}${sense}`;
79    }),
80    "",
81    `Etymology: ${etymology}`,
82    "",
83  ].join("\n");
84}
85
86/**
87 * schema.org DefinedTerm: the name, sense 2 as the description (what the word means on this page),
88 * and the set every entry belongs to, which is the Software hub.
89 *
90 * @param {DictionaryEntry} entry
91 * @param {string} origin
92 */
93export function definedTermJsonLd(entry, origin) {
94  return {
95    "@context": "https://schema.org",
96    "@type": "DefinedTerm",
97    name: entry.term,
98    description: entry.senses[1],
99    url: `${origin}${entry.path}`,
100    inDefinedTermSet: {
101      "@type": "DefinedTermSet",
102      name: "Software names on dustinedwards.info",
103      url: `${origin}/software`,
104    },
105  };
106}