[v2,1/2] cocci: add headings to and reword README

Commit Message

Glen Choo April 27, 2023, 10:22 p.m. UTC

From: Glen Choo <[e-mail]>

- Drop "examples" since we actually use the patches.
- Drop sentences that could be headings instead

Signed-off-by: Glen Choo <[e-mail]>
---
 contrib/coccinelle/README | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

Comments

Ævar Arnfjörð Bjarmason May 1, 2023, 10:53 a.m. UTC | #1

On Thu, Apr 27 2023, Glen Choo via GitGitGadget wrote:

Re subject: I don't per-se mind the "add headings" formatting change,
but doesn't it have headings already? I.e.:

> -Git-specific tips & things to know about how we run "spatch":
> +== Git-specific tips & things to know about how we run "spatch":
>  
>   * The "make coccicheck" will piggy-back on
>     "COMPUTE_HEADER_DEPENDENCIES". If you've built a given object file

I think it was clear before that that was a "heading", at least in the
sense that it summarized what the indented part that followed was
discussing.

I think what this is really doing is converting this part of the doc to
asciidoc, but is anything actually rendering it as asciidoc?

If we are converting it to asciidoc shouldn't the bullet-points be
un-indented too? (I'm not sure, but couldn't find a part of our build
that actually feeds this through asciidoc, so spot-checking that wasn't
trivial...)

Junio C Hamano May 1, 2023, 3:06 p.m. UTC | #2

Ævar Arnfjörð Bjarmason <[e-mail]> writes:

> On Thu, Apr 27 2023, Glen Choo via GitGitGadget wrote:
>
> Re subject: I don't per-se mind the "add headings" formatting change,
> but doesn't it have headings already? I.e.:
>
>> -Git-specific tips & things to know about how we run "spatch":
>> +== Git-specific tips & things to know about how we run "spatch":
>>  
>>   * The "make coccicheck" will piggy-back on
>>     "COMPUTE_HEADER_DEPENDENCIES". If you've built a given object file

I think "add headings" mostly refers to what the first hunk, that
is, the hunk before that one, did.  Giving the entire document the
title (while removing references to "examples").  As a side effect,
the existing two sections ("-Git-specific tips..." we see above is
the second one among them) are moved down in the section hierarchy;
in other words, I do not think the highlighted part of the patch in
your message is the primary change intended.

Felipe Contreras May 2, 2023, 7:29 p.m. UTC | #3

Ævar Arnfjörð Bjarmason wrote:
> On Thu, Apr 27 2023, Glen Choo via GitGitGadget wrote:
> 
> Re subject: I don't per-se mind the "add headings" formatting change,
> but doesn't it have headings already? I.e.:
> 
> > -Git-specific tips & things to know about how we run "spatch":
> > +== Git-specific tips & things to know about how we run "spatch":
> >  
> >   * The "make coccicheck" will piggy-back on
> >     "COMPUTE_HEADER_DEPENDENCIES". If you've built a given object file
> 
> I think it was clear before that that was a "heading", at least in the
> sense that it summarized what the indented part that followed was
> discussing.
> 
> I think what this is really doing is converting this part of the doc to
> asciidoc, but is anything actually rendering it as asciidoc?

Personally I write many documents in AsciiDoc format even if I'm not
using asciidoc, as I find them easier to read.

Moreover, one can always do `:set ft=asciidoc` in vim to see some syntax
colors for an easier read.

> If we are converting it to asciidoc shouldn't the bullet-points be
> un-indented too? (I'm not sure, but couldn't find a part of our build
> that actually feeds this through asciidoc, so spot-checking that wasn't
> trivial...)

You can just do `asciidoctor doc.txt` with any document and it will
generate an HTML page.

Felipe Contreras May 2, 2023, 7:30 p.m. UTC | #4

I fogot to mention:

Ævar Arnfjörð Bjarmason wrote:
> If we are converting it to asciidoc shouldn't the bullet-points be
> un-indented too?

I don't think that's necessary.

Glen Choo May 9, 2023, 5:54 p.m. UTC | #5

Ævar Arnfjörð Bjarmason <[e-mail]> writes:

> On Thu, Apr 27 2023, Glen Choo via GitGitGadget wrote:
>
> Re subject: I don't per-se mind the "add headings" formatting change,
> but doesn't it have headings already? I.e.:
>
>> -Git-specific tips & things to know about how we run "spatch":
>> +== Git-specific tips & things to know about how we run "spatch":
>>  
>>   * The "make coccicheck" will piggy-back on
>>     "COMPUTE_HEADER_DEPENDENCIES". If you've built a given object file
>
> I think it was clear before that that was a "heading", at least in the
> sense that it summarized what the indented part that followed was
> discussing.

As Junio guessed downthread, I was primarily aiming to heading-ify the
other parts of the doc.

> I think what this is really doing is converting this part of the doc to
> asciidoc, but is anything actually rendering it as asciidoc?

And as Felipe mentioned downthread, I chose to author it as asciidoc
because I also find structured docs easier to read, and asciidoc seems
to be the closest thing to a standardized format we have. You're right
that nothing renders this as asciidoc.

Thanks, all :)

> If we are converting it to asciidoc shouldn't the bullet-points be
> un-indented too? (I'm not sure, but couldn't find a part of our build
> that actually feeds this through asciidoc, so spot-checking that wasn't
> trivial...)

Thanks Felipe for checking.

Patch

diff --git a/contrib/coccinelle/README b/contrib/coccinelle/README
index d1daa1f6263..9b28ba1c57a 100644
--- a/contrib/coccinelle/README
+++ b/contrib/coccinelle/README
@@ -1,7 +1,9 @@ 
-This directory provides examples of Coccinelle (http://coccinelle.lip6.fr/)
-semantic patches that might be useful to developers.
+= coccinelle
 
-There are two types of semantic patches:
+This directory provides Coccinelle (http://coccinelle.lip6.fr/) semantic patches
+that might be useful to developers.
+
+==  Types of semantic patches
 
  * Using the semantic transformation to check for bad patterns in the code;
    The target 'make coccicheck' is designed to check for these patterns and
@@ -42,7 +44,7 @@  There are two types of semantic patches:
    This allows to expose plans of pending large scale refactorings without
    impacting the bad pattern checks.
 
-Git-specific tips & things to know about how we run "spatch":
+== Git-specific tips & things to know about how we run "spatch":
 
  * The "make coccicheck" will piggy-back on
    "COMPUTE_HEADER_DEPENDENCIES". If you've built a given object file