Am 10.05.2018 um 18:42 schrieb Mauro Carvalho Chehab [off-list ref]:

Em Thu, 10 May 2018 09:38:46 -0600
Jonathan Corbet [off-list ref] escreveu:

quoted

On Thu, 10 May 2018 11:21:13 -0300
Mauro Carvalho Chehab [off-list ref] wrote:

quoted

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@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html