Re: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks
On Thu, 10 May 2018, Jonathan Corbetwrote: > On Thu, 10 May 2018 09:34:56 -0700 > Matthew Wilcox wrote: > >> I think this is a bit fragile. Why not just search for ':\n'? Is >> there ever a case where we want to write: >> >> /** >> * foo is a bar: >> * wibble >> */ >> and have wibble not be a code-block? > > Yeah, we might want to write something like: > > - Leading off a bulleted list > > 1) or a numbered list > > for example. That's why I was thinking of looking for explicit markers > for such lists. > > It'll take some playing around with to have a hope of getting right, > methinks. We had serious trouble with the old DocBook toolchain because the tool pipeline was so long, and each step had its own expectations and quirks. For example, remember the escaping needed for xml in kernel-doc? Or tmpl xml files being invalid xml because of the docproc directives? One of the big benefits of the current toolchain is minimizing the amount of special casing magic required. The more we add custom syntax sugar in kernel-doc, the more we run the risk of running into hard problems later on in the Sphinx phase. For example, our own syntax preventing the use of legitimate rst syntax. And now we get somewhat reasonable error messages from Sphinx when things go wrong; we didn't get that when the impedance mismatches caused issues with the old toolchain. They were hard to debug and mostly nobody even bothered. We should work to reduce the amount of special processing in kernel-doc, not the other way round. The use of "::" is a valid and arguably rather non-invasive rst token for indicating the following indented block is a literal block. Adding heuristics (especially ones based on English language magic words) will lead to bigger problems than it's trying to solve. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks
On Thu, 10 May 2018 09:34:56 -0700 Matthew Wilcoxwrote: > I think this is a bit fragile. Why not just search for ':\n'? Is > there ever a case where we want to write: > > /** > * foo is a bar: > * wibble > */ > and have wibble not be a code-block? Yeah, we might want to write something like: - Leading off a bulleted list 1) or a numbered list for example. That's why I was thinking of looking for explicit markers for such lists. It'll take some playing around with to have a hope of getting right, methinks. jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks
On Thu, May 10, 2018 at 10:38:16AM -0400, Mauro Carvalho Chehab wrote: > Comments that end with a comma and have certain keywords > should be presented as code-blocks I think this is a bit fragile. Why not just search for ':\n'? Is there ever a case where we want to write: /** * foo is a bar: * wibble */ and have wibble not be a code-block? -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks
Comments that end with a comma and have certain keywords should be presented as code-blocks Signed-off-by: Mauro Carvalho Chehab--- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0057d8eafcc1..8ce2d0f54369 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -803,7 +803,8 @@ sub output_highlight_rst { # if (! $in_literal) { $block .= $line . "\n"; - if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { + if (($block =~ s/(code|example|artwork|flow|diagram)([^\:]*:)\n/$1$2:\n/) || + ($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { $in_literal = 1; $litprefix = ""; $output .= highlight_block($block); -- 2.17.0 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html