LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity
man-pages/README

43 lines
1.5 KiB
Plaintext
Raw Permalink Normal View History

README: Update generally * Reflect fact that project ships pages in sections 1-8. * Resync documentation of the basic Makefile targets with what they actually do at present. Slighly simplify discussion. * Put the man page overlaps into a table. + Drop references to overlaps with the old a.out ld.so, long dead. * Update reference to Announce file to use current naming convention. + Send people looking for copyright information there rather than duplicating some of it here. * Direct reader to the top-level homepage instead of more deeply to the "Contributing" page. * Reflow paragraphs to 72 columns. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-05-10 22:39:58 +00:00
This package contains Linux man pages for sections 1 through 8. Some
more information is given in the 'man-pages-x.y.Announce' file.
Import of man-pages 1.70
2004-11-03 13:51:07 +00:00
README: Move the "Home page" section to the top of the file Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-12 20:50:08 +00:00
Homepage
========
For information about the Linux man-pages project, see
http://www.kernel.org/doc/man-pages/index.html.
README: Add section on "Bug reports and contributing" Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-12 21:09:25 +00:00
Bug reports and contributing
============================
If you have corrections and additions to suggest, see
http://www.kernel.org/doc/man-pages/contributing.html
README: wfix Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-13 05:16:56 +00:00
(Although there is a mirror of this repository on GitHub,
please don't report issues via the GitHub issue tracker!)
README: Add section on "Bug reports and contributing" Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-12 21:09:25 +00:00
For further information on contributing, see the CONTRIBUTING file.
README: Update generally * Reflect fact that project ships pages in sections 1-8. * Resync documentation of the basic Makefile targets with what they actually do at present. Slighly simplify discussion. * Put the man page overlaps into a table. + Drop references to overlaps with the old a.out ld.so, long dead. * Update reference to Announce file to use current naming convention. + Send people looking for copyright information there rather than duplicating some of it here. * Direct reader to the top-level homepage instead of more deeply to the "Contributing" page. * Reflow paragraphs to 72 columns. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-05-10 22:39:58 +00:00
Installing and uninstalling
===========================
README: Update installation path The installation path was changed recently (See 'prefix' in the Makefile). I forgot to update the README with those changes. Fix it. Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-05-11 06:53:00 +00:00
"make install" will copy these man pages to /usr/local/share/man/man[1-8].
README: Update generally * Reflect fact that project ships pages in sections 1-8. * Resync documentation of the basic Makefile targets with what they actually do at present. Slighly simplify discussion. * Put the man page overlaps into a table. + Drop references to overlaps with the old a.out ld.so, long dead. * Update reference to Announce file to use current naming convention. + Send people looking for copyright information there rather than duplicating some of it here. * Direct reader to the top-level homepage instead of more deeply to the "Contributing" page. * Reflow paragraphs to 72 columns. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-05-10 22:39:58 +00:00
README: Update installation path The installation path was changed recently (See 'prefix' in the Makefile). I forgot to update the README with those changes. Fix it. Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-05-11 06:53:00 +00:00
To install to a path different from /usr/local, use
README: Explain usage of prefix when installing Installing the man pages to /usr may not be the preferred option when working on a system with a packaging system like apt or yum, where /usr is reserved for packages and /usr/local or /opt is used for user addons. README should explain how to install to a path different to /usr. Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2014-05-26 01:36:52 +00:00
"make install prefix=/install/path".
README: Update generally * Reflect fact that project ships pages in sections 1-8. * Resync documentation of the basic Makefile targets with what they actually do at present. Slighly simplify discussion. * Put the man page overlaps into a table. + Drop references to overlaps with the old a.out ld.so, long dead. * Update reference to Announce file to use current naming convention. + Send people looking for copyright information there rather than duplicating some of it here. * Direct reader to the top-level homepage instead of more deeply to the "Contributing" page. * Reflow paragraphs to 72 columns. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-05-10 22:39:58 +00:00
"make remove" or "make uninstall" will remove any man page in this
distribution from its destination. Use with caution, and remember to
use "prefix" if desired, as with the "install" target.
Makefile, README: Break installation into a target for each mandir Instead of having a monolithic 'make install', break it into multiple targets such as 'make install-man3'. This simplifies packaging, for example in Debian, where they break this project into several packages: 'manpages' and 'manpages-dev', each containing different mandirs. The above allows for multithread installation: 'make -j' Also, don't overwrite files that don't need to be overwritten, by having a target for files, which makes use of make's timestamp comparison. This allows for much faster installation times. For comparison, on my laptop (i7-8850H; 6C/12T): Old Makefile: ~/src/linux/man-pages$ time sudo make >/dev/null real 0m7.509s user 0m5.269s sys 0m2.614s The times with the old makefile, varied a lot, between 5 and 10 seconds. The times after applying this patch are much more consistent. BTW, I compared these times to the very old Makefile of man-pages-5-09, and those were around 3.5 s, so it was a bit of my fault to have such a slow Makefile, when I changed the Makefile some weeks ago. New Makefile (full clean install): ~/src/linux/man-pages$ time sudo make >/dev/null real 0m5.160s user 0m4.326s sys 0m1.137s ~/src/linux/man-pages$ time sudo make -j2 >/dev/null real 0m1.602s user 0m2.529s sys 0m0.289s ~/src/linux/man-pages$ time sudo make -j >/dev/null real 0m1.398s user 0m2.502s sys 0m0.281s Here we can see that 'make -j' drops times drastically, compared to the old monolithic Makefile. Not only that, but since when we are working with the man pages there aren't many pages involved, times will be even better. Here are some times with a single page changed (touched): New Makefile (one page touched): ~/src/linux/man-pages$ touch man2/membarrier.2 ~/src/linux/man-pages$ time sudo make install - INSTALL /usr/local/share/man/man2/membarrier.2 real 0m0.988s user 0m0.966s sys 0m0.025s ~/src/linux/man-pages$ touch man2/membarrier.2 ~/src/linux/man-pages$ time sudo make install -j - INSTALL /usr/local/share/man/man2/membarrier.2 real 0m0.989s user 0m0.943s sys 0m0.049s Also, modify the output of the make install and uninstall commands so that a line is output for each file or directory that is installed, similarly to the kernel's Makefile. This doesn't apply to html targets, which haven't been changed in this commit. Also, make sure that for each invocation of $(INSTALL_DIR), no parents are created, (i.e., avoid `mkdir -p` behavior). The GNU make manual states that it can create race conditions. Instead, declare as a prerequisite for each directory its parent directory, and let make resolve the order of creation. Also, use ':=' instead of '=' to improve performance, by evaluating each assignment only once. Ensure than the shell is not called when not needed, by removing all ";" and quotes in the commands. See also: <https://stackoverflow.com/q/67862417/6872717> Specify conventions and rationales used in the Makefile in a comment. Add copyright. Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-06-09 17:01:08 +00:00
To install only a specific man section (mandir) such as man3, use
"make install-man3". Similar syntax can be used to uninstall a
specific man section, such as man7: "make uninstall-man7".
README: Update generally * Reflect fact that project ships pages in sections 1-8. * Resync documentation of the basic Makefile targets with what they actually do at present. Slighly simplify discussion. * Put the man page overlaps into a table. + Drop references to overlaps with the old a.out ld.so, long dead. * Update reference to Announce file to use current naming convention. + Send people looking for copyright information there rather than duplicating some of it here. * Direct reader to the top-level homepage instead of more deeply to the "Contributing" page. * Reflow paragraphs to 72 columns. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-05-10 22:39:58 +00:00
"make" or "make all" will perform "make uninstall" followed by "make
install".
Makefile, README: Break installation into a target for each mandir Instead of having a monolithic 'make install', break it into multiple targets such as 'make install-man3'. This simplifies packaging, for example in Debian, where they break this project into several packages: 'manpages' and 'manpages-dev', each containing different mandirs. The above allows for multithread installation: 'make -j' Also, don't overwrite files that don't need to be overwritten, by having a target for files, which makes use of make's timestamp comparison. This allows for much faster installation times. For comparison, on my laptop (i7-8850H; 6C/12T): Old Makefile: ~/src/linux/man-pages$ time sudo make >/dev/null real 0m7.509s user 0m5.269s sys 0m2.614s The times with the old makefile, varied a lot, between 5 and 10 seconds. The times after applying this patch are much more consistent. BTW, I compared these times to the very old Makefile of man-pages-5-09, and those were around 3.5 s, so it was a bit of my fault to have such a slow Makefile, when I changed the Makefile some weeks ago. New Makefile (full clean install): ~/src/linux/man-pages$ time sudo make >/dev/null real 0m5.160s user 0m4.326s sys 0m1.137s ~/src/linux/man-pages$ time sudo make -j2 >/dev/null real 0m1.602s user 0m2.529s sys 0m0.289s ~/src/linux/man-pages$ time sudo make -j >/dev/null real 0m1.398s user 0m2.502s sys 0m0.281s Here we can see that 'make -j' drops times drastically, compared to the old monolithic Makefile. Not only that, but since when we are working with the man pages there aren't many pages involved, times will be even better. Here are some times with a single page changed (touched): New Makefile (one page touched): ~/src/linux/man-pages$ touch man2/membarrier.2 ~/src/linux/man-pages$ time sudo make install - INSTALL /usr/local/share/man/man2/membarrier.2 real 0m0.988s user 0m0.966s sys 0m0.025s ~/src/linux/man-pages$ touch man2/membarrier.2 ~/src/linux/man-pages$ time sudo make install -j - INSTALL /usr/local/share/man/man2/membarrier.2 real 0m0.989s user 0m0.943s sys 0m0.049s Also, modify the output of the make install and uninstall commands so that a line is output for each file or directory that is installed, similarly to the kernel's Makefile. This doesn't apply to html targets, which haven't been changed in this commit. Also, make sure that for each invocation of $(INSTALL_DIR), no parents are created, (i.e., avoid `mkdir -p` behavior). The GNU make manual states that it can create race conditions. Instead, declare as a prerequisite for each directory its parent directory, and let make resolve the order of creation. Also, use ':=' instead of '=' to improve performance, by evaluating each assignment only once. Ensure than the shell is not called when not needed, by removing all ";" and quotes in the commands. See also: <https://stackoverflow.com/q/67862417/6872717> Specify conventions and rationales used in the Makefile in a comment. Add copyright. Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-06-09 17:01:08 +00:00
Consider using multiple threads (at least 2) when installing
these man pages, as the Makefile is optimized for multiple threads:
"make -j install".
README: Update generally * Reflect fact that project ships pages in sections 1-8. * Resync documentation of the basic Makefile targets with what they actually do at present. Slighly simplify discussion. * Put the man page overlaps into a table. + Drop references to overlaps with the old a.out ld.so, long dead. * Update reference to Announce file to use current naming convention. + Send people looking for copyright information there rather than duplicating some of it here. * Direct reader to the top-level homepage instead of more deeply to the "Contributing" page. * Reflow paragraphs to 72 columns. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-05-10 22:39:58 +00:00
Copyrights
==========
See the 'man-pages-x.y.Announce' file.