Improve README/CONTRIBUTING files

Use reStructuredText to allow HTML formatting while still maintaining
clarity in the raw text.

CONTRIBUTING

@@ -1,64 +0,0 @@
-Contributing Information:
-
- - Our bug tracker is located at (currently linked to forum accounts):
-       https://obsproject.com/mantis/
-
- - Development forums are currently located at:
-       https://obsproject.com/forum/list/general-development.21/
-
- - Development IRC channel is primarily #obs-dev on QuakeNet
- 
- - To contribute translations, see:
-       https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
-
-
-Contributing Guidelines:
-
- - Code and commits will be reviewed.  Reviews will be blunt and honest, and
-   your change probably won't go through the first time, or may be outright
-   rejected.  It may require many revisions before changes are finally
-   accepted.
-
- - If you want to avoid doing a lot of work only to have it rejected, discuss
-   what you want to change it in the main channels/forums/mailing lists before
-   actually working on it.  Open source requires thick skin.  Please don't be
-   discouraged if your changes don't go through, learn from it and get better.
-
- - Coding style is Linux-style KNF (kernel normal form).  This means K&R, 80
-   columns max, preferable maximum function length of approximately 42 lines, 8
-   character width tabs, lower_case_names, etc.  I chose this for the sake of
-   the project.  Don't argue about it, just do it.  It takes no time to do.
-
-   See https://www.kernel.org/doc/Documentation/CodingStyle for a general
-   guideline (though not necessarily a rulebook, for example we allow the use
-   of boolean return values instead of ints for failure).
-
-   NOTE: C++ is an exception to the lower_case_only rule, CamelCase is
-   encouraged (though not required) to distinguish it from C code.  Just a
-   personal and subjective stylistic thing on my part.
-
- - Commits are not just changes to code; they should also be treated as
-   annotation to code.  For that reason, do not put unrelated changes in a
-   single commit.  Separate out different changes in to different commits, and
-   make separate pull requests for unrelated changes.  Commits should be
-   formatted with the 50/72 standard, and should be descriptive and concise.
-   See http://chris.beams.io/posts/git-commit/ for a summary of how to make
-   good commit messages.
-
- - Core code is C only (unless there's an operating system specific thing that
-   absolutely requires another language).
-
- - Modules and UI may use C, C++, or Objective-C (for apple), though please try
-   to use C unless an API you're using requires C++ or Objective-C (such as
-   windows COM classes, or apple Objective-C APIs).
-
- - If you don't quite know what to work on and just want to help, the bug
-   tracker has a list of things that need to be worked on.
-
- - Try to respect the wishes of the author(s)/maintainer(s).  A good maintainer
-   will always listen, and will often ask others on the project for their
-   opinions, but don't expect things to be completely democratic.
-
- - Do not use dependencies for the sake of convenience.  There's enough
-   dependencies as it is.  Use them only if you absolutely have to depend on
-   them.

CONTRIBUTING.rst

@@ -0,0 +1,90 @@
+Contributing
+============
+
+Quick Links for Contributing
+----------------------------
+
+ - Compiling and building OBS Studio:
+   https://github.com/jp9000/obs-studio/wiki/Install-Instructions
+
+ - Our bug tracker (linked to forum accounts):
+   https://obsproject.com/mantis/
+
+ - Development IRC channel: #obs-dev on QuakeNet
+ 
+ - Development forum:
+   https://obsproject.com/forum/list/general-development.21/
+
+ - To contribute language translations, do not make pull requests.
+   Instead, use crowdin.  Read here for more information:
+   https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
+
+Coding Guidelines
+-----------------
+
+ - OBS Studio uses kernel normal form (linux variant), for more
+   information, please read here:
+   https://www.kernel.org/doc/Documentation/CodingStyle
+
+ - Avoid trailing spaces.  To view trailing spaces before making a
+   commit, use "git diff" on your changes.  If colors are enabled for
+   git in the command prompt, it will show you any whitespace issues
+   marked with red.
+
+ - Tabs for indentation, spaces for alignment.  Tabs are treated as 8
+   columns wide.
+
+ - 80 columns max
+
+Commit Guidlines
+----------------
+
+ - OBS Studio uses the 50/72 standard for commits.  50 characters max
+   for the title (excluding module prefix), an empty line, and then a
+   full description of the commit, wrapped to 72 columns max.  See this
+   link for more information: http://chris.beams.io/posts/git-commit/
+
+ - Make sure commit titles are always in present tense, and are not
+   followed by punctuation.
+
+ - Prefix commit titles with the module name, followed by a colon and a
+   space (unless modifying a file in the base directory).  When
+   modifying cmake modules, prefix with "cmake".  So for example, if you
+   are modifying the obs-ffmpeg plugin::
+
+     obs-ffmpeg: Fix bug with audio output
+
+   Or for libobs::
+
+     libobs: Fix source not displaying
+
+ - If you still need examples, please view the commit history.
+
+Headers
+-------
+
+  There's no formal documentation as of yet, so it's recommended to read
+  the headers (which are heavily commented) to learn the API.
+
+  Here are the most important headers to check out::
+
+    libobs/obs.h                Main header
+
+    libobs/obs-module.h         Main header for plugin modules
+
+    libobs/obs-source.h         Creating video/audio sources
+
+    libobs/obs-output.h         Creating outputs
+
+    libobs/obs-encoder.h        Implementing encoders
+
+    libobs/obs-service.h        Implementing custom streaming services
+
+    libobs/graphics/graphics.h  Graphics API
+
+    UI/obs-frontend-api/obs-frontend-api.h
+                                Front-end API
+
+  If you would like to learn from example, examine the default plugins
+  (in the <plugins> subdirectory).  All features of OBS Studio are
+  implemented as plugins.

