From 89c44aa13a29d4ee59286d8847804e3adfba39f8 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Wed, 21 Nov 2018 19:51:33 +0100
Subject: [PATCH] [doc] reorder python/README.md sections, group links

---
 python/README.md | 88 ++++++++++++++++++++++++++++++--------------------------
 1 file changed, 47 insertions(+), 41 deletions(-)

diff --git a/python/README.md b/python/README.md
index 629fcb3d..06c8bb61 100644
--- a/python/README.md
+++ b/python/README.md
@@ -15,53 +15,20 @@ efficient tools to process and analyse audio signals, including:
 
 aubio works with both Python 2 and Python 3.
 
-Built with
-----------
-
-The core of aubio is written in C for portability and speed. In addition to
-[NumPy], aubio can be optionally built to use one or more of the following
-libraries:
-
-- media file reading:
-
-    - [ffmpeg](https://ffmpeg.org) / [avcodec](https://libav.org) to decode and
-      read audio from almost any format,
-    - [libsndfile](http://www.mega-nerd.com/libsndfile/) to read audio from
-      uncompressed sound files,
-    - [libsamplerate](http://www.mega-nerd.com/SRC/) to re-sample audio signals
-    - [CoreAudio](https://developer.apple.com/reference/coreaudio) to read all
-      media files supported natively on macOS, iOS, and tvOS.
-
-- hardware acceleration:
-
-    - [Atlas](http://math-atlas.sourceforge.net/) and
-      [Blas](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms),
-      for accelerated vector and matrix computations,
-    - [fftw3](http://fftw.org), to compute fast Fourier Transforms of any size.
-    - [Accelerate](https://developer.apple.com/reference/accelerate) for
-      hardware accelerated FFT and matrix computations on macOs and iOS,
-    - [Intel IPP](https://software.intel.com/en-us/intel-ipp), accelerated
-      vector computation and FFT implementation,
-
-Documentation
--------------
+Links
+-----
 
 - [module documentation][doc_python]
-- [installation][doc_python_install]
+- [installation instructions][doc_python_install]
 - [aubio manual][manual]
 - [aubio homepage][homepage]
+- [issue tracker][bugtracker]
 
-[manual]: https://aubio.org/manual/latest/
-[doc_python]: https://aubio.org/manual/latest/python.html
-[doc_python_install]: https://aubio.org/manual/latest/python_module.html
-[homepage]: https://aubio.org
-[NumPy]: https://www.numpy.org
-
-Demos scripts
--------------
+Demos
+-----
 
-Some examples are available in the [`python/demos`][demos_dir] folder. These
-scripts are small programs written in python and using python-aubio.
+Some examples are available in the [`python/demos`][demos_dir] folder. Each
+script is a command line program which accepts one ore more argument.
 
 **Notes**: installing additional modules is required to run some of the demos.
 
@@ -95,9 +62,48 @@ Use `demo_timestretch_online.py` to slow down `loop.wav`, write the results in
 
     $ python demo_timestretch_online.py loop.wav stretched_loop.wav 0.92
 
+Built with
+----------
+
+The core of aubio is written in C for portability and speed. In addition to
+[NumPy], aubio can be optionally built to use one or more of the following
+libraries:
+
+- media file reading:
+
+    - [ffmpeg] / [avcodec] to decode and read audio from almost any format,
+    - [libsndfile] to read audio from uncompressed sound files,
+    - [libsamplerate] to re-sample audio signals,
+    - [CoreAudio] to read all media formats supported by macOS, iOS, and tvOS.
+
+- hardware acceleration:
+
+    - [Atlas] and [Blas], for accelerated vector and matrix computations,
+    - [fftw3], to compute fast Fourier Transforms of any size,
+    - [Accelerate] for accelerated FFT and matrix computations (macOS/iOS),
+    - [Intel IPP], accelerated vector computation and FFT implementation.
+
+[ffmpeg]: https://ffmpeg.org
+[avcodec]: https://libav.org
+[libsndfile]: http://www.mega-nerd.com/libsndfile/
+[libsamplerate]: http://www.mega-nerd.com/SRC/
+[CoreAudio]: https://developer.apple.com/reference/coreaudio
+[Atlas]: http://math-atlas.sourceforge.net/
+[Blas]: https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms
+[fftw3]: http://fftw.org
+[Accelerate]: https://developer.apple.com/reference/accelerate
+[Intel IPP]: https://software.intel.com/en-us/intel-ipp
+
 [demos_dir]:https://github.com/aubio/aubio/tree/master/python/demos
 [pyaudio]:https://people.csail.mit.edu/hubert/pyaudio/
 [PySoundCard]:https://github.com/bastibe/PySoundCard
 [pyalsaaudio]:https://larsimmisch.github.io/pyalsaaudio/
 [mido]:https://mido.readthedocs.io
+
+[manual]: https://aubio.org/manual/latest/
+[doc_python]: https://aubio.org/manual/latest/python.html
+[doc_python_install]: https://aubio.org/manual/latest/python_module.html
+[homepage]: https://aubio.org
+[NumPy]: https://www.numpy.org
+[bugtracker]: https://github.com/aubio/aubio/issues
 [matplotlib]:https://matplotlib.org/
-- 
2.11.0