Re: Contributing to documentation

Re: Contributing to documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2730 bytes --]

[CC += linux-man@]

Hi rajesh,

On Fri, Dec 22, 2023 at 02:27:21PM +0530, rajesh wrote:
> Hi Alejandor,
> 
> Thanks for the help so far. So I think I can contribute to two issues now.

Thanks a lot for helping with the bugzilla bugs!

> However going through the kernel patch videos, I am not sure how to
> apply the patches to man pages.

First of all, you should clone the git repository, and cd(1) into it:

	$ git clone https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
	$ cd man-pages/

I assume you know how to use git, do you?  After cloning that repo,
you'll be able to read the README and CONTRIBUTING files.

Assuming you want to modify mount_namespaces(7), you should edit the
file <./man7/mount_namespaces.7>.

Assuming you know how to use the basics of git(1) to do a commit, then
you can produce a patch with

	$ git format-patch -1 HEAD -o ./patches/ \
	                   --to alx@kernel.org \
	                   --cc linux-man@vger.kernel.org

This will produce a file inside the ./patches/ directory, which you need
to send via email.  You can send it with any mail client to start, and
I can help you refine that.  Most mail clients mess the patch (they
usually mess the whitespace), so it can't be applied with git(1), so you
can configure git-send-email(1) to send it, which will respect the
patch.  mutt(1) or neomutt(1) will by default also respect it, but
git-send-email(1) is probably easier to configure for a start.  Check
this:
<https://git-scm.com/docs/git-send-email#_use_gmail_as_the_smtp_server>


> Attachment is a no no.

What do you mean?  I can accept attachments if you want to send a patch
as an attachment.

> I went through many links but not clear on what's process for patching
> man pages.

Here's the contributing guide we have:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING>

Although you may want to ask for clarification on some things that are
not specified there.

> Can you point me to some link or share some notes please?  I have
> setup git, mutt, and have downloaded the latest stable kernel version.

The Linux man-pages project is different from the Linux kernel project,
and the code is in different repositories.  You don't need the kernel
for contributing to the manual pages.  The guidelines for contributing
are mostly the same, though.

I've CCed the <linux-man@vger.kernel.org> mailing list, to which all
contributions to the project should be sent, as per the contributing
guide I've linked above.

> Kind regards,
> Rajesh

Have a lovely day,
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Contributing to documentation

[rajesh]

Thanks, I'll check them out Alejandro. Yes I m ok with git (but
looking forward to learn more)

I also made a comment on https://bugzilla.kernel.org/show_bug.cgi?id=218266

Does my comment looks ok? The language, code etc,.? If it's ok then
putting this code in shutdown makes sense?

Thank you and happy holidays.

On Fri, 22 Dec 2023 at 16:17, Alejandro Colomar <alx@kernel.org> wrote:
>
> [CC += linux-man@]
>
> Hi rajesh,
>
> On Fri, Dec 22, 2023 at 02:27:21PM +0530, rajesh wrote:
> > Hi Alejandor,
> >
> > Thanks for the help so far. So I think I can contribute to two issues now.
>
> Thanks a lot for helping with the bugzilla bugs!
>
> > However going through the kernel patch videos, I am not sure how to
> > apply the patches to man pages.
>
> First of all, you should clone the git repository, and cd(1) into it:
>
>         $ git clone https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
>         $ cd man-pages/
>
> I assume you know how to use git, do you?  After cloning that repo,
> you'll be able to read the README and CONTRIBUTING files.
>
> Assuming you want to modify mount_namespaces(7), you should edit the
> file <./man7/mount_namespaces.7>.
>
> Assuming you know how to use the basics of git(1) to do a commit, then
> you can produce a patch with
>
>         $ git format-patch -1 HEAD -o ./patches/ \
>                            --to alx@kernel.org \
>                            --cc linux-man@vger.kernel.org
>
> This will produce a file inside the ./patches/ directory, which you need
> to send via email.  You can send it with any mail client to start, and
> I can help you refine that.  Most mail clients mess the patch (they
> usually mess the whitespace), so it can't be applied with git(1), so you
> can configure git-send-email(1) to send it, which will respect the
> patch.  mutt(1) or neomutt(1) will by default also respect it, but
> git-send-email(1) is probably easier to configure for a start.  Check
> this:
> <https://git-scm.com/docs/git-send-email#_use_gmail_as_the_smtp_server>
>
>
> > Attachment is a no no.
>
> What do you mean?  I can accept attachments if you want to send a patch
> as an attachment.
>
> > I went through many links but not clear on what's process for patching
> > man pages.
>
> Here's the contributing guide we have:
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING>
>
> Although you may want to ask for clarification on some things that are
> not specified there.
>
> > Can you point me to some link or share some notes please?  I have
> > setup git, mutt, and have downloaded the latest stable kernel version.
>
> The Linux man-pages project is different from the Linux kernel project,
> and the code is in different repositories.  You don't need the kernel
> for contributing to the manual pages.  The guidelines for contributing
> are mostly the same, though.
>
> I've CCed the <linux-man@vger.kernel.org> mailing list, to which all
> contributions to the project should be sent, as per the contributing
> guide I've linked above.
>
> > Kind regards,
> > Rajesh
>
> Have a lovely day,
> Alex
>
> --
> <https://www.alejandro-colomar.es/>
> Looking for a remote C programming job at the moment.

