Merge pull request #14160 from overleaf/ds-missing-package-errors

Adding improved user facing messages for missing packages

GitOrigin-RevId: d1ad4111b5f2c3596ee88ef69dab8094df065ee0

services/web/frontend/js/ide/human-readable-logs/HumanReadableLogsHints.js

@@ -1,5 +1,8 @@
 import PropTypes from 'prop-types'
-import packageSuggestions from './HumanReadableLogsPackageSuggestions'
+import {
+  packageSuggestionsForCommands,
+  packageSuggestionsForEnvironments,
+} from './HumanReadableLogsPackageSuggestions'
 
 function WikiLink({ url, children }) {
   if (window.wikiEnabled) {
@@ -162,22 +165,25 @@ const hints = {
     ),
   },
   hint_undefined_control_sequence: {
-    extraInfoURL:
-      'https://www.overleaf.com/learn/Errors/Undefined_control_sequence',
     formattedContent: details => {
-      if (details?.length && packageSuggestions.has(details[0])) {
+      if (details?.length && packageSuggestionsForCommands.has(details[0])) {
         const command = details[0]
-        const suggestion = packageSuggestions.get(command)
+        const suggestion = packageSuggestionsForCommands.get(command)
         return (
           <>
-            Undefined control sequence. You have used the command{' '}
-            <code>{command}</code>, which is part of the{' '}
-            <code>{suggestion.name}</code> package. Make sure to include the
-            package in your{' '}
-            <WikiLink url="https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes#The_preamble_of_a_document">
-              preamble
-            </WikiLink>{' '}
-            using <code>{suggestion.command}</code>.
+            <p>
+              We think you’ve got a missing package! The <code>{command}</code>{' '}
+              command won't work unless you include
+              <code>{suggestion.command}</code> in your{' '}
+              <WikiLink url="https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes#The_preamble_of_a_document">
+                document preamble
+              </WikiLink>
+              .{' '}
+              <WikiLink url="https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes#Finding_and_using_LaTeX_packages">
+                Learn more about packages
+              </WikiLink>
+              .
+            </p>
           </>
         )
       }
@@ -188,6 +194,61 @@ const hints = {
           a package, make sure you have included the package in your preamble
           using <code>\usepackage</code>
           {'{...}'}.
+          <div className="log-entry-content-link">
+            <a
+              href="https://www.overleaf.com/learn/Errors/Undefined_control_sequence"
+              target="_blank"
+              rel="noopener"
+            >
+              Learn more
+            </a>
+          </div>
+        </>
+      )
+    },
+  },
+  hint_undefined_environment: {
+    formattedContent: details => {
+      if (
+        details?.length &&
+        packageSuggestionsForEnvironments.has(details[0])
+      ) {
+        const environment = details[0]
+        const suggestion = packageSuggestionsForEnvironments.get(environment)
+        return (
+          <>
+            <p>
+              We think you’ve got a missing package! The{' '}
+              <code>{environment}</code> environment won't work unless you
+              include <code>{suggestion.command}</code> in your{' '}
+              <WikiLink url="https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes#The_preamble_of_a_document">
+                document preamble
+              </WikiLink>
+              .{' '}
+              <WikiLink url="https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes#Finding_and_using_LaTeX_packages">
+                Learn more about packages
+              </WikiLink>
+              .
+            </p>
+          </>
+        )
+      }
+      return (
+        <>
+          You have created an environment (using \begin
+          {'{…}'} and \end
+          {'{…}'} commands) which is not recognized. Make sure you have included
+          the required package for that environment in your preamble, and that
+          the environment is spelled correctly.
+          <div className="log-entry-content-link">
+            <a
+              href="https://www.overleaf.com/learn/Errors%2FLaTeX%20Error%3A%20Environment%20XXX%20undefined"
+              target="_blank"
+              rel="noopener"
+            >
+              Learn more
+            </a>
+          </div>
         </>
       )
     },
@@ -339,19 +400,6 @@ const hints = {
       </>
     ),
   },
-  hint_environment_undefined: {
-    extraInfoURL:
-      'https://www.overleaf.com/learn/Errors%2FLaTeX%20Error%3A%20Environment%20XXX%20undefined',
-    formattedContent: () => (
-      <>
-        You have created an environment (using \begin
-        {'{…}'} and \end
-        {'{…}'} commands) which is not recognized. Make sure you have included
-        the required package for that environment in your preamble, and that the
-        environment is spelled correctly.
-      </>
-    ),
-  },
   hint_somethings_wrong_perhaps_a_missing_item: {
     extraInfoURL:
       'https://www.overleaf.com/learn/Errors/LaTeX_Error:_Something%27s_wrong--perhaps_a_missing_%5Citem',

services/web/frontend/js/ide/human-readable-logs/HumanReadableLogsPackageSuggestions.js

@@ -1,7 +1,46 @@
-const suggestions = [
+const commandSuggestions = [
   [
     '\\includegraphics',
     { name: 'graphicx', command: '\\usepackage{graphicx}' },
   ],
+  ['\\toprule', { name: 'booktabs', command: '\\usepackage{booktabs}' }],
+  ['\\midrule', { name: 'booktabs', command: '\\usepackage{booktabs}' }],
+  ['\\bottomrule', { name: 'booktabs', command: '\\usepackage{booktabs}' }],
+  ['\\cmidrule', { name: 'booktabs', command: '\\usepackage{booktabs}' }],
+  ['\\multirow', { name: 'multirow', command: '\\usepackage{multirow}' }],
+  ['\\justifying', { name: 'ragged2e', command: '\\usepackage{ragged2e}' }],
+  ['\\tag', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['\\notag', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['\\text', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['\\boldsymbol', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['\\eqref', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['\\iint', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['\\iiint', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['\\nmid', { name: 'amssymb', command: '\\usepackage{amssymb}' }],
+  ['\\varnothing', { name: 'amssymb', command: '\\usepackage{amssymb}' }],
+  ['\\Box', { name: 'amssymb', command: '\\usepackage{amssymb}' }],
+  ['\\citep', { name: 'natbib', command: '\\usepackage{natbib}' }],
+  ['\\citet', { name: 'natbib', command: '\\usepackage{natbib}' }],
+  ['\\url', { name: 'url', command: '\\usepackage{url}' }],
+  ['\\href', { name: 'hyperref', command: '\\usepackage{hyperref}' }],
+  ['\\texorpdfstring', { name: 'hyperref', command: '\\usepackage{hyperref}' }],
+  ['\\phantomsection', { name: 'hyperref', command: '\\usepackage{hyperref}' }],
 ]
-export default new Map(suggestions)
+
+const environmentSuggestions = [
+  ['justify', { name: 'ragged2e', command: '\\usepackage{ragged2e}' }],
+  ['align', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['align*', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['split', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['gather', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['cases', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['matrix', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['pmatrix', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['bmatrix', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+  ['subequations', { name: 'amsmath', command: '\\usepackage{amsmath}' }],
+]
+
+const packageSuggestionsForCommands = new Map(commandSuggestions)
+const packageSuggestionsForEnvironments = new Map(environmentSuggestions)
+
+export { packageSuggestionsForCommands, packageSuggestionsForEnvironments }

services/web/frontend/js/ide/human-readable-logs/HumanReadableLogsRules.js

@@ -1,5 +1,8 @@
 /* eslint-disable no-useless-escape */
-import packageSuggestions from './HumanReadableLogsPackageSuggestions'
+import {
+  packageSuggestionsForCommands,
+  packageSuggestionsForEnvironments,
+} from './HumanReadableLogsPackageSuggestions'
 
 const rules = [
   {
@@ -48,10 +51,34 @@ const rules = [
     contentRegex:
       /^(?:l\.[0-9]+|<(?:recently read|inserted text|to be read again)>)\s*(\\\S+)/,
     improvedTitle: (currentTitle, details) => {
-      if (details?.length && packageSuggestions.has(details[0])) {
+      if (details?.length && packageSuggestionsForCommands.has(details[0])) {
         const command = details[0]
-        const suggestion = packageSuggestions.get(command)
-        return `${suggestion.command} is missing.`
+        const suggestion = packageSuggestionsForCommands.get(command)
+        return (
+          <span>
+            Is <code>{suggestion.command}</code> missing?
+          </span>
+        )
+      }
+      return currentTitle
+    },
+  },
+  {
+    ruleId: 'hint_undefined_environment',
+    regexToMatch: /LaTeX Error: Environment .+ undefined/,
+    contentRegex: /\\begin\{(\S+)\}/,
+    improvedTitle: (currentTitle, details) => {
+      if (
+        details?.length &&
+        packageSuggestionsForEnvironments.has(details[0])
+      ) {
+        const environment = details[0]
+        const suggestion = packageSuggestionsForEnvironments.get(environment)
+        return (
+          <span>
+            Is <code>{suggestion.command}</code> missing?
+          </span>
+        )
       }
       return currentTitle
     },
@@ -108,10 +135,6 @@ const rules = [
     ruleId: 'hint_no_author_given',
     regexToMatch: /No \\author given/,
   },
-  {
-    ruleId: 'hint_environment_undefined',
-    regexToMatch: /LaTeX Error: Environment .+ undefined/,
-  },
   {
     ruleId: 'hint_somethings_wrong_perhaps_a_missing_item',
     regexToMatch: /LaTeX Error: Something's wrong--perhaps a missing \\item/,