README

@@ -1,174 +0,0 @@
-
-What is OBS?
-
-  This project is a rewrite of what was formerly known as "Open Broadcaster
-  Software", software originally designed for recording and streaming live
-  video content, efficiently.
-
-Bug Tracker: https://obsproject.com/mantis/
-
-   We are no longer using GitHub issues!  Please use Mantis, and only report
-   bugs and major issues.  Do NOT use mantis to ask questions or request
-   features, please keep that to the forums.
-
-   Forum accounts are now linked to Mantis Bug Tracker.  To use the bug
-   tracker, simply log in to the forums and then go to the bug tracker link
-   above.
-
-What's the goal of rewriting OBS?
-
- - Make it multiplatform.  Use multiplatform libraries/functions/classes where
-   possible to allow this.  Multi-platform support was one of the primary
-   reasons for the rewrite.  This also means using a UI toolkit will be
-   necessary for user interface.  It also means allowing the use of OpenGL as
-   well as Direct3D.
-
- - Separate the application from the core, allowing custom application of
-   the core if desired, and easier extending of the user interface.
-
- - Simplify complex systems to not only make it easier to use, but easier to
-   maintain.
-
- - Write a better core API, and design the entire system to be modular.
-
- - Now that we have much more experience, improve the overall design of all
-   the subsystems/API, and minimize/eliminate design flaws.  Make it so we can
-   do all the things we've had trouble with before, such as custom outputs,
-   multiple outputs at once, better handling of inputs, custom services.
-
- - Make a better/cleaner code base, use better coding standards, use standard
-   libraries where possible (not just STL and C standard library, but also
-   things like ffmpeg as well), and improve maintainability of the project as a
-   whole.
-
- - Implement a new API-independent shader/effect system allowing better and
-   easier shaders usage and customization without having to duplicate shader
-   code.
-
- - Better device support.  Again, I didn't know what I was getting into when
-   I originally started writing code for devices.  It evolved into a totally
-   convoluted mess.  I would have improved the existing device plugin code, but
-   it was just all so fundamentally bad and flawed that it would have been
-   detrimental to progression to continue working on it rather than rewrite it.
-
-
-What was wrong with the original OBS?
-
-  The original OBS was rewritten not because it was bad, at least in terms of
-  optimization.  Optimization and graphics are things I love.  However, there
-  were some serious problems with the code and design that were deep and
-  fundamental, which prevented myself and other developers from being able to
-  improve/extend the application or add new features very easily.
-
-  First, the design flaws:
-
-    - The original OBS was completely and hopelessly hard-coded for windows,
-      and only windows.  It was just totally impossible to use it on other
-      systems.
-
-    - All the sub-systems were written before I really knew what I was getting
-      into.  When I started the project, I didn't really fully comprehend the
-      scope of what I would need or how to properly design the project.  My
-      design and plans for the application were just to write something that
-      would "stream games and a webcam, with things like overlays and such."
-      This turned out fine for most casual gamers and streamers (and very
-      successful), but left anyone wanting to do anything more advanced left
-      massively wanting.
-
-    - Subsystems and core functionalities intermingled in such a way that it
-      was a nightmare to get proper custom functionality out of it.  Things
-      like QSV had to be meshed in with the main encoding loop, and it just
-      made things a nightmare to deal with.  Custom outputs were nigh
-      impossible.
-
-    - The API was poorly designed because most of it came after I originally
-      wrote the application, it was more of an afterthought, and plugin API
-      would routinely break for plugin developers due to changing C++
-      interfaces (one of the reasons the core is now C).
-
-    - API was intermeshed with the main executable.  The OBSApi DLL was
-      nothing more than basically this mutant growth upon OBS.exe that allowed
-      plugin developers to barely write plugins, but all the important API
-      code was actually stored in the executable.  Navigation was a total mess.
-
-    - The graphics subsystem, while not bad, was incomplete, and though far
-      easier to use than bare D3D, wasn't ideal, and was hard-coded for D3D
-      specifically.
-
-    - The devices and audio code was poor, I had no idea what I was getting into
-      when I started writing them in.  I did not realize beforehand all the
-      device-specific quirks that each device/system could have.  Some devices
-      had bad timing and quirks that I never anticipated while writing them.
-      I struggled with devices, and my original design for the audio subsystem
-      for example morphed over and over into an abomination that, though works,
-      is basically this giant duct-taped zombie monster.
-
-    - Shaders were difficult to customize because they had to be duplicated if
-      you wanted slightly different functionality that required more than just
-      changing shader constants.
-
-    - Orientation of sources was fixed, and required special code for each
-      source to do any custom modification of rotation/position/scale/etc.
-      This is one of those fundamental flaws that I look back on and regret, as
-      it was a stupid idea from the beginning.  I originally thought I could
-      get more accurate source position/sizes, but it just turned out to be
-      totally bad.  Should have been matrices from the beginning just like with
-      a regular 3D engine.
-
-  Second, the coding flaws:
-
-    - The coding style was inconsistent.
-
-    - C++98, C-Style C++, there was no exception usage, no STL.  C++ used
-      poorly.
-
-    - Not Invented Here Syndrome everywhere.  Custom string functions/classes,
-      custom templates, custom everything everywhere.  To be fair, it was all
-      hand-me-down code from the early 2000s that I had become used to, but
-      that was no excuse -- C-standard libraries and the STL should have been
-      used from the beginning over anything else.  That doesn't mean to say
-      that using custom stuff is always bad, but doing it to the extent I did
-      definitely was.  Made it horrible to maintain as well, required extra
-      knowledge for plugin developers and anyone messing with the code.
-
-    - Giant monolithic classes everywhere, the main OBS class was paricularly
-      bad in this regard.  This meant navigation was a nightmare, and no one
-      really knew where to go or where to add/change things.
-
-    - Giant monolithic functions everywhere.  This was particularly bad
-      because it meant that functions became harder to debug and harder to
-      keep track of what was going on in any particular function at any given
-      time.  These large functions, though not inefficient, were delicate and
-      easily breakable.  (See OBS::MainCaptureLoop for a nightmarish example,
-      or the listbox subclass window procedure in WindowStuff.cpp)
-
-    - Very large file sizes with everything clumped up into single files (for
-      another particularly nightmarish example, see WindowStuff.cpp)
-
-    - Bad formatting.  Code could go beyond 200 columns in some cases, making
-      it very unpleasant to read with many editors.  Spaces instead of tabs,
-      K&R mixed with allman (which was admittedly my fault).
-
-
-New (actual) coding guidelines
-
- - For the C code (especially in the core), guidelines are pretty strict K&R,
-   kernel style.  See the linux kernel "CodingStyle" document for more
-   information.  That particular coding style guideline is for more than just
-   style, it actually helps produce a better overall code base.
-
- - For C++ code, I still use CamelCase instead of all_lowercase just because
-   I prefer it that way, it feels right with C++ for some reason.  It also
-   helps make it distinguishable from C code.
-
- - I've started using 8-column tabs for almost everything -- I really
-   personally like it over 4-column tabs.  I feel that 8-column tabs are very
-   helpful in preventing large amounts of indentation.  A self-imposed
-   limitation, if you will.  I also use actual tabs now, instead of spaces.
-   Also, I feel that the K&R style looks much better/cleaner when viewed with
-   8-column tabs.
-
- - Preferred maximum columns: 80.  I've also been doing this because in
-   combination with 8-column tabs, it further prevents large/bad functions
-   with high indentation.  Another self-imposed limitation.  Also, it makes
-   for much cleaner viewing in certain editors that wrap (like vim).