Re: Contributing to documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 881 bytes --]

Hi rajesh,

On Fri, Dec 22, 2023 at 07:40:19PM +0530, rajesh wrote:
> Thanks, I'll check them out Alejandro. Yes I m ok with git (but
> looking forward to learn more)

Ok.

> I also made a comment on https://bugzilla.kernel.org/show_bug.cgi?id=218266
> 
> Does my comment looks ok? The language,

Yes, the language looks good.

> code etc,.? If it's ok then
> putting this code in shutdown makes sense?

That code is useful for debugging with something short, but normally you
shouldn't call printf(3) from a signal handler.
<https://stackoverflow.com/questions/16891019/how-to-avoid-using-printf-in-a-signal-handler>

I can't give any other response without actually investigating myself,
since I don't use signal handlers often.

Have a lovely day,
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Contributing to documentation

[rajesh]

That code is useful for debugging with something short, but normally you
shouldn't call printf(3) from a signal handler.

Yes, it makes sense. I agree about no printfs in signal handler. But
this is a demo to prove that SIGTERM is called and put an entry to
prove the point.

Also so we leave this as a comment and no need to update shutdown man
pages then?
Sorry to bug just trying to understand the process more : )

On Fri, 22 Dec 2023 at 19:50, Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi rajesh,
>
> On Fri, Dec 22, 2023 at 07:40:19PM +0530, rajesh wrote:
> > Thanks, I'll check them out Alejandro. Yes I m ok with git (but
> > looking forward to learn more)
>
> Ok.
>
> > I also made a comment on https://bugzilla.kernel.org/show_bug.cgi?id=218266
> >
> > Does my comment looks ok? The language,
>
> Yes, the language looks good.
>
> > code etc,.? If it's ok then
> > putting this code in shutdown makes sense?
>
> That code is useful for debugging with something short, but normally you
> shouldn't call printf(3) from a signal handler.
> <https://stackoverflow.com/questions/16891019/how-to-avoid-using-printf-in-a-signal-handler>
>
> I can't give any other response without actually investigating myself,
> since I don't use signal handlers often.
>
> Have a lovely day,
> Alex
>
> --
> <https://www.alejandro-colomar.es/>
> Looking for a remote C programming job at the moment.

Re: Contributing to documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 691 bytes --]

On Fri, Dec 22, 2023 at 08:38:43PM +0530, rajesh wrote:
> That code is useful for debugging with something short, but normally you
> shouldn't call printf(3) from a signal handler.
> 
> Yes, it makes sense. I agree about no printfs in signal handler. But
> this is a demo to prove that SIGTERM is called and put an entry to
> prove the point.
> 
> Also so we leave this as a comment and no need to update shutdown man
> pages then?

For now I think there's nothing to update, right.

> Sorry to bug just trying to understand the process more : )

No problem.

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]