Re: [docs] [PATCH] manuals: simplify colon usage

Re: [docs] [PATCH] manuals: simplify colon usage

[Michael Opdenacker]

On 4/15/21 6:09 PM, Michael Opdenacker wrote:
> - This replaces instances of ": ::" by "::", which
>   generates identical HTML output

I'll propose the same changes to the Bitbake manual :)

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] manuals: simplify colon usage

[Quentin Schulz]

Hi Michael,

On Thu, Apr 15, 2021 at 06:14:33PM +0200, Michael Opdenacker wrote:
> 
> On 4/15/21 6:09 PM, Michael Opdenacker wrote:
> > - This replaces instances of ": ::" by "::", which
> >   generates identical HTML output
> 
> I'll propose the same changes to the Bitbake manual :)
> 

Great first patch... but still a few occurences are left :)

It'd be awesome if you could follow up with another patch fixing
`:<newline>::`, see:

➜  documentation git:(master) ✗ ag -Rc ":\n\s*::"
overview-manual/development-environment.rst:2
dev-manual/start.rst:10
dev-manual/qemu.rst:8
dev-manual/common-tasks.rst:340
0001-docs-fix-missing-and-surrounding-references-from-pok.patch:10
sdk-manual/appendix-customizing.rst:9
overview-manual/concepts.rst:17
sdk-manual/using.rst:2
sdk-manual/extensible.rst:27
sdk-manual/working-projects.rst:20
ref-manual/variables.rst:283
ref-manual/migration-2.1.rst:3
ref-manual/terms.rst:1
ref-manual/migration-1.3.rst:1
ref-manual/structure.rst:6
ref-manual/images.rst:1
ref-manual/migration-2.0.rst:3
ref-manual/migration-2.2.rst:4
ref-manual/migration-3.1.rst:1
ref-manual/features.rst:1
ref-manual/migration-2.5.rst:2
ref-manual/migration-1.7.rst:2
ref-manual/kickstart.rst:2
ref-manual/faq.rst:4
ref-manual/migration-2.3.rst:5
ref-manual/tasks.rst:16
ref-manual/migration-1.4.rst:2
ref-manual/migration-1.6.rst:2
ref-manual/devtool-reference.rst:17
ref-manual/system-requirements.rst:23
ref-manual/migration-2.6.rst:5
ref-manual/classes.rst:29
ref-manual/qa-checks.rst:3
kernel-dev/maint-appx.rst:5
kernel-dev/concepts-appx.rst:2
kernel-dev/advanced.rst:29
kernel-dev/faq.rst:2
kernel-dev/common.rst:75
sdk-manual/appendix-obtain.rst:10

You probably want to use `ag -Rc ":\s*::"` after this patch has been
applied to find all weird corner cases (like, a line ending with `: `.

Also, I think it is time to start a CONTRIBUTING file or whatever the
appropriate name for a file about guidelines would be.

At least, it would help us the day to remember the "rules" once we have
the time to create a linter :)

But not needed for this patch to be merged obviously.

Cheers,
Quentin
-- 
StreamUnlimited Engineering GmbH
High Tech Campus Vienna, Gutheil-Schoder-Gasse 10, 1100 Vienna, Austria
Fax: +43 1 667 20 02 4401
quentin.schulz@streamunlimited.com, www.streamunlimited.com

Re: [docs] [PATCH] manuals: simplify colon usage

[Quentin Schulz]

On Thu, Apr 15, 2021 at 06:14:33PM +0200, Michael Opdenacker wrote:
> 
> On 4/15/21 6:09 PM, Michael Opdenacker wrote:
> > - This replaces instances of ": ::" by "::", which
> >   generates identical HTML output
> 

Could you explain how you did the changes? I'm pretty sure you are not
crazy enough to do all those changes by hand :)

Just add the command you used when you use automation for things in the
docs.

I'm not sure I'd actually ask for a v2 just for that, so... up to you :)

Cheers,
Quentin

Re: [docs] [PATCH] manuals: simplify colon usage

[Michael Opdenacker]

Hi Quentin

On 4/15/21 6:55 PM, Quentin Schulz wrote:
> On Thu, Apr 15, 2021 at 06:14:33PM +0200, Michael Opdenacker wrote:
>> On 4/15/21 6:09 PM, Michael Opdenacker wrote:
>>> - This replaces instances of ": ::" by "::", which
>>>   generates identical HTML output
> Could you explain how you did the changes? I'm pretty sure you are not
> crazy enough to do all those changes by hand :)


Yes, I am!
I was using:

git grep -Ovi ": ::"

This takes at most a few minutes to go through all the matches and
substitute them all in the same way. Actually, when the number of
changes is still not prohibitive such as here, my personal preference is
to check each instance before making the substitution (just alternating
between "n" and "." in vim) to make sure it's not a special case that
would be different. Otherwise, I'd have to inspect each line in the
generated patch which would be an equivalent effort, wouldn't it?

By the way, which remaining occurrences did you find?

Many thanks for the feedback,

Michael.

-- 

Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] manuals: simplify colon usage

[Quentin Schulz]

On April 15, 2021 5:10:04 PM UTC, Michael Opdenacker <michael.opdenacker@bootlin.com> wrote:
>Hi Quentin
>
>On 4/15/21 6:55 PM, Quentin Schulz wrote:
>> On Thu, Apr 15, 2021 at 06:14:33PM +0200, Michael Opdenacker wrote:
>>> On 4/15/21 6:09 PM, Michael Opdenacker wrote:
>>>> - This replaces instances of ": ::" by "::", which
>>>>   generates identical HTML output
>> Could you explain how you did the changes? I'm pretty sure you are not
>> crazy enough to do all those changes by hand :)
>
>
>Yes, I am!
>I was using:
>
>git grep -Ovi ": ::"
>
>This takes at most a few minutes to go through all the matches and
>substitute them all in the same way. Actually, when the number of
>changes is still not prohibitive such as here, my personal preference is
>to check each instance before making the substitution (just alternating
>between "n" and "." in vim) to make sure it's not a special case that
>would be different. Otherwise, I'd have to inspect each line in the
>generated patch which would be an equivalent effort, wouldn't it?
>

I would craft a command and then check the patch. But honestly, I don't know if it's any better. It's anyway time consuming.

>By the way, which remaining occurrences did you find?
>

I used ag -R ":\n\s*::" to find them. It'll probably work fine with git grep instead of ag. Or :%s/:\n\s*::/::/gc in vim I guess?

Cheers,
Quentin

Re: [docs] [PATCH] manuals: simplify colon usage

[Michael Opdenacker]

Hi Quentin,

On 4/15/21 8:14 PM, Quentin Schulz wrote:
>
> I used ag -R ":\n\s*::" to find them. 

Very cool! I didn't know this command but I won't forget it, thanks :)

Indeed, I'll add another patch fixing those, which are equivalent, but
not looking as bad as ": ::" on the same line.

I'll keep this for tomorrow ;), and will update my (so far private)
bitbake changes too.

Thanks again

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com