fix(parser): transform man pages (#349)

* fix(parser): transform man pages

* fixup!

Author: avivkeller

src/generators/metadata/utils/parse.mjs

@@ -35,6 +35,7 @@ export const parseApiDoc = ({ file, tree }) => {
     addYAMLMetadata,
     updateMarkdownLink,
     updateTypeReference,
+    updateUnixManualReference,
     updateLinkReference,
     addStabilityMetadata,
   } = createQueries();
@@ -127,6 +128,13 @@ export const parseApiDoc = ({ file, tree }) => {
       updateTypeReference(node, parent)
     );
 
+    // Visits all Unix manual references, and replaces them with links
+    visit(
+      subTree,
+      createQueries.UNIST.isTextWithUnixManual,
+      (node, _, parent) => updateUnixManualReference(node, parent)
+    );
+
     // Removes already parsed items from the subtree so that they aren't included in the final content
     remove(subTree, [createQueries.UNIST.isYamlNode]);
 

src/utils/parser/constants.mjs

@@ -3,6 +3,9 @@
 // This is the base URL of the MDN Web documentation
 export const DOC_MDN_BASE_URL = 'https://developer.mozilla.org/en-US/docs/Web/';
 
+// This is the base URL of the Man7 documentation
+export const DOC_MAN_BASE_URL = 'http://man7.org/linux/man-pages/man';
+
 // This is the base URL for the MDN JavaScript documentation
 export const DOC_MDN_BASE_URL_JS = `${DOC_MDN_BASE_URL}JavaScript/`;
 

src/utils/parser/index.mjs

@@ -10,6 +10,7 @@ import {
   DOC_TYPES_MAPPING_NODE_MODULES,
   DOC_TYPES_MAPPING_OTHER,
   DOC_TYPES_MAPPING_PRIMITIVES,
+  DOC_MAN_BASE_URL,
 } from './constants.mjs';
 import createQueries from '../queries/index.mjs';
 
@@ -44,6 +45,21 @@ export const normalizeYamlSyntax = yamlContent => {
     .replace(/^[\r\n]+|[\r\n]+$/g, ''); // Remove initial and final line breaks
 };
 
+/**
+ * @param {string} text The inner text
+ * @param {string} command The manual page
+ * @param {string} sectionNumber The manual section
+ * @param {string} sectionLetter The manual section number
+ */
+export const transformUnixManualToLink = (
+  text,
+  command,
+  sectionNumber,
+  sectionLetter = ''
+) => {
+  return `[\`${text}\`](${DOC_MAN_BASE_URL}${sectionNumber}/${command}.${sectionNumber}${sectionLetter}.html)`;
+};
+
 /**
  * This method replaces plain text Types within the Markdown content into Markdown links
  * that link to the actual relevant reference for such type (either internal or external link)

src/utils/queries/index.mjs

@@ -9,6 +9,7 @@ import {
   parseHeadingIntoMetadata,
   parseYAMLIntoMetadata,
   transformTypeToReferenceLink,
+  transformUnixManualToLink,
 } from '../parser/index.mjs';
 import { getRemark } from '../remark.mjs';
 import { transformNodesToString } from '../unist.mjs';
@@ -64,18 +65,17 @@ const createQueries = () => {
   };
 
   /**
-   * Updates a Markdown text containing an API type reference
-   * into a Markdown link referencing to the correct API docs
+   * Updates a reference
    *
-   * @param {import('@types/mdast').Text} node A Markdown link node
+   * @param {import('@types/mdast').Text} node The current node
    * @param {import('@types/mdast').Parent} parent The parent node
+   * @param {string|RegExp} query The search query
+   * @param {Function} transformer The function to transform the reference
+   *
    */
-  const updateTypeReference = (node, parent) => {
+  const updateReferences = (query, transformer, node, parent) => {
     const replacedTypes = node.value
-      .replace(
-        createQueries.QUERIES.normalizeTypes,
-        transformTypeToReferenceLink
-      )
+      .replace(query, transformer)
       // Remark doesn't handle leading / trailing spaces, so replace them with
       // HTML entities.
       .replace(/^\s/, ' ')
@@ -172,7 +172,20 @@ const createQueries = () => {
     addYAMLMetadata,
     setHeadingMetadata,
     updateMarkdownLink,
-    updateTypeReference,
+    /** @param {Array<import('@types/mdast').Node>} args */
+    updateTypeReference: (...args) =>
+      updateReferences(
+        createQueries.QUERIES.normalizeTypes,
+        transformTypeToReferenceLink,
+        ...args
+      ),
+    /** @param {Array<import('@types/mdast').Node>} args */
+    updateUnixManualReference: (...args) =>
+      updateReferences(
+        createQueries.QUERIES.unixManualPage,
+        transformUnixManualToLink,
+        ...args
+      ),
     updateLinkReference,
     addStabilityMetadata,
     updateStabilityPrefixToLink,
@@ -195,6 +208,8 @@ createQueries.QUERIES = {
   stabilityIndexPrefix: /Stability: ([0-5])/,
   // ReGeX for retrieving the inner content from a YAML block
   yamlInnerContent: /^<!--[ ]?(?:YAML([\s\S]*?)|([ \S]*?))?[ ]?-->/,
+  // ReGeX for finding references to Unix manuals
+  unixManualPage: /\b([a-z.]+)\((\d)([a-z]?)\)/g,
 };
 
 createQueries.UNIST = {
@@ -217,6 +232,12 @@ createQueries.UNIST = {
    */
   isTextWithType: ({ type, value }) =>
     type === 'text' && createQueries.QUERIES.normalizeTypes.test(value),
+  /**
+   * @param {import('@types/mdast').Text} text
+   * @returns {boolean}
+   */
+  isTextWithUnixManual: ({ type, value }) =>
+    type === 'text' && createQueries.QUERIES.unixManualPage.test(value),
   /**
    * @param {import('@types/mdast').Html} html
    * @returns {boolean}