From c6eb43be39ab76323824a4c40fd9100def580338 Mon Sep 17 00:00:00 2001 From: avivkeller Date: Thu, 10 Jul 2025 11:06:43 -0400 Subject: [PATCH 1/2] fix(parser): transform man pages --- src/generators/metadata/utils/parse.mjs | 8 +++++ src/utils/parser/constants.mjs | 3 ++ src/utils/parser/index.mjs | 16 ++++++++++ src/utils/queries/index.mjs | 39 +++++++++++++++++++------ 4 files changed, 57 insertions(+), 9 deletions(-) diff --git a/src/generators/metadata/utils/parse.mjs b/src/generators/metadata/utils/parse.mjs index d5b59059..eb8e6a62 100644 --- a/src/generators/metadata/utils/parse.mjs +++ b/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]); diff --git a/src/utils/parser/constants.mjs b/src/utils/parser/constants.mjs index 381b55d3..893a10d9 100644 --- a/src/utils/parser/constants.mjs +++ b/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/'; +// The 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/`; diff --git a/src/utils/parser/index.mjs b/src/utils/parser/index.mjs index b47cf7af..d7456a6a 100644 --- a/src/utils/parser/index.mjs +++ b/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) diff --git a/src/utils/queries/index.mjs b/src/utils/queries/index.mjs index 6f8875e6..df39751e 100644 --- a/src/utils/queries/index.mjs +++ b/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} args */ + updateTypeReference: (...args) => + updateReferences( + createQueries.QUERIES.normalizeTypes, + transformTypeToReferenceLink, + ...args + ), + /** @param {Array} 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: /^/, + // RegEX for finding references to Unix manuals + unixManualPage: /\b([a-z.]+)\((\d)([a-z]?)\)/gm, }; 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} From c36357cef00909accd5dd4ffea30519c7793f9d3 Mon Sep 17 00:00:00 2001 From: avivkeller Date: Thu, 10 Jul 2025 11:15:56 -0400 Subject: [PATCH 2/2] fixup! --- src/utils/parser/constants.mjs | 2 +- src/utils/parser/index.mjs | 2 +- src/utils/queries/index.mjs | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/utils/parser/constants.mjs b/src/utils/parser/constants.mjs index 893a10d9..fb6f221c 100644 --- a/src/utils/parser/constants.mjs +++ b/src/utils/parser/constants.mjs @@ -3,7 +3,7 @@ // This is the base URL of the MDN Web documentation export const DOC_MDN_BASE_URL = 'https://developer.mozilla.org/en-US/docs/Web/'; -// The is the base URL of the Man7 documentation +// 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 diff --git a/src/utils/parser/index.mjs b/src/utils/parser/index.mjs index d7456a6a..f964ba1f 100644 --- a/src/utils/parser/index.mjs +++ b/src/utils/parser/index.mjs @@ -55,7 +55,7 @@ export const transformUnixManualToLink = ( text, command, sectionNumber, - sectionLetter + sectionLetter = '' ) => { return `[\`${text}\`](${DOC_MAN_BASE_URL}${sectionNumber}/${command}.${sectionNumber}${sectionLetter}.html)`; }; diff --git a/src/utils/queries/index.mjs b/src/utils/queries/index.mjs index df39751e..1b168c61 100644 --- a/src/utils/queries/index.mjs +++ b/src/utils/queries/index.mjs @@ -208,8 +208,8 @@ createQueries.QUERIES = { stabilityIndexPrefix: /Stability: ([0-5])/, // ReGeX for retrieving the inner content from a YAML block yamlInnerContent: /^/, - // RegEX for finding references to Unix manuals - unixManualPage: /\b([a-z.]+)\((\d)([a-z]?)\)/gm, + // ReGeX for finding references to Unix manuals + unixManualPage: /\b([a-z.]+)\((\d)([a-z]?)\)/g, }; createQueries.UNIST = {