Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Markus Heiser]

> Am 10.05.2018 um 18:42 schrieb Mauro Carvalho Chehab 
> :
> 
> Em Thu, 10 May 2018 09:38:46 -0600
> Jonathan Corbet  escreveu:
> 
>> On Thu, 10 May 2018 11:21:13 -0300
>> Mauro Carvalho Chehab  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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 18:52:20 +0200
Andrea Parri  escreveu:

> On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote:
> > On Thu, 10 May 2018 14:23:35 +0200
> > Andrea Parri  wrote:
> >   
> > > only
> > > remember that other people (including some developers running into the
> > > "disadventure" of opening an RST doc. from their preferred text editor
> > > and being brought to conclude:  "WTH!  I need to open a web browser, I
> > > guess...") _use_ such doc. and _do care_ about it, and that what might
> > > be an improvement for some people might look as "vandalizing" to others.  
> > 
> > If you have an example of a place where use of a web browser has been
> > made mandatory, please point it out.  Avoiding that was at the top of the
> > list of explicit requirements.  
> 
> That's all I need.
> 
> 
> >Surely an extra colon is not going to
> > force you to run screaming to the protective embrace of Firefox...?  
> 
> Let me put it in these terms: I believe that that extra colon (or the
> "diagram" keywork) is not going to improve/help my use of the doc. ;D

No, it won't improve, but, it won't make it harder for a human
to understand if a "diagram" or "::" is added at the description.

The thing is that we need something that works for the Kernel as
a hole, and not just on a few places.

On some subsystems, just a text is not good enough to describe
things. See, for example:
https://www.kernel.org/doc/html/latest/media/uapi/v4l/crop.html

https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-packed-rgb.html

https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-srggb10-ipu3.html
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html

Images, complex tables, etc are sometimes required to show some things.
Trying to explain just on text is harder to write, longer and worse
for readers. In the past, DocBook was used. ReST made very simple to
write documentation. From where I sit, I'm reviewing documentation
patches from a lot more people than the usage of a markup language.

As a bonus, we can now create cross-references for kernel-doc functions,
with is really great when reading documentation for complex hardware.

From where I sit at media, the subsystem documentation, if generated
in PDF, becomes a book with more than 1,100 pages, full of long tables,
images and graphs[1], covering uAPI, kAPI and driver-specific
documentation.

[1] https://linuxtv.org/downloads/v4l-dvb-apis-new/media.pdf

As on all subsystems, developers write documentation directly
at .rst or as kernel-doc comments. But for reading it, even developers
prefer to read the docs via the html (or pdf) output, as it better
shows tables and images. It is also faster to follow the dozen
thousands of links inside it.

The point is: we shouldn't enforce everyone to use our own view
about how to navigate through documentation. People are free to
use whatever improves their workflow.

Thanks,
Mauro
--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 13:42:58 -0300
Mauro Carvalho Chehab  escreveu:

> Em Thu, 10 May 2018 09:38:46 -0600
> Jonathan Corbet  escreveu:
> 
> > On Thu, 10 May 2018 11:21:13 -0300
> > Mauro Carvalho Chehab  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.

Btw, running this:

$ git grep -A2 "\*\s.*following.*(code|example|artwork|flow|diagram).*:$"

currently doesn't have a single match. 

If we force a two word combination, and an ending with ":" should
be enough to not having too much false positives.

Regards,
Mauro
--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Andrea Parri]

