From: Craig Small Date: Sun, 10 May 2015 07:23:54 +0000 (+1000) Subject: docs: Updated documentation X-Git-Tag: v3.3.11~59 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=7993b4d85d0d90f668394e1cf4c375ae0b5a3f65;p=procps-ng docs: Updated documentation Updated the documents with the following general changes: * Replaced Gitorious with GitLab * Moved translate stuff out of README * Changed plain text to markdown (looks better on website) --- diff --git a/Documentation/BUGS b/Documentation/BUGS deleted file mode 100644 index c0d623bd..00000000 --- a/Documentation/BUGS +++ /dev/null @@ -1,82 +0,0 @@ -BUG REPORTS - -Please read this file before sending in a bug report or patch. - -Also, PLEASE read the documentation first. 90% of the mail I get -complaining about procps-ng is due to the sender not having read the -documentation! - - -Where to send -============= -Send comments, bug reports, patches, etc., to procps@freelists.org - - -What to send -============ -It is much more useful to me if a program really crashes to recompile it -with make "CFLAGS=-ggdb -O", run it with "gdb prog" and "run" and send -me a stack trace ('bt' command). That said, any bug report is still -better than none. - -strace and ltrace output are very helpful: - - strace -o output-file ps --blah - bzip2 output-file - -I also like "ps --info" output, even if there isn't a ps problem. - -Patches -======= - -Get latest version of the source from upstream git. - -git clone git://gitorious.org/procps/procps.git - -and use 'git format-patch' format. It is fine to attach patches as -compressed tar balls. When you are about to send very large number -of patches consider setting up your personal clone, and send a pull -request. - -git request-pull commit-id \ - git://gitorious.org/~yourlogin/procps/your-clone.git - -Gitorious merge requests -======================== -Prefer sending pull request to mail list. More people will notice a -change being proposed, making potential discussion to capture wider -point of view. Using gitorious merge reguest in combination mail -list announcement is fine. - -Kernel-Dependent Patches -======================== -If you send me patches which are specific to *running* with a particular -kernel version of /proc, please condition them with the runtime determined -variable 'linux_version_code' from libproc/version.c. It is the same -number as the macro LINUX_VERSION_CODE for which the kernel /proc fs -code was compiled. - -A macro is provide in libproc/version.h to construct the code from its -components, e.g. - if (linux_version_code < LINUX_VERSION(2,5,41)) - /* blah blah blah */ -A startup call to set_linux_version may also be necessary. - -Of course, if a bug is due to a change in kernel file formats, it would -be best to first try to generalize the parsing, since the code is then -more resilient against future change. - -Code Structure -============== - -A goal is to encapsulate *all* parsing dependent on /proc -file formats into the libproc library. If the API is general enough -it can hopefully stabilize and then /proc changes might only require -updating libproc.so. Beyond that having the set of utilities be simple -command lines parsers and output formatters and encapsulating all kernel -divergence in libproc is the way to go. - -Hence if you are submitting a new program or are fixing an old one, keep -in mind that adding files to libproc which encapsulate such things is -more desirable than patching the actual driver program. (well, except -to move it toward the API of the library). diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle.md similarity index 100% rename from Documentation/CodingStyle rename to Documentation/CodingStyle.md diff --git a/Documentation/bugs.md b/Documentation/bugs.md new file mode 100644 index 00000000..1eddf049 --- /dev/null +++ b/Documentation/bugs.md @@ -0,0 +1,92 @@ +BUG REPORTS +=========== + +The following is information for reporting bugs. Please read +the file as well as the documentation for the relevant program +before posting. This document is more useful for advanced users +and the people that package for the distributions. + +Also if you are an end-user of the programs and not the packager +and are using a distribution, check their bug tracker first, +you may find its a known bug already. + + +Where to send +------------- +You can raise issues on the GitLab issues tracker which is +located at https://gitlab.com/procps-ng/procps/issues You +will need a GitLab login to do so. + +Alternatively send comments, bug reports, patches, etc. +to the email list procps@freelists.org + +What to send +------------ +It is much more useful to us if a program really crashes to recompile it +with make `CFLAGS=-ggdb -O`, run it with `gdb prog` and `run` and send +me a stack trace (`bt` command). That said, any bug report is still +better than none. + +strace and ltrace output are very helpful: + +> strace -o output-file ps --blah +> bzip2 output-file + +The output of `ps --info` is often quite useful, even if the problem +is not with ps itself. A lot of the utilities use the same library. + +Merge Requests +-------------- +Merge requests are fine to use and give a central place for +everyone involved to have a look. Merge requests are found +on GitLab at https://gitlab.com/procps-ng/procps/merge_requests +It is best to follow up your merge request with an email to +the list saying what you have done. + +Patches +------- +While merge requests are preferred, patches are also welcome. +Get latest version of the source from upstream git. + +> git clone git@gitlab.com:procps-ng/procps.git + +and use `git format-patch` format. It is fine to attach patches as +compressed tar balls. When you are about to send very large number +of patches consider setting up your personal clone, and send a pull +request. + +> git request-pull commit-id \ +> git://gitorious.org/~yourlogin/procps/your-clone.git + + +Kernel-Dependent Patches +------------------------ +If you send patches which are specific to *running* with a particular +kernel version of /proc, please condition them with the runtime determined +variable `linux_version_code` from libproc/version.c. It is the same +number as the macro `LINUX_VERSION_CODE` for which the kernel /proc fs +code was compiled. + +A macro is provide in libproc/version.h to construct the code from its +components, e.g. +> if (linux_version_code < LINUX_VERSION(2,5,41)) +> /* blah blah blah */ +A startup call to `set_linux_version` may also be necessary. + +Of course, if a bug is due to a change in kernel file formats, it would +be best to first try to generalize the parsing, since the code is then +more resilient against future change. + +Code Structure +-------------- +A goal is to encapsulate *all* parsing dependent on /proc +file formats into the libproc library. If the API is general enough +it can hopefully stabilize and then /proc changes might only require +updating libproc.so. Beyond that having the set of utilities be simple +command lines parsers and output formatters and encapsulating all kernel +divergence in libproc is the way to go. + +Hence if you are submitting a new program or are fixing an old one, keep +in mind that adding files to libproc which encapsulate such things is +more desirable than patching the actual driver program. (well, except +to move it toward the API of the library). diff --git a/Documentation/translations.md b/Documentation/translations.md new file mode 100644 index 00000000..654a45f1 --- /dev/null +++ b/Documentation/translations.md @@ -0,0 +1,21 @@ +Translations +============ + +There is a three-step process for translating man pages. Most +of the work happens in the man-po directory. + +> make -C man-po translate-templates +Creates the translation templates (the .pot files) for translators +to use as a base. These, along with the tar file, should be sent +to the tp-coorindator before release. + +> make get-trans +rsyncs the latest translated (.po) files for both the programs and +man pages. + +> make -C man-po translate-mans +This is also called in the dist-hook and is where the translation +magic happens. Take the original man page, the relevant .po file +and produce a translated man page in that language. +All of the man pages generated are found in +man-po/(LANG)/man(SECTION)/ diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..c8aee5f6 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,24 @@ +Installation Instructions for procps +==================================== +Depending on what format you are using to get these files, you +might need to run the `autogen.sh` program to create the +configure script. If you have a configure script already then +you might not need it. + +A typical installation would go something like +> ./autogen.sh +> ./configure +> make +> make install + +The configure script has a lot of options, so please have a read +of `configure --help` to see what they are and what they are used +for. + +Testing +------- +procps has a series of test scripts (and more are welcome if they +are repeatable). You will need to install DejaGNU to run it and +it is simply: + +> make check diff --git a/README b/README deleted file mode 100644 index 54c871f7..00000000 --- a/README +++ /dev/null @@ -1,67 +0,0 @@ -COMPATIBILITY - - This code is intended for use with Linux 2.6.xx, 3.x and - hopefully all future kernels. - -INSTALLATION - - If you are using git version of the project you need extra step. - - ./autogen.sh - - After that, and everyone using .tar.xz version of procps-ng, can - do normal build. Read './configure --help' to select options for - your needs. - - ./configure - make - make install - - If you have DejaGNU installed you can run optional test suite. - - make check - -HOW TO CONTRIBUTE - - See Documentation/BUGS file. - -PACKAGING - - If you are a downstream maintainer (packager) for a Linux - distribution, please avoid causing troubles. This section - applies to you. - - Avoid maintaining distribution specific patches. Send your - patches to upstream, where they are at least reviewed, if not - included. - - Please forward bug reports. If your bug database is public and - busy enough to bother with, please make this known. Follow - Debian's lead in making the bug database easy to comment on via - email without need for an account. - - For normal packages, ensure that you do not add debugging flags - to the CFLAGS variable. - -TRANSLATING MAN PAGES - There is a three-step process for translating man pages. Most - of the work happens in the man-po directory. - - make -C man-po translate-templates - Creates the translation templates (the .pot files) for translators - to use as a base. These, along with the tar file, should be sent - to the tp-coorindator before release. - - make get-trans - rsyncs the latest translated (.po) files for both the programs and - man pages. - - make -C man-po translate-mans - This is also called in the dist-hook and is where the translation - magic happens. Take the original man page, the relevant .po file - and produce a translated man page in that language. - All of the man pages generated are found in - man-po/(LANG)/man(SECTION)/ -UPSTREAM & BUG REPORTS - - procps-ng