Merge branch 'refs/heads/t/doc'

The contributing section for the user manual and a few other
documentation updates.

* refs/heads/t/doc:
  signal.h: Add documentation of signal_pre_select().
  manual: Fix kernel coding style link.
  user manual: Add section on contributing.

diff --git a/NEWS.md b/NEWS.md
index 3d00528d123929d78d4895a5a57fd748c085cdad..d47141ce1f8112cdd73b59814b9124dad5dd5019 100644 (file)
--- a/NEWS.md
+++ b/NEWS.md
@@ -16,6 +16,7 @@ NEWS
   files with unusual block sizes.
 - We now compile with -Wformat-signedness if possible.
 - The touch command now refuses to set an invalid image or lyrics ID.
+- New section on contributing for the user manual.
 
 Download: [tarball](./releases/paraslash-git.tar.bz2)
 

diff --git a/signal.h b/signal.h
index b5b06f356999062f3b9b233e8303eea33015804a..742f677a2568cad3001ae9cc2220344ebf7f8b1b 100644 (file)
--- a/signal.h
+++ b/signal.h
@@ -16,6 +16,22 @@ struct signal_task {
        struct task *task;
 };
 
+/**
+ * A generic pre-select method for signal tasks.
+ *
+ * \param s Passed to para_fd_set().
+ * \param context Signal task pointer.
+ *
+ * This convenience helper is called from several programs which need to handle
+ * signals, including para_server and para_audiod. These programs define a
+ * signal task structure and set its ->pre_select method to this function which
+ * adds the file descriptor of the signal task to the set of descriptors to be
+ * watched in the next select() call.
+ *
+ * Although the second parameter must be in fact a pointer to a signal_task
+ * structure, the parameter is specified as void * here to match the
+ * ->pre_select method of struct task.
+ */
 _static_inline_ void signal_pre_select(struct sched *s, void *context)
 {
        struct signal_task *st = context;

diff --git a/web/manual.md b/web/manual.md
index 15386134771c2921ecf840347e8179aecc374e1a..12454ee2ae55ba131165ae2d442041879dad33b1 100644 (file)
--- a/web/manual.md
+++ b/web/manual.md
@@ -1813,6 +1813,33 @@ Examples
 Development
 ===========
 
+Contributing
+------------
+
+Paraslash is an open source project and contributions are
+welcome. Here's a list of things you can do to help the project:
+
+- Report problems with building, installing or running the software.
+  In particular, test the experimental git branches ("next" and "pu").
+  This helps to identify and fix problems before the code gets merged
+  and thus keeps the master branch as stable as possible.
+- Proofread the documentation (manual, web pages, man pages, source
+  code documentation) and point out unclear or poorly written parts. If
+  you are a native English speaker you will easily find a lot of text
+  that could be improved.
+- Run analysis tools (coverity, afl, sparse, etc.) and report issues
+  found by those tools.
+- Suggest new features you would like to see implemented.
+- Compile and test on your favorite architecture or operating
+  system. The code is tested only on a limited set of systems, so you
+  will probably encounter problems when building on different systems.
+- Post about about paraslash on your blog or on social networks.
+- Build and maintain Debian/RPM packages for your favorite distribution.
+
+Note that there is no mailing list, no bug tracker and no discussion
+forum for paraslash. If you'd like to contribute, or have questions
+about contributing, send email to Andre Noll <maan@tuebingen.mpg.de>.
+
 Tools
 -----
 
@@ -1934,7 +1961,7 @@ Coding Style
 
 The preferred coding style for paraslash coincides more or less
 with the style of the Linux kernel. So rather than repeating what is
-written [there](http://www.kernel.org/doc/Documentation/CodingStyle),
+written [there](http://www.kernel.org/doc/Documentation/process/coding-style.rst),
 here are the most important points.
 
 - Burn the GNU coding standards.