On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote:
> On Thu, 10 May 2018 14:23:35 +0200
> Andrea Parri  wrote:
> 
> > only
> > remember that other people (including some developers running into the
> > "disadventure" of opening an RST doc. from their preferred text editor
> > and being brought to conclude:  "WTH!  I need to open a web browser, I
> > guess...") _use_ such doc. and _do care_ about it, and that what might
> > be an improvement for some people might look as "vandalizing" to others.
> 
> If you have an example of a place where use of a web browser has been
> made mandatory, please point it out.  Avoiding that was at the top of the
> list of explicit requirements.

That's all I need.


>Surely an extra colon is not going to
> force you to run screaming to the protective embrace of Firefox...?

Let me put it in these terms: I believe that that extra colon (or the
"diagram" keywork) is not going to improve/help my use of the doc. ;D

  Andrea


> 
> Thanks,
> 
> 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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 09:38:46 -0600
Jonathan Corbet  escreveu:

> On Thu, 10 May 2018 11:21:13 -0300
> Mauro Carvalho Chehab  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.


Thanks,
Mauro
--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Thu, 10 May 2018 11:21:13 -0300
Mauro Carvalho Chehab  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...

Thanks,

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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 07:30:12 -0600
Jonathan Corbet  escreveu:

> On Thu, 10 May 2018 06:38:05 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > (Peter said):  
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.
> 
> FWIW, there's no problem with a sentence ending with a single colon.
> It's only an issue if you want to flag a special interpretation for the
> text that follows that sentence.  Just to be precise.
> 
> > Patches are welcome, although I don't see any easy way to solve it.  
> 
> I could envision some sort of heuristic that would recognize an indented
> block containing code.  Probably we could go simpler and force the
> "literal block" treatment for any indented block that lacks explicit
> enumeration markers.  So:
> 
>   this->would_be("a literal block");
> 
> but:
> 
>   - This would not be
> 
> Such a thing would likely be a bit fragile (people feel, rightly, that
> they can put anything into normal text) but it might just work well
> enough.  For best results, it should probably be done as part of Sphinx
> itself, rather than yet another ugly hack in the kerneldoc script.

I guess that it also won't work...

$ git grep -A2 "\*\s.*\s.*:$" -- $(git grep kernel-doc:: Documentation/|cut -d 
: -f 4-)

Present some matches that seem to be violating such hint.

drivers/edac/edac_device.h:/* The offset value can be:
drivers/edac/edac_device.h- *   -1 indicating no offset value
drivers/edac/edac_device.h- *   0 for zero-based block numbers

drivers/gpu/drm/drm_scdc_helper.c: *As per the spec:
drivers/gpu/drm/drm_scdc_helper.c- *TMDS clock rate for pixel clock 
< 340 MHz = 1x the character
drivers/gpu/drm/drm_scdc_helper.c- *rate = 1/10 pixel clock rate

I didn't actually check if those are part of a Kernel-doc markup, though,
but it shows that people sometimes don't add a "prepend" character to
a list.

In the specific case of errors, prepending with a "-" can be weird,
as it may lead ugly things like:

* - -1 indicating no offset value
* - 0 for zero-based block numbers

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.

> This particular problem may be solvable, and I'll look into it, but not
> right away.  The offline world is being rather insistently obnoxious
> these days...

Thanks,
Mauro

[PATCH] Mark a diagram at wait.h as such, using a code-block for it

Instead of explicitly using "::" to mark the diagram,
detect it based on code words inside the description.

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/include/linux/wait.h b/include/linux/wait.h
index d9f131ecf708..c360c5947374 100644
--- a/include/linux/wait.h
+++ b/include/linux/wait.h
@@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry 
*wq_entry, wait_queue_func_t f
  * lead to sporadic and non-obvious failure.
  *
  * Use either while holding wait_queue_head::lock or when used for wakeups
- * with an extra smp_mb() like:
+ * with an extra smp_mb() like on this diagram:
  *
  *  CPU0 - wakerCPU1 - waiter
  *
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0057d8eafcc1..1c69072997f8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -803,7 +803,12 @@ 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/) {
+   $in_literal = 1;
+   $litprefix = "";
+   $output .= highlight_block($block);
+   $block = ""
+   } elsif (($line =~ /$sphinx_literal/) || ($line =~ 
/$sphinx_cblock/)) {
$in_literal = 1;
$litprefix = "";
$output .= highlight_block($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

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Thu, 10 May 2018 07:30:12 -0600
Jonathan Corbet  wrote:

> > (Peter said):  
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.

*Sigh*.  Of course, Christoph said that, not Peter.  Time for more coffee.

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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Thu, 10 May 2018 06:38:05 -0300
Mauro Carvalho Chehab  wrote:

> (Peter said):
> > Independent of any philosophical discussion not allowing a setence to
> > end with a single ':' is completely idiotic.  Please fix the tooling
> > instead to allow it, as it is very important for being able to just
> > write understandable comments.  

FWIW, there's no problem with a sentence ending with a single colon.
It's only an issue if you want to flag a special interpretation for the
text that follows that sentence.  Just to be precise.

> Patches are welcome, although I don't see any easy way to solve it.

I could envision some sort of heuristic that would recognize an indented
block containing code.  Probably we could go simpler and force the
"literal block" treatment for any indented block that lacks explicit
enumeration markers.  So:

this->would_be("a literal block");

but:

  - This would not be

Such a thing would likely be a bit fragile (people feel, rightly, that
they can put anything into normal text) but it might just work well
enough.  For best results, it should probably be done as part of Sphinx
itself, rather than yet another ugly hack in the kerneldoc script.

This particular problem may be solvable, and I'll look into it, but not
right away.  The offline world is being rather insistently obnoxious
these days...

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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Thu, 10 May 2018 14:23:35 +0200
Andrea Parri  wrote:

> only
> remember that other people (including some developers running into the
> "disadventure" of opening an RST doc. from their preferred text editor
> and being brought to conclude:  "WTH!  I need to open a web browser, I
> guess...") _use_ such doc. and _do care_ about it, and that what might
> be an improvement for some people might look as "vandalizing" to others.

If you have an example of a place where use of a web browser has been
made mandatory, please point it out.  Avoiding that was at the top of the
list of explicit requirements.  Surely an extra colon is not going to
force you to run screaming to the protective embrace of Firefox...?

Thanks,

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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 14:20:36 +0200
Peter Zijlstra  escreveu:

> On Thu, May 10, 2018 at 06:38:05AM -0300, Mauro Carvalho Chehab wrote:
> > Em Thu, 10 May 2018 01:38:38 -0700
> > Christoph Hellwig  escreveu:
> >   
> > > >   * Use either while holding wait_queue_head::lock or when used for 
> > > > wakeups
> > > > - * with an extra smp_mb() like:
> > > > + * with an extra smp_mb() like::
> > > 
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.  
> 
> That is exactly my point; the whole rst stuff detracts from normal text.
> It makes both reading and writing harder than it needs to be.
> 
> > Patches are welcome, although I don't see any easy way to solve it.
> > 
> > In English, the common case is that a line with ends with a colon is
> > followed by a list. E. g.  
> 
> (google) Dictionary says:
> 
> "a punctuation mark (:) used to precede a list of items, a quotation, or
> an expansion or explanation."
> 
> An enumeration (list) is just one of many possible uses of the colon.

True, but the point is that whatever tool is used, it should be able
to uniquely unambiguously identify what it follows.

For example, it if is a list of items, it should keep parsing the
semantics markups inside it e. g. marking %FOO as a constant,
and bar() as a function, etc, following kernel-doc syntax. 

But, if it is a quote, a code example or an ascii artwork, it
should disable all such parsers, enclosing the result into a
literal block.

> > However, in this specific case, it is followed by an ascii artwork. 
> > The double colon is a notation that tells Sphinx to not parse the
> > lines at the next block, placing the contents of it inside a literal
> > block. It is used also when the next lines contain a code example,
> > in order to avoid parsing things like @, () and * inside the code 
> > block.
> > 
> > The kernel-doc tool might eventually have some parsing logic that
> > would replace something to a '::' before sending it to Sphinx.  
> 
> I think typically there will be an 'empty' line between the colon ending
> and the 'example/explanation'. This seems true for a number of comments
> I found in drm using the '::' nonsense.

Unfortunately, that's not true treewide. The presense/absense of a
blank line after a line ending with a colon doesn't indicate if the contents
below should be handled as a literal block or not[1].

[1] you can verify some use cases with:
$ git grep -A2 "\*.*\s.*:$" -- $(git grep kernel-doc:: 
Documentation/|cut -d : -f 4-)

> Simple regexes don't do multi-line patterns, but maybe the kerneldoc
> thing can parse it differently.

kernel-doc is a regex-based parser (and not an AI engine). It will do only
what it is programmed for, based on a clear regex-based semantics.

Independently on how easy/hard it would be to use a multi-line pattern
for this, what it is required is a clear non-hint based pattern that
will provide a match for a part of the tag that should be escaped
from normal parsing rules. The m/::$/ is a clear rule.

Do you have a proposal for some other rule? If so, I can see how
feasible is to add it there.

Thanks,
Mauro
--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Andrea Parri]

On Wed, May 09, 2018 at 08:45:18AM -0600, Jonathan Corbet wrote:
> On Wed, 9 May 2018 10:41:20 +0200
> Peter Zijlstra  wrote:
> 
> > > This is easily done by using "::" instead of just ":".  
> > 
> > And I'll voice my objection once again. This makes a regular comment
> > worse. This rst stuff is utter shit for making normal text files less
> > readable in your favourite text editor.
> > 
> > If this gets merged, I'll simply remove that spurious ':' the next time
> > I'm near that comment.
> 
> Seriously, Peter?
> 
> It's a simple colon.  It goes along with the /** marker for kerneldoc
> comments and the @ markers found within them, both of which you seem to
> have found a way to live with.
> 
> The RST work was discussed for a year before we even started.  It has
> brought in the efforts of a large number of developers, all of whom see
> the value in actually caring about our documentation and making it
> accessible to a much larger group of readers.  And it has all happened
> while preserving the primacy of the plain-text documentation.
> 
> You're not the only consumer of the docs.  You may not appreciate the
> improvements that have come, but others certainly do.  I do hope that you
> can find it in youself to avoid vandalizing things for everybody else ...?

You wrote it:  the fact that some people (including its developers) see
a value in the RST work or the fact that such work made the kernel doc.
accessible to a larger group of readers are not in question here;  only
remember that other people (including some developers running into the
"disadventure" of opening an RST doc. from their preferred text editor
and being brought to conclude:  "WTH!  I need to open a web browser, I
guess...") _use_ such doc. and _do care_ about it, and that what might
be an improvement for some people might look as "vandalizing" to others.

We're talking about readability/accessibility here, but I think similar
considerations apply to other aspects of the doc. such as availability/
completeness (yes, I did hear developers arguing "I won't write such a
doc., because...") and consistency (w.r.t. the doc. itself and sources).

  Andrea


> 
> Thanks,
> 
> 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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Peter Zijlstra]

On Thu, May 10, 2018 at 06:38:05AM -0300, Mauro Carvalho Chehab wrote:
> Em Thu, 10 May 2018 01:38:38 -0700
> Christoph Hellwig  escreveu:
> 
> > >   * Use either while holding wait_queue_head::lock or when used for 
> > > wakeups
> > > - * with an extra smp_mb() like:
> > > + * with an extra smp_mb() like::  
> > 
> > Independent of any philosophical discussion not allowing a setence to
> > end with a single ':' is completely idiotic.  Please fix the tooling
> > instead to allow it, as it is very important for being able to just
> > write understandable comments.

That is exactly my point; the whole rst stuff detracts from normal text.
It makes both reading and writing harder than it needs to be.

> Patches are welcome, although I don't see any easy way to solve it.
> 
> In English, the common case is that a line with ends with a colon is
> followed by a list. E. g.

(google) Dictionary says:

"a punctuation mark (:) used to precede a list of items, a quotation, or
an expansion or explanation."

An enumeration (list) is just one of many possible uses of the colon.

> However, in this specific case, it is followed by an ascii artwork. 
> The double colon is a notation that tells Sphinx to not parse the
> lines at the next block, placing the contents of it inside a literal
> block. It is used also when the next lines contain a code example,
> in order to avoid parsing things like @, () and * inside the code 
> block.
> 
> The kernel-doc tool might eventually have some parsing logic that
> would replace something to a '::' before sending it to Sphinx.

I think typically there will be an 'empty' line between the colon ending
and the 'example/explanation'. This seems true for a number of comments
I found in drm using the '::' nonsense.

Simple regexes don't do multi-line patterns, but maybe the kerneldoc
thing can parse it differently.
--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 01:38:38 -0700
Christoph Hellwig  escreveu:

> >   * Use either while holding wait_queue_head::lock or when used for wakeups
> > - * with an extra smp_mb() like:
> > + * with an extra smp_mb() like::  
> 
> Independent of any philosophical discussion not allowing a setence to
> end with a single ':' is completely idiotic.  Please fix the tooling
> instead to allow it, as it is very important for being able to just
> write understandable comments.

Patches are welcome, although I don't see any easy way to solve it.

In English, the common case is that a line with ends with a colon is
followed by a list. E. g.

foo:
  - bar1;
  - bar2.

However, in this specific case, it is followed by an ascii artwork. 
The double colon is a notation that tells Sphinx to not parse the
lines at the next block, placing the contents of it inside a literal
block. It is used also when the next lines contain a code example,
in order to avoid parsing things like @, () and * inside the code 
block.

The kernel-doc tool might eventually have some parsing logic that
would replace something to a '::' before sending it to Sphinx.
It could, for example, have a "hint" regex that would expect a
certain sequence of characters to be at the last line, like:

s/ascii\s+artwork.*:/ascii artwork.*::/
or
s/code\s+block.*:/code block.*::/

Then, change the kernel-doc comment to use it, like:

 * with an extra smp_mb() like shown at the following ascii artwork:

but IMHO, this is a lot worse than "::": it would be more intrusive
and more error-prune.

Thanks,
Mauro
--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Christoph Hellwig]

>   * Use either while holding wait_queue_head::lock or when used for wakeups
> - * with an extra smp_mb() like:
> + * with an extra smp_mb() like::

Independent of any philosophical discussion not allowing a setence to
end with a single ':' is completely idiotic.  Please fix the tooling
instead to allow it, as it is very important for being able to just
write understandable comments.
--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Peter Zijlstra]

On Wed, May 09, 2018 at 12:35:40PM -0600, Jonathan Corbet wrote:
> On Wed, 9 May 2018 17:20:26 +0200
> Peter Zijlstra  wrote:
> 
> > The whole rst wankery is detrimental to that interface in order to
> > pander to something else.. I don't see the value. I've objected before,
> > and I suppose I'll object again.
> 
> One person's wankery is another's integrated, browsable, and searchable
> documentation that shows some signs of having actually been thought about,
> I guess.

Browsable is what we have ctags/cscope for and searchable is git-grep, right?
--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Markus Heiser]

> Am 09.05.2018 um 20:35 schrieb Jonathan Corbet :
> 
>> Why should I care for people not using text editors to write code?

Eh? .. why must readers write code?

We have rules how to write kernel-doc markup since the beginning of the century.
If you do not want to contribute kernel-doc markups, then just leave it, change
your comment start-tag to

 /*

and feel free to type what ever you want. Sorry, but this discussion is 
superfluous.

-- Markus -




--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Wed, 9 May 2018 17:20:26 +0200
Peter Zijlstra  wrote:

> The whole rst wankery is detrimental to that interface in order to
> pander to something else.. I don't see the value. I've objected before,
> and I suppose I'll object again.

One person's wankery is another's integrated, browsable, and searchable
documentation that shows some signs of having actually been thought about,
I guess.

> > It's a simple colon.  It goes along with the /** marker for kerneldoc
> > comments and the @ markers found within them, both of which you seem to
> > have found a way to live with.  
> 
> Barely, and personally I tend to not bother with kerneldoc much. Most of
> the comments I write lack the extra *, and I note that the other fix to
> this problem it to drop that spurious * here as well.

Perhaps you'd like to post a patch removing the kerneldoc mechanism?  It
would make my life a lot easier...:)

> The @arg thing is okay, it clearly distinguishes arguments/variable
> names from regular text. But "::" is the C++ class member syntax, not
> the start of an English enumeration or the like.

Not sure what C++ has to do with anything, unless we want to bring in
$LANGUAGE_WE_DISRESPECT spuriously.  I'm sure it's the Perl
do-five-different-things-magically syntax too.  It's probably an entire
natural-language processing system in Haskell.  It also happens to be the
Sphinx "start literal block" syntax.

> > You're not the only consumer of the docs.  You may not appreciate the
> > improvements that have come, but others certainly do.  I do hope that you
> > can find it in youself to avoid vandalizing things for everybody else ...?  
> 
> Why should I care for people not using text editors to write code?

The set of "people using text editors to write code" is a superset
of the set containing only Peter Zijlstra.  Many of the people who have
used text editors to write the very code we all work on find a minimally
structured documentation system to be useful.  Out of respect for them, if
nothing else, I'll ask again, please, that you suffer the substantial
cognitive drain of skipping over an extra colon.

Thanks,

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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Peter Zijlstra]

On Wed, May 09, 2018 at 08:45:18AM -0600, Jonathan Corbet wrote:
> On Wed, 9 May 2018 10:41:20 +0200
> Peter Zijlstra  wrote:
> 
> > > This is easily done by using "::" instead of just ":".  
> > 
> > And I'll voice my objection once again. This makes a regular comment
> > worse. This rst stuff is utter shit for making normal text files less
> > readable in your favourite text editor.
> > 
> > If this gets merged, I'll simply remove that spurious ':' the next time
> > I'm near that comment.
> 
> Seriously, Peter?

Yep... it makes for pointlessly ugly text. And seeing that the only way
to write code is using text editors, the text editor is the primary
interface to our code.

The whole rst wankery is detrimental to that interface in order to
pander to something else.. I don't see the value. I've objected before,
and I suppose I'll object again.

> It's a simple colon.  It goes along with the /** marker for kerneldoc
> comments and the @ markers found within them, both of which you seem to
> have found a way to live with.

Barely, and personally I tend to not bother with kerneldoc much. Most of
the comments I write lack the extra *, and I note that the other fix to
this problem it to drop that spurious * here as well.

The @arg thing is okay, it clearly distinguishes arguments/variable
names from regular text. But "::" is the C++ class member syntax, not
the start of an English enumeration or the like.

> The RST work was discussed for a year before we even started.  It has
> brought in the efforts of a large number of developers, all of whom see
> the value in actually caring about our documentation and making it
> accessible to a much larger group of readers.  And it has all happened
> while preserving the primacy of the plain-text documentation.

Clearly I don't agree. It reads like crap. I suspect many of the other
options, which I suppose there were, were even worse. Doesn't mean rst
is any good.

> You're not the only consumer of the docs.  You may not appreciate the
> improvements that have come, but others certainly do.  I do hope that you
> can find it in youself to avoid vandalizing things for everybody else ...?

Why should I care for people not using text editors to write code?

--
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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Wed, 9 May 2018 10:41:20 +0200
Peter Zijlstra  wrote:

> > This is easily done by using "::" instead of just ":".  
> 
> And I'll voice my objection once again. This makes a regular comment
> worse. This rst stuff is utter shit for making normal text files less
> readable in your favourite text editor.
> 
> If this gets merged, I'll simply remove that spurious ':' the next time
> I'm near that comment.

Seriously, Peter?

It's a simple colon.  It goes along with the /** marker for kerneldoc
comments and the @ markers found within them, both of which you seem to
have found a way to live with.

The RST work was discussed for a year before we even started.  It has
brought in the efforts of a large number of developers, all of whom see
the value in actually caring about our documentation and making it
accessible to a much larger group of readers.  And it has all happened
while preserving the primacy of the plain-text documentation.

You're not the only consumer of the docs.  You may not appreciate the
improvements that have come, but others certainly do.  I do hope that you
can find it in youself to avoid vandalizing things for everybody else ...?

Thanks,

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: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Peter Zijlstra]

On Mon, May 07, 2018 at 06:35:49AM -0300, Mauro Carvalho Chehab wrote:
> The flow diagram should be inside a code-block to avoid those
> warnings:
>   ./include/linux/wait.h:110: WARNING: Block quote ends without a blank 
> line; unexpected unindent.
>   ./include/linux/wait.h:113: WARNING: Unexpected indentation.
>   ./include/linux/wait.h:115: WARNING: Block quote ends without a blank 
> line; unexpected unindent.
> 
> This is easily done by using "::" instead of just ":".

And I'll voice my objection once again. This makes a regular comment
worse. This rst stuff is utter shit for making normal text files less
readable in your favourite text editor.

If this gets merged, I'll simply remove that spurious ':' the next time
I'm near that comment.

> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  include/linux/wait.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/wait.h b/include/linux/wait.h
> index d9f131ecf708..d907ed761a7f 100644
> --- a/include/linux/wait.h
> +++ b/include/linux/wait.h
> @@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry 
> *wq_entry, wait_queue_func_t f
>   * lead to sporadic and non-obvious failure.
>   *
>   * Use either while holding wait_queue_head::lock or when used for wakeups
> - * with an extra smp_mb() like:
> + * with an extra smp_mb() like::
>   *
>   *  CPU0 - wakerCPU1 - waiter
>   *
> -- 
> 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

[PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

The flow diagram should be inside a code-block to avoid those
warnings:
./include/linux/wait.h:110: WARNING: Block quote ends without a blank 
line; unexpected unindent.
./include/linux/wait.h:113: WARNING: Unexpected indentation.
./include/linux/wait.h:115: WARNING: Block quote ends without a blank 
line; unexpected unindent.

This is easily done by using "::" instead of just ":".

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/wait.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/wait.h b/include/linux/wait.h
index d9f131ecf708..d907ed761a7f 100644
--- a/include/linux/wait.h
+++ b/include/linux/wait.h
@@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry 
*wq_entry, wait_queue_func_t f
  * lead to sporadic and non-obvious failure.
  *
  * Use either while holding wait_queue_head::lock or when used for wakeups
- * with an extra smp_mb() like:
+ * with an extra smp_mb() like::
  *
  *  CPU0 - wakerCPU1 - waiter
  *
-- 
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