From 315cc123cdba79098bf1ab7cc7a103061d9383ed Mon Sep 17 00:00:00 2001 From: Alejandro Colomar Date: Sat, 8 Jul 2023 20:28:14 +0200 Subject: [PATCH] CONTRIBUTING, INSTALL, README, RELEASE: Reflow to 72 columns This makes it easier to quote in emails. Signed-off-by: Alejandro Colomar --- CONTRIBUTING | 182 ++++++++++++++++++++++++++++----------------------- INSTALL | 100 ++++++++++++++-------------- README | 33 +++++----- RELEASE | 117 +++++++++++++++++---------------- 4 files changed, 229 insertions(+), 203 deletions(-) diff --git a/CONTRIBUTING b/CONTRIBUTING index 25106f53fc..80052c38e8 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -2,34 +2,37 @@ Name 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 Cc: - 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 Cc: Linux API Cc: Glibc - For other kernel mailing lists and maintainers, check the - file in the Linux kernel repository. + For other kernel mailing lists and maintainers, check the + file in the Linux kernel repository. Please don't send HTML email; it will be discarded by the list. @@ -38,8 +41,8 @@ Description Subscription: - Send a message to containing the - following body: + Send a message to containing + the following body: subscribe linux-man @@ -55,61 +58,68 @@ Description 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 . 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 - 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> @@ -118,86 +128,92 @@ Description - 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 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 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 . - 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: diff --git a/INSTALL b/INSTALL index bc2cc83487..d12fd7ae5b 100644 --- a/INSTALL +++ b/INSTALL @@ -6,29 +6,30 @@ Synopsis 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 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 + 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 @@ -39,11 +40,11 @@ Description 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 @@ -57,14 +58,14 @@ Description $ 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 @@ -112,8 +113,8 @@ Description - tac(1) - libbsd-dev - And one that isn't packaged, but can be extracted from the Linux - kernel source tree in : + And one that isn't packaged, but can be extracted from the + Linux kernel source tree in : - checkpatch(1) @@ -126,13 +127,13 @@ Description 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. @@ -160,27 +161,30 @@ Standards And the Filesystem Hierarchy Standard: - But deviate from them in some cases, the most notable case being the - use of directories for manual subsections, such as . + But deviate from them in some cases, the most notable case being + the use of directories for manual subsections, such as + . 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) diff --git a/README b/README index beb20b055f..9925ac13ff 100644 --- a/README +++ b/README @@ -2,17 +2,18 @@ Name 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 @@ -31,11 +32,12 @@ Files 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 file, and run 'make help'. + Build system. For help, consult the file, and run + 'make help'. lsm Linux software map. See also . @@ -47,7 +49,8 @@ Files 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. @@ -90,15 +93,15 @@ History 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 file. Copyright - Several free/open source licenses. See the directory, and - the comment at the top of each source file. + Several free/open source licenses. See the + directory, and the comment at the top of each source file. See also man-pages(7) diff --git a/RELEASE b/RELEASE index 1e20718bb9..6d4b7b1cfe 100644 --- a/RELEASE +++ b/RELEASE @@ -5,15 +5,15 @@ Synopsis 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) @@ -30,8 +30,8 @@ Description - 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) @@ -46,20 +46,20 @@ Description (2) Changes - Fill the 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 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: @@ -69,10 +69,10 @@ Description (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: @@ -81,24 +81,25 @@ Description (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 . + You need to create a set of tarballs, sign the .tar archive, + and upload the compressed tarballs to . 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 , 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 , 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 @@ -129,27 +130,28 @@ Description $ git add lsm $ git commit -sm "lsm: Released ${new}" - - Send (email) the lsm file to with the subject - "add". + - Send (email) the lsm file to 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 . - 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 to , and prepare for - the next release. + Move the contents of to , and prepare + for the next release. - Copy contents of to : @@ -164,12 +166,12 @@ Description $ 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: @@ -183,28 +185,29 @@ Files 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 . .tmp/man-pages-.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. -- 2.39.2