> Am 10.05.2018 um 18:42 schrieb Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>: > > Em Thu, 10 May 2018 09:38:46 -0600 > Jonathan Corbet <corbet@xxxxxxx> escreveu: > >> On Thu, 10 May 2018 11:21:13 -0300 >> Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote: >> >>> The problem with a hint-based mechanism is that it will generate >>> false hints. If added, we may end by needing to add extra tags to >>> disable the hints mechanism where it gets wrong, or to periodically >>> do code changes at kernel-doc comments in order to make the hints >>> logic happy. >>> >>> So, IMO, we should provide non-hints based mechanism, like forcing the >>> string that prepends the colon to have a keyword that will make it to >>> parse the block as literal, where expressions like: >>> >>> See the code-block foo: >>> See the following code example: >>> See the following flow diagram: >>> See the following artwork: >>> >>> Is the best alternative to avoid "::", as on the enclosed patch. >> >> But this, too, is a hint-based mechanism. Thanks for the patches, I'll >> keep them around, but I would like an opportunity to try to do better >> before applying them. I fear that using magic words in this way will >> lead to a constant stream of surprises, and I'd like to avoid that if >> possible... > > Yes, it is still hint-based. A careful selection of the "magic spell > words/phrases" would minimize the risks of false positives, but it > could still lead into some unwanted surprises. > > IMO, "::" (or some other character combination that is not used > elsewhere) is still the safest option. Right, let's just stay with reST: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html We already have some special kernel-doc additions e.g. for highlighting, cross referencing and "DOC:": https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#how-to-format-kernel-doc-comments But we should not break with reST fundamentals. There are other plain text markups on the market, I would remember Markdown as one. They all come with markup rules (syntax), to make text parseable. Mauro brought the example with lists and colons. In ReST, the "::" introduce an indented literal block, which can be used for code block examples or a small ASCII art. FWIW: at docutils there is also a (slow ongoing) discussion about reST syntax alternatives http://docutils.sourceforge.net/docs/dev/rst/alternatives.html may the syntax discussion is better placed there? -- Markus -- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
