This makes it easier to quote in emails.
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Contributing - instructions for contributing to the project
Synopsis
- Mailing list, patches, lint & check, style guide, bug reports, and notes
+ Mailing list, patches, lint & check, style guide, bug reports,
+ and notes
Description
Mailing list
- The main discussions regarding development of the project, patches,
- bugs, news, doubts, etc. happen on the mailing list. To send an email
- to the project, send it to Alejandro and CC the mailing list:
+ The main discussions regarding development of the project,
+ patches, bugs, news, doubts, etc. happen on the mailing list.
+ To send an email to the project, send it to Alejandro and CC the
+ mailing list:
To: Alejandro Colomar <alx@kernel.org>
Cc: <linux-man@vger.kernel.org>
- Please CC any relevant developers and mailing lists that may know about
- or be interested in the discussion. If your email discusses a feature
- or change, and you know which developers added the feature or made the
- change that your email discusses, please CC them on the email; with
- luck they may review and comment on it. If you don't know who the
- developers are, you may be able to discover that information from
- mailing list archives or from git(1) logs or logs in other version
- control systems. Obviously, if you are the developer of the feature
- being discussed in a man-pages email, please identify yourself as such.
+ Please CC any relevant developers and mailing lists that may know
+ about or be interested in the discussion. If your email
+ discusses a feature or change, and you know which developers
+ added the feature or made the change that your email discusses,
+ please CC them on the email; with luck they may review and
+ comment on it. If you don't know who the developers are, you may
+ be able to discover that information from mailing list archives
+ or from git(1) logs or logs in other version control systems.
+ Obviously, if you are the developer of the feature being
+ discussed in a man-pages email, please identify yourself as such.
Relevant mailing lists may include:
Cc: LKML <linux-kernel@vger.kernel.org>
Cc: Linux API <linux-api@vger.kernel.org>
Cc: Glibc <libc-alpha@sourceware.org>
- For other kernel mailing lists and maintainers, check the <MAINTAINERS>
- file in the Linux kernel repository.
+ For other kernel mailing lists and maintainers, check the
+ <MAINTAINERS> file in the Linux kernel repository.
Please don't send HTML email; it will be discarded by the list.
<https://marc.info/?l=linux-man>
Subscription:
- Send a message to <majordomo@vger.kernel.org> containing the
- following body:
+ Send a message to <majordomo@vger.kernel.org> containing
+ the following body:
subscribe linux-man
If you know how to fix a problem in a manual page (if not, see
"Reporting bugs" below), then send a patch in an email.
- - Follow the instructions for sending mail to the mailing list above.
+ - Follow the instructions for sending mail to the mailing list
+ above.
- - The subject of the email should contain "[patch]" in the subject line.
+ - The subject of the email should contain "[patch]" in the
+ subject line.
- The above is the minimum needed so that someone might respond to your
- patch. If you did that and someone does not respond within a few days,
- then ping the email thread, "replying to all". Make sure to send it to
- the maintainers in addition to the mailing list.
+ The above is the minimum needed so that someone might respond to
+ your patch. If you did that and someone does not respond within
+ a few days, then ping the email thread, "replying to all". Make
+ sure to send it to the maintainers in addition to the mailing
+ list.
- To make your patch even more useful, please note the following points:
+ To make your patch even more useful, please note the following
+ points:
- - Write a suitable subject line. Make sure to mention the name(s) of
- the page(s) being patched. Example:
+ - Write a suitable subject line. Make sure to mention the
+ name(s) of the page(s) being patched. Example:
[patch] shmop.2: Add "(void *)" cast to RETURN VALUE
- - Sign your patch with "Signed-off-by:". Read about the "Developer's
- Certificate of Origin" at
+ - Sign your patch with "Signed-off-by:". Read about the
+ "Developer's Certificate of Origin" at
<https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>.
When appropriate, other tags documented in that file, such as
- "Reported-by:", "Reviewed-by:", "Acked-by:", and "Suggested-by:" can
- be added to the patch. The man-pages project also uses a
- "Cowritten-by:" tag with the obvious meaning. Example:
+ "Reported-by:", "Reviewed-by:", "Acked-by:", and
+ "Suggested-by:" can be added to the patch. The man-pages
+ project also uses a "Cowritten-by:" tag with the obvious
+ meaning. Example:
Signed-off-by: Alejandro Colomar <alx@kernel.org>
- Describe how you obtained the information in your patch. For
example, was it:
- - by reading (or writing) the relevant kernel or (g)libc source
- code? Please provide a pointer to the following code.
+ - by reading (or writing) the relevant kernel or (g)libc
+ source code? Please provide a pointer to the following
+ code.
- from a commit message in the kernel or (g)libc source code
repository? Please provide a commit ID.
- - by writing a test program? Send it with the patch, but please
- make sure it's as simple as possible, and provide instructions on
- how to use it and/or a demo run.
+ - by writing a test program? Send it with the patch, but
+ please make sure it's as simple as possible, and provide
+ instructions on how to use it and/or a demo run.
- - from a standards document? Please name the standard, and quote
- the relevant text.
+ - from a standards document? Please name the standard, and
+ quote the relevant text.
- from other documentation? Please provide a pointer to that
documentation.
- - from a mailing list or online forum? Please provide a URL if
- possible.
+ - from a mailing list or online forum? Please provide a URL
+ if possible.
- - Send patches in diff -u format, inline inside the email message. If
- you're worried about your mailer breaking the patch, the send it
- both inline and as an attachment. You may find it useful to employ
- git-send-email(1) and git-format-patch(1).
+ - Send patches in diff -u format, inline inside the email
+ message. If you're worried about your mailer breaking the
+ patch, the send it both inline and as an attachment. You may
+ find it useful to employ git-send-email(1) and
+ git-format-patch(1).
- - Where relevant, include source code comments that cite commit hashes
- for relevant kernel or glibc changes:
+ - Where relevant, include source code comments that cite commit
+ hashes for relevant kernel or glibc changes:
.\" commit <40-character-git-hash>
- ffix: Formatting fix.
- tfix: Typo fix.
- wfix: Minor wording fix.
- - srcfix: Change to manual page source that doesn't affect output.
+ - srcfix: Change to manual page source that doesn't affect
+ the output.
Example:
[patch] tcp.7: tfix
- Send logically separate patches. For unrelated pages, or for
- logically-separate issues in the same page, send separate emails.
+ logically-separate issues in the same page, send separate
+ emails.
- - Make patches against the latest version of the manual page. Use
- git(1) for getting the latest version.
+ - Make patches against the latest version of the manual page.
+ Use git(1) for getting the latest version.
Lint & check
- If you plan to patch a manual page, consider running the linters and
- checks configured in the build system, to make sure your change doesn't
- add new warnings. However, you might still get warnings that are not
- your fault. To minimize that, do the following steps:
+ If you plan to patch a manual page, consider running the linters
+ and checks configured in the build system, to make sure your
+ change doesn't add new warnings. However, you might still get
+ warnings that are not your fault. To minimize that, do the
+ following steps:
- (1) First use make(1)'s -t option, so that make(1) knows that it only
- needs to lint & check again pages that you will touch.
+ (1) First use make(1)'s -t option, so that make(1) knows that it
+ only needs to lint & check again pages that you will touch.
$ make -t lint check >/dev/null
(2) Run make(1) again, asking it to imagine that the page wou'll
- modify has been touched, to see which warnings you'll still see
- from that page that are not your fault.
+ modify has been touched, to see which warnings you'll still
+ see from that page that are not your fault.
$ # replace 'man2/membarrier.2' by the page you'll modify
$ make -W man2/membarrier.2 -k lint check
- (3) Apply your changes, and then run make(1) again. You can ignore
- warnings that you saw in step (2), but if you see any new ones,
- please fix them if you know how, or at least note them in your
- patch email.
+ (3) Apply your changes, and then run make(1) again. You can
+ ignore warnings that you saw in step (2), but if you see any
+ new ones, please fix them if you know how, or at least note
+ them in your patch email.
$ vi man2/membarrier.2 # do your work
$ make -k lint check
- See <INSTALL> for a list of dependencies that this feature requires.
- If you can't meet them all, don't worry; it will still run the linters
- and checks that you have available.
+ See <INSTALL> for a list of dependencies that this feature
+ requires. If you can't meet them all, don't worry; it will still
+ run the linters and checks that you have available.
Style guide
- For a description of the preferred layout of manual pages, as well as
- some style guide notes, see:
+ For a description of the preferred layout of manual pages, as
+ well as some style guide notes, see:
$ man 7 man-pages
It will also be interesting to consult groff_man(7) and
- groff_man_style(7) for understanding and writing good man(7) source code.
+ groff_man_style(7) for understanding and writing good man(7)
+ source code.
Reporting bugs
- Report bugs to the mailing list, following the instructions above for
- sending mails to the list. If you can write a patch (see instructions
- for sending patches above), it's preferred.
+ Report bugs to the mailing list, following the instructions above
+ for sending mails to the list. If you can write a patch (see
+ instructions for sending patches above), it's preferred.
- If you're unsure if the bug is in the manual page or in the code being
- documented (kernel, glibc, ...), it's best to send the report to both
- at the same time, that is, CC all the mailing lists that may be
- concerned by the report.
+ If you're unsure if the bug is in the manual page or in the code
+ being documented (kernel, glibc, ...), it's best to send the
+ report to both at the same time, that is, CC all the mailing
+ lists that may be concerned by the report.
- Some distributions (for example Debian) apply patches to the upstream
- manual pages. If you suspect the bug is in one of those patches,
- report it to your distribution maintainer.
+ Some distributions (for example Debian) apply patches to the
+ upstream manual pages. If you suspect the bug is in one of those
+ patches, report it to your distribution maintainer.
Send logically separate reports. For unrelated pages, or for
logically-separate issues in the same page, send separate emails.
- There's also a bugzilla, but we don't use it as much as the mailing list.
+ There's also a bugzilla, but we don't use it as much as the
+ mailing list.
Notes
External and autogenerated pages
- A few pages come from external sources. Fixes to the pages should
- really go to the upstream source.
+ A few pages come from external sources. Fixes to the pages
+ should really go to the upstream source.
tzfile(5), zdump(8), and zic(8) come from the tz project
<https://www.iana.org/time-zones>.
- bpf-helpers(7) is autogenerated from the Linux kernel sources using
- scripts. See man-pages commits 53666f6c3 and 19c7f7839 for details.
+ bpf-helpers(7) is autogenerated from the Linux kernel sources
+ using scripts. See man-pages commits 53666f6c3 and 19c7f7839 for
+ details.
Bugs
Bugzilla:
Description
(a) Use a package manager
- If you want to install the manual pages into your system, consider
- installing them through your package manager from an official release,
- instead of installing them from this repository. This repository
- contains the newest manual pages, but using an official release and the
- system package manager offers important benefits. On a Debian system
- it would be:
+ If you want to install the manual pages into your system,
+ consider installing them through your package manager from an
+ official release, instead of installing them from this
+ repository. This repository contains the newest manual pages,
+ but using an official release and the system package manager
+ offers important benefits. On a Debian system it would be:
$ sudo apt-get install -V manpages-dev manpages
- If you prefer to install the manual pages from this repository, maybe
- because your system ships a too old version, consider updating the
- package offered by your system. See the <RELEASE> file, and also
- talk to the maintainer of the package in your distribution.
+ If you prefer to install the manual pages from this repository,
+ maybe because your system ships a too old version, consider
+ updating the package offered by your system. See the <RELEASE>
+ file, and also talk to the maintainer of the package in your
+ distribution.
(b) Install manually from source
- If you are contributing to the project, you may want to install the
- manual pages from this repository to test them, instead of using an
- official release. Or maybe your distribution installs packages from
- source code without any package manager.
+ If you are contributing to the project, you may want to install
+ the manual pages from this repository to test them, instead of
+ using an official release. Or maybe your distribution installs
+ packages from source code without any package manager.
- In most cases, you just want to install all of the manual pages, and
- nothing else. To install them in the default system directory (per GNU
- guidelines), use:
+ In most cases, you just want to install all of the manual pages,
+ and nothing else. To install them in the default system
+ directory (per GNU guidelines), use:
$ sudo make install
A few features can be used to tweak the install:
Variables
- There are many variables available with which you can tweak the
- build system. Most of them are directory variables and command
- variables, based on the GNU Coding Standards. Others are
- specially designed for this project. To see all of the available
- variables, use:
+ There are many variables available with which you can tweak
+ the build system. Most of them are directory variables and
+ command variables, based on the GNU Coding Standards. Others
+ are specially designed for this project. To see all of the
+ available variables, use:
$ make help-variables
$ sudo make install V=1
Uninstall
- You can uninstall the pages with the following command (but see the
- "Caveats" section below):
+ You can uninstall the pages with the following command (but
+ see the "Caveats" section below):
$ sudo make uninstall
Targets
- There are targets for more granular control, such as 'install-man3'.
- See the help to know all of them:
+ There are targets for more granular control, such as
+ 'install-man3'. See the help to know all of them:
$ make help
- tac(1)
- libbsd-dev
- And one that isn't packaged, but can be extracted from the Linux
- kernel source tree in <scripts/checkpatch.pl>:
+ And one that isn't packaged, but can be extracted from the
+ Linux kernel source tree in <scripts/checkpatch.pl>:
- checkpatch(1)
Lint & check
You can lint and check both the manual pages, and the example C
- programs contained in them. See 'make help' for a list of targets that
- can be used.
+ programs contained in them. See 'make help' for a list of
+ targets that can be used.
Files
Makefile, share/mk/install-man.mk, share/mk/install.mk
- Main makefiles for installing (however, others may also be used by
- inclusion).
+ Main makefiles for installing (however, others may also be used
+ by inclusion).
share/mk/cmd.mk
Command variables.
And the Filesystem Hierarchy Standard:
<https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html>
- But deviate from them in some cases, the most notable case being the
- use of directories for manual subsections, such as <man3type/>.
+ But deviate from them in some cases, the most notable case being
+ the use of directories for manual subsections, such as
+ <man3type/>.
Caveats
Uninstall
- You can uninstall the pages. However, take into account that it will
- only uninstall pages that exist in the repository. This means that if
- you installed the manual pages from source from an older version of the
- repository with 'make install', and some page was [re]moved later, it
- won't be uninstalled. You should probably install with a prefix of
- prefix=/opt/local/man-pages to be able to nuke the directory later with
- 'rm -r /opt/local/man-pages'. However, you'll need to modify your
- $MANPATH to be able to use those manual pages as if they were in a
- system path.
+ You can uninstall the pages. However, take into account that it
+ will only uninstall pages that exist in the repository. This
+ means that if you installed the manual pages from source from an
+ older version of the repository with 'make install', and some
+ page was [re]moved later, it won't be uninstalled. You should
+ probably install with a prefix of prefix=/opt/local/man-pages to
+ be able to nuke the directory later with
+ 'rm -r /opt/local/man-pages'. However, you'll need to modify
+ your $MANPATH to be able to use those manual pages as if they
+ were in a system path.
Version and last-modified date
- If you're an end user or a distributor, make sure you do this (install)
- from a tarball, and not from the git repository. The manual pages in
- the repository have placeholders for the version and last modified date,
- which are filled when creating the tarball. You can create your own
- tarball, for which you need to read the RELEASE file.
+ If you're an end user or a distributor, make sure you do this
+ (install) from a tarball, and not from the git repository. The
+ manual pages in the repository have placeholders for the version
+ and last modified date, which are filled when creating the
+ tarball. You can create your own tarball, for which you need to
+ read the RELEASE file.
See also
gmake(1)
Linux man-pages - manual pages for GNU/Linux
Synopsis
- This package contains GNU/Linux manual pages for sections 1 through 8.
+ This package contains GNU/Linux manual pages for sections 1
+ through 8.
Description
- The manual pages in this project document primarily the Linux kernel
- and the GNU C library, but also consider relevant differences in other
- kernels or C libraries.
+ The manual pages in this project document primarily the Linux
+ kernel and the GNU C library, but also consider relevant
+ differences in other kernels or C libraries.
These pages are most of the section 2, 3, 4, 5, 7 man pages for
- GNU/Linux. A few pages are provided in sections 1 and 8 for commands
- that are not documented in other packages, and there are a few pages in
- sections 5 and 8 for the timezone utilities.
+ GNU/Linux. A few pages are provided in sections 1 and 8 for
+ commands that are not documented in other packages, and there are
+ a few pages in sections 5 and 8 for the timezone utilities.
Files
CONTRIBUTING
Instructions for releasing and distributing new versions.
Changes, Changes.old
- Change log. Includes most relevant changes. However, it's not as
- complete as the git(1) log.
+ Change log. Includes most relevant changes. However, it's not
+ as complete as the git(1) log.
Makefile, share/mk/*
- Build system. For help, consult the <INSTALL> file, and run 'make help'.
+ Build system. For help, consult the <INSTALL> file, and run
+ 'make help'.
lsm
Linux software map. See also <https://lsm.qqx.org/>.
Licenses in use by the project.
etc/*
- Configuration files for (linter) programs called by the build system.
+ Configuration files for (linter) programs called by the build
+ system.
man*/*
Manual pages.
1993 - 1995 (1.0 - 1.5)
Caveats
- Some projects provide their own manual pages, not related to the Linux
- man-pages project.
+ Some projects provide their own manual pages, not related to the
+ Linux man-pages project.
Bugs
See the <CONTRIBUTING> file.
Copyright
- Several free/open source licenses. See the <LICENSES/> directory, and
- the comment at the top of each source file.
+ Several free/open source licenses. See the <LICENSES/>
+ directory, and the comment at the top of each source file.
See also
man-pages(7)
Change log, git tag, tarball, LSM, email, and push.
Description
- This are the instructions to release a new official version of the
- project. However, these should also be useful for those who simply
- want to package a random commit (this is done for example by Gentoo).
- For packaging a random commit without an official release, you only
- need step (4) "Tarball".
+ This are the instructions to release a new official version of
+ the project. However, these should also be useful for those who
+ simply want to package a random commit (this is done for example
+ by Gentoo). For packaging a random commit without an official
+ release, you only need step (4) "Tarball".
Dependencies
- The following list of dependencies states what the build system (the
- makefiles) need to perform the relevant (dist) targets:
+ The following list of dependencies states what the build system
+ (the makefiles) need to perform the relevant (dist) targets:
- echo(1)
- expr(1)
- xargs(1)
- xz(1)
- Apart from that, the following commands are also needed for other tasks
- shown below:
+ Apart from that, the following commands are also needed for other
+ tasks shown below:
- gpg(1)
- kup(1)
(2) Changes
- Fill the <Changes> file. For that you can check older commits,
- like d4e80a7748 "Changes: Ready for 6.01". It needs manual
- intervention, but in that commit log you can check a few commands
- that will help.
+ Fill the <Changes> file. For that you can check older
+ commits, like d4e80a7748 "Changes: Ready for 6.01". It
+ needs manual intervention, but in that commit log you can
+ check a few commands that will help.
- Remember to change the version number, the date, and the
location.
- - Remove any headers not used for a specific release (usually\
- happens with "New and changed links").
+ - Remove any headers not used for a specific release
+ (usually happens with "New and changed links").
- The structure is a bit freestyle, but keep it organized.
- man-pages-6.00 was a huge release, so it might help to check it:
- 51228378bec7 "Changes: Ready for 6.00".
+ man-pages-6.00 was a huge release, so it might help to
+ check it: 51228378bec7 "Changes: Ready for 6.00".
- Commit:
(3) Tag
Create a signed tag. The tag message should note the most
- important changes in the version being released, since it will be
- read by users and packagers. It should include any information
- that is especially relevant for them. Check old tags such as
- 'man-pages-6.00' or 'man-pages-6.01'.
+ important changes in the version being released, since it
+ will be read by users and packagers. It should include any
+ information that is especially relevant for them. Check old
+ tags such as 'man-pages-6.00' or 'man-pages-6.01'.
- Tag:
(4) Tarball
Creating the tarball will embed in the manual pages both the
- version number, and the date of last modification (in the git
- repository, the pages have placeholders for the date and the
- version).
+ version number, and the date of last modification (in the
+ git repository, the pages have placeholders for the date and
+ the version).
- You need to create a set of tarballs, sign the .tar archive, and
- upload the compressed tarballs to <kernel.org>.
+ You need to create a set of tarballs, sign the .tar archive,
+ and upload the compressed tarballs to <kernel.org>.
In case you're creating a tarball for distributing a random
- commit, it might be interesting to tweak a few parameters; check
- the variables available at <share/mk/dist.mk>, and any makefiles
- included by that one. See the "Versions" section below.
+ commit, it might be interesting to tweak a few parameters;
+ check the variables available at <share/mk/dist.mk>, and any
+ makefiles included by that one. See the "Versions" section
+ below.
- Create the tarball:
$ make -Bj4 dist
- Alternatively, you may want to only create a specific kind of
- tarball with one of the following targets:
+ Alternatively, you may want to only create a specific
+ kind of tarball with one of the following targets:
$ make -Bj4 dist-tar dist-xz dist-gz
$ git add lsm
$ git commit -sm "lsm: Released ${new}"
- - Send (email) the lsm file to <lsm@qqx.org> with the subject
- "add".
+ - Send (email) the lsm file to <lsm@qqx.org> with the
+ subject "add".
(6) Email
Send an announce email to linux-man, LKML, libc-alpha, and
- possibly others that might be interested in the release, such as
- distribution maintainers, or those who have contributed to the
- release.
+ possibly others that might be interested in the release,
+ such as distribution maintainers, or those who have
+ contributed to the release.
The email should contain a mix of the git tag message, the
- contents of Changes, and anything else that might be relevant.
- Check old emails such as
+ contents of Changes, and anything else that might be
+ relevant. Check old emails such as
<https://lore.kernel.org/linux-man/4ba6c215-6d28-1769-52d3-04941b962ff3@kernel.org/T/#u>.
- The subject of the email should be "man-pages-${new} released".
+ The subject of the email should be
+ "man-pages-${new} released".
(7) Changes.old
- Move the contents of <Changes> to <Changes.old>, and prepare for
- the next release.
+ Move the contents of <Changes> to <Changes.old>, and prepare
+ for the next release.
- Copy contents of <Changes> to <Changes.old>:
$ git add Changes Changes.old
$ git commit -sm \
- "Start of man-pages-NEXT: Move Changes to Changes.old"
+ "Start of man-pages-NEXT: Move Changes to Changes.old"
(8) Push
- You've finished. When you confirm it's good, push to the git
- repository.
+ You've finished. When you confirm it's good, push to the
+ git repository.
- Push:
Change log. Includes most relevant changes.
Makefile, share/mk/dist.mk, share/mk/version.mk
- Main makefiles used for releasing (however, others may also be used by
- inclusion).
+ Main makefiles used for releasing (however, others may also be
+ used by inclusion).
lsm
Linux software map. See also <https://lsm.qqx.org/>.
.tmp/man-pages-<version>.tar{,.xz,.gz}
Generated tarballs. You can generate all with 'make -B dist', or
- generate only some of them, with 'make -B dist-tar', 'make -B dist-xz',
- or 'make -B dist-gz'.
+ generate only some of them, with 'make -B dist-tar',
+ 'make -B dist-xz', or 'make -B dist-gz'.
Versions
- Use the DISTVERSION variable when running make(1) to specify a version
- different than the default, which is generated with git-describe(1).
- This needs to be done from the git repository, and won't work from an
- extracted tarball.
+ Use the DISTVERSION variable when running make(1) to specify a
+ version different than the default, which is generated with
+ git-describe(1). This needs to be done from the git repository,
+ and won't work from an extracted tarball.
$ make -B dist-xz DISTVERSION=6.01+43
Caveats
- The version and date of last modification for each page is hardcoded
- by the Makefile into the pages when the tarball is generated. This
- means that it's not possible to generate a valid tarball from another
- extracted tarball, since the version and date will not be updated.
- Tarballs need to be created from the git(1) repository.
+ The version and date of last modification for each page is
+ hardcoded by the Makefile into the pages when the tarball is
+ generated. This means that it's not possible to generate a valid
+ tarball from another extracted tarball, since the version and
+ date will not be updated. Tarballs need to be created from the
+ git(1) repository.
projects / thirdparty / man-pages.git / commitdiff