README.rst

@@ -0,0 +1,44 @@
+OBS Studio <https://obsproject.com>
+===================================
+
+What is OBS Studio?
+-------------------
+
+  OBS Studio is software designed for capturing, compositing, encoding,
+  recording, and streaming video content, efficiently.
+
+  It's distributed under the GNU General Public License v2 - see the
+  accompanying COPYING file for more details.
+
+Quick Links
+-----------
+
+ - Website: https://obsproject.com
+
+ - Help/Guides: https://github.com/jp9000/obs-studio/wiki
+
+ - Forums: https://obsproject.com/forum/
+
+ - Build Instructions: https://github.com/jp9000/obs-studio/wiki/Install-Instructions
+
+ - Bug Tracker: https://obsproject.com/mantis/
+
+   (Note: The bug tracker is linked to forum accounts.  To use the bug
+   tracker, log in to a forum account)
+
+Contributing
+------------
+
+ - If you wish to contribute code to the project, please make sure read
+   the coding and commit guidelines:
+   https://github.com/jp9000/obs-studio/blob/master/CONTRIBUTING.rst
+
+ - If you wish to contribute translations, do not submit pull requests.
+   Instead, please use Crowdin.  For more information read this thread:
+   https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
+
+ - Other ways to contribute are by helping people out with support on
+   our forums or in our community chat.  Please limit support to topics
+   you fully understand -- bad advice is worse than no advice.  When it
+   comes to something that you don't fully know or understand, please
+   defer to the official help or official channels.