From 280025fc7e97ad943ed2938f6434cadf94bd635f Mon Sep 17 00:00:00 2001 From: Shawn Rutledge Date: Mon, 10 Feb 2025 14:25:01 +0100 Subject: [PATCH] doc: Add QTextDocument::MarkdownFeature docs Detailed docs were omitted before (and QTextMarkdownImporter::Feature is not public) because - "GitHub dialect" is a moving target (although we may have supported all known features when it was introduced). We should reserve the right to add to the feature set accordingly: so the numeric flags can be expected to change. - the writer mostly ignores the feature flags and writes back to GitHub dialect; only the front matter can be omitted that way - recognizing non-URL links seems fuzzy; md4c does it, so we allow that feature, but if it goes wrong it would be an md4c bug - hex flags look strange: in fact they come from https://github.com/mity/md4c/blob/master/src/md4c.h#L306 If we assume that they might change, it would be better not to document the numeric values in detail. But so far, md4c has never removed any, only added a few (and we don't yet support all the new ones). Change-Id: I6552da1226bf7ad6242432c1d5d3df9ec8f61d6f Pick-to: 6.9 Reviewed-by: David Boddie Reviewed-by: Tommi M. Tauriainen Reviewed-by: Paul Wicking --- src/gui/text/qtextdocument.cpp | 50 +++++++++++++++++++++++++++------- 1 file changed, 40 insertions(+), 10 deletions(-) diff --git a/src/gui/text/qtextdocument.cpp b/src/gui/text/qtextdocument.cpp index a7d3b8f1b19..e5f8ac3a733 100644 --- a/src/gui/text/qtextdocument.cpp +++ b/src/gui/text/qtextdocument.cpp @@ -3689,6 +3689,45 @@ QString QTextDocument::toMarkdown(QTextDocument::MarkdownFeatures features) cons } #endif +/*! + \since 5.14 + \enum QTextDocument::MarkdownFeature + + This enum selects the supported feature set when reading or writing Markdown. + + \value MarkdownNoHTML + Any HTML tags in the Markdown text will be discarded + \value MarkdownDialectCommonMark + Only the features standardized by \l {https://spec.commonmark.org/0.31.2/}{CommonMark} + \value MarkdownDialectGitHub + Most features from the + \l {https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax} + {GitHub dialect} + + Specifically, the supported subset of the GitHub dialect includes + everything from CommonMark, plus: + + \list + \li recognizing URLs, www and email addresses and turning them into links + \li strikethrough + \li underline (distinct from italics; in CommonMark it's the same) + \li tables + \li task lists + \li \l {QTextDocument::metaInformation()}{front matter} + \endlist + + "Front matter" is often metadata in YAML format. Qt does not currently + include a parser for that; but you may choose a third-party parser, call + QTextDocument::metaInformation() to get the whole block, and invoke your + own parser after Qt has parsed the Markdown file. + + \note The Markdown output from toMarkdown() currently may include GitHub + features even if you attempt to disable them by specifying another enum + value. This may be fixed in a future version of Qt. + + \sa toMarkdown(), setMarkdown() +*/ + /*! \since 5.14 Replaces the entire contents of the document with the given @@ -3706,16 +3745,7 @@ QString QTextDocument::toMarkdown(QTextDocument::MarkdownFeatures features) cons not supported. Some features of the parser can be enabled or disabled via the \a features - argument: - - \value MarkdownNoHTML - Any HTML tags in the Markdown text will be discarded - \value MarkdownDialectCommonMark - The parser supports only the features standardized by CommonMark - \value MarkdownDialectGitHub - The parser supports the GitHub dialect - - The default is \c MarkdownDialectGitHub. + argument. The default is \c MarkdownDialectGitHub. The undo/redo history is reset when this function is called. */