Update documentation

Document that we now support GitHub.  Also, change .md files
to use ~~~~ instead of `...` because that's friendlier to
people who want to cut-and-paste commands.

Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>

CONTRIBUTING.md

@@ -3,13 +3,24 @@
 We love contributions!  Here's how to do them in a way that will
 make everyone's lives easy.
 
+Flawfinder has long been maintained on SourceForge.
+We now support reporting and changes using either SourceForge or GitHub.
+
 ## Reporting
 
-For normal problems, bugs, and feature requests, please file a
+For normal problems, bugs, and feature requests, *except* for
-[ticket](https://sourceforge.net/p/flawfinder/_list/tickets).
+vulnerabilities, please file a
+[GitHub issue](https://github.com/david-a-wheeler/flawfinder/issues) or
+[SourceForge ticket](https://sourceforge.net/p/flawfinder/_list/tickets).
 
 If you find a vulnerability, please separately send a private email to
 [David A. Wheeler](https://dwheeler.com/contactme.html).
+To maintain confidentiality,
+please use an email system that implements STARTTLS hop-by-hop email
+encryption on outgoing email (many do, including
+Gmail, hotmail.com, live.com, outlook.com, and runbox.com).
+For more about STARTTLS, see the
+EFF's [STARTTLS Everywhere](https://www.starttls-everywhere.org/) project.
 We plan to handle vulnerabilities separately, fixing them and *then*
 telling the world.  We will gladly provide credit to vulnerability reporters
 (unless you don't want the credit).  We've never had a vulnerability
@@ -19,9 +30,13 @@ report, so this is theoretical at this time.
 
 We use "git" to track changes.  To propose a change, create a fork
 (copy) of the repository, make your changes, and create a
-merge request (also called a pull request).
+GitHub pull request or SourceForge merge request (they are the same thing).
+
 If you're not familiar with the process, here's some
-[documentation](https://sourceforge.net/p/forge/documentation/Git/).
+documentation for
+[GitHub](https://help.github.com/articles/about-pull-requests/)
+and
+[SourceForge](https://sourceforge.net/p/forge/documentation/Git/).
 
 ## License and DCO
 
@@ -55,15 +70,21 @@ An easy way to install pylint is to use pip.
 Most python installs have pip, but if yours does not
 (e.g., Cygwin), install pip with:
 
-`python -m ensurepip`
+~~~~
+python -m ensurepip
+~~~~
 
 You may want to upgrade pip with:
 
-`pip install --upgrade pip`
+~~~~
+pip install --upgrade pip
+~~~~
 
 Finally, you can actually install pylint using:
 
-`pip install pylint`
+~~~~
+pip install pylint
+~~~~
 
 ## Code Conventions
 
@@ -80,12 +101,16 @@ patches to improve that are often welcome.
 The code must run on both Python 2.7 and Python 3.
 To check that it works on both, run:
 
-`make check`
+~~~~
+make check
+~~~~
 
 We use "pylint" to check for style and other generic quality problems.
 To check that the code passes these quality tests, run:
 
-`make pylint`
+~~~~
+make pylint
+~~~~
 
 We require that the pylint results for contributions be at least 9.5/10 as
 configured with the provided "pylintrc" file, without any errors ("E").
@@ -108,5 +133,12 @@ the automated test suite.
 
 ## Other
 
+Project documentation tends to be in markdown (.md) format.
+We use "~~~~" so that it's easy to cut-and-paste commands if desired.
+The main document is a man page, which is then converted to PDF.
+
+Avoid trailing space or tab on a line in source files - those can create
+hard-to-understand "differences" on lines.
+
 We have earned a
 [CII Best Practices Badge](https://bestpractices.coreinfrastructure.org/projects/323)... make sure we keep it!

INSTALL.md

@@ -12,7 +12,9 @@ For many, the simple approach is to first install Python
 Then use `pip` to install flawfinder
 (this will normally download the package):
 
-`pip install flawfinder`
+~~~~
+pip install flawfinder
+~~~~
 
 One advantage for using pip is that you'll generally get the
 *current* released version.
@@ -28,7 +30,10 @@ For a ports-based system where you have a current port, just use that.
 This will work out-of-the-box; it may not be the most recent version.
 
 One way to accomplish this is:
-`sudo apt install flawfinder`
+
+~~~~
+sudo apt install flawfinder
+~~~~
 
 
 ## 3. TARBALL (SOURCE INSTALL)
@@ -37,7 +42,9 @@ QUICK START:
 The quick way to install flawfinder from the tarball is to
 unpack the tarball and type in something like this on the command line:
 
-`sudo make prefix=/usr install`
+~~~~
+sudo make prefix=/usr install
+~~~~
 
 Omit prefix=/usr to install in /usr/local instead.
 Omit "sudo" if you are already root.
@@ -119,4 +126,6 @@ Not enough?  Here are more detailed step-by-step instructions and options.
 You can also simply run the program in the directory you've unpacked it
 into.   It's a simple Python program, just type into a command line:
 
-`./flawfinder files_or_directory`
+~~~~
+./flawfinder FILES-OR-DIRECTORY
+~~~~

README.md

@@ -15,7 +15,7 @@ For more information, see the [project website](http://dwheeler.com/flawfinder)
 
 Flawfinder is designed for use on Unix/Linux/POSIX systems
 (including Cygwin, Linux-based systems, MacOS, and various BSDs) as a
-command line tool.  It requires Python 2.7 or Python 3.
+command line tool.  It requires either Python 2.7 or Python 3.
 
 # Installation
 
@@ -31,7 +31,24 @@ You don't HAVE to install it to run it, but it's easiest that way.
 To run flawfinder, just give it a list of source files or directories to
 example.  For example, to examine all files in "src/" and down recursively:
 
-`flawfinder src/`
+~~~~
+flawfinder src/
+~~~~
+
+To examine all files in the *current* directory and down recursively:
+
+~~~~
+flawfinder ./
+~~~~
+
+Hits (findings) are given a risk level from 0 (very low risk) to 5 (high risk),
+By default, findings of risk level 1 or higher are shown.
+You can show only the hits of risk level 4 or higher in the current
+directory and down this way:
+
+~~~~
+flawfinder --minlevel 4 ./
+~~~~
 
 The manual page (flawfinder.1 or flawfinder.pdf) describes how to use
 flawfinder (including its various options) and related information

release_process.md

@@ -15,23 +15,33 @@ setup.py
 index.html
 
 Then run:
-`make test && make test-is-correct` # update version number in tests
+
+~~~~
+make test && make test-is-correct # update version number in tests
+~~~~
 
 ## Test it
 
-`make check` # Run tests in Python 2 and 3
+~~~~
+make check # Run tests in Python 2 and 3
+~~~~
 
 ## Tag version
 
 Once you're sure this is the *real* version, tag it:
 
-`git tag VERSION`
+~~~~
-`git push --tags`
+git tag VERSION
+git push --tags
+~~~~
 
 ## Create tarball
 
 Run:
-`make distribute`
+
+~~~~
+make distribute
+~~~~
 
 
 ## Post tarball
@@ -46,8 +56,12 @@ the usual places:
 
 Create a PyPi distribution package:
 
-`make pypi`
+~~~~
+make pypi
+~~~~
 
 And upload it:
 
-`make upload-pypi`
+~~~~
+make upload-pypi
+~~~~