Updated README.md files to represent current code / use Markdown format

Previously, all of the README files have been renamed to README.md
and now, the contents of these files were changed to use Markdown
format. Other than format inconsistency, some README.md files lacked
information about modules, or were out of date. By using LibreOffice
/ OpenOffice wiki and other documentation websites, these files were
updated. Now every README.md file has a title, and some description.
The top-level README.md file is changed to add links to the modules.
The result of processing the Markdown format README.md files can be
seen at: https://docs.libreoffice.org/

Change-Id: Ic3b0c3c064a2498d6a435253b041df010cd7797a
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/113424
Tested-by: Jenkins
Reviewed-by: Michael Stahl <michael.stahl@allotropia.de>
Reviewed-by: Adolfo Jayme Barrientos <fitojb@ubuntu.com>

1 files changed, 46 insertions, 43 deletions

diff --git a/vcl/README.md b/vcl/README.md
index e0944688f2f3..25498991e4fb 100644
--- a/vcl/README.md
+++ b/vcl/README.md
@@ -1,58 +1,61 @@
-Visual Class Library is responsible for the widgets (windowing, buttons, controls, file-pickers etc.), operating system abstraction, including basic rendering (e.g. the output device).
+# Visual Class Library (VCL)
+
+Visual Class Library (VCL) is responsible for the widgets (windowing, buttons, controls,
+file-pickers etc.), operating system abstraction, including basic rendering (e.g. the output device).
 
 It should not be confused with Borland's Visual Component Library, which is entirely unrelated.
 
 VCL provides a graphical toolkit similar to gtk+, Qt, SWING etc.
 
-source/
++ source/
 	+ the main cross-platform chunk of source
 
-inc/
++ inc/
 	+ cross-platform abstraction headers
 
-headless/
++ headless/
 	+ a backend renderer that draws to bitmaps
 
-android/
++ android/
 	+ Android backend
 
-osx/
++ osx/
 	+ macOS backend
 
-ios/
++ ios/
 	+ iOS backend
 
-quartz/
++ quartz/
 	+ code common to macOS and iOS
 
-win/
++ win/
 	+ Windows backend
 
-qt5/
++ qt5/
 	+ Qt5 (under construction)
 
-unx/
++ unx/
 	+ X11 backend and its sub-platforms
-	gtk3/
-		+ GTK3 support
-	kf5/
-		+ KF5 support (based on qt5 VCL plugin mentioned above)
-	gtk3_kde5/
-		+ GTK3 support with KDE5 file pickers (alternative to native kf5 one)
-	generic/
-		+ raw X11 support
-
-		plugadapt/
+		+ gtk3/
+			+ GTK3 support
+		+ kf5/
+			+ KF5 support (based on qt5 VCL plugin mentioned above)
+		+ gtk3_kde5/
+			+ GTK3 support with KDE5 file pickers (alternative to native kf5 one)
+		+ generic/
+			+ raw X11 support
+
+		+ plugadapt/
 			+ pluggable framework to select correct unx backend
 
-		dtrans/
+		+ dtrans/
 			+ "data transfer" - clipboard handling
 			+ http://stackoverflow.com/questions/3261379/getting-html-source-or-rich-text-from-the-x-clipboard
 			  for tips how to show the current content of the
 			  clipboard
 
 
-How the platform abstraction works
++ How the platform abstraction works
 
 	+ InitVCL calls 'CreateSalInstance'
 		+ this is implemented by the compiled-in platform backend
@@ -72,24 +75,24 @@ LibreOffice (and OpenOffice).
 
 "svp" stands for "StarView Plugin".
 
-== COM threading ==
+## COM Threading
 
 The way COM is used in LO generally:
 - vcl puts main thread into Single-threaded Apartment (STA)
-- oslWorkerWrapperFunction() puts every thread spawned via oslCreateThread()
+- oslWorkerWrapperFunction() puts every thread spawned via `oslCreateThread()`
   into MTA (free-threaded)
 
-== GDIMetafile ==
+# GDIMetafile
 
 GDIMetafile is a vector drawing representation that corresponds directly
 to the SVM (StarView Metafile) format; it is extremely important as
 an intermediate format in all sorts of drawing and printing operations.
 
-There is a class MetafileXmlDump in include/vcl/mtfxmldump.hxx that
+There is a class `MetafileXmlDump` in `include/vcl/mtfxmldump.hxx` that
 can store a GDIMetafile as XML, which makes debugging much easier
 since you can just use "diff" to see changes.
 
-== EMF+ ==
+## EMF+
 
 emf+ is vector file format used by MSO and is successor of wmf and
 emf formats. see
@@ -104,7 +107,7 @@ because GDIMetafile is missing features we need (mostly related to
 transparency, argb colors, etc.)
 
 emf/wmf is translated to GDIMetafile in import filter
-vcl/source/filter/wmf and so special handling ends here
+`vcl/source/filter/wmf` and so special handling ends here
 
 emf+ is encapsulated into GDIMetafile inside comment records and
 parsed/rendered later, when it reaches cppcanvas. It is parsed and
@@ -113,9 +116,9 @@ emf+-only and emf+-dual files. dual files contains both types of
 records (emf and emf+) for rendering the images. these can used also
 in applications which don't know emf+. in that case we must ignore
 emf records and use emf+ for rendering. for more details see
-documentation
+the documentation.
 
-parsing:
+## Parsing
 
  wmf/emf filter --> GDI metafile with emf+ in comments --> cppcanvas metafile renderer
 
@@ -141,7 +144,7 @@ yet. but there were already few cases where we first though that the
 problem might be because of broken emf+ part. so far it always turned
 out to be another problem.
 
-rendering:
+## Rendering
 
  before
 
@@ -157,16 +160,16 @@ using that bitmap later in code using vcl API.
 EMF+ implementation has some extensive logging, best if you do a dbgutil
 build, and then
 
-export SAL_LOG=+INFO.cppcanvas.emf+INFO.vcl.emf
+    export SAL_LOG=+INFO.cppcanvas.emf+INFO.vcl.emf
 
 before running LibreOffice; it will give you lots of useful hints.
 
 You can also fallback to EMF (from EMF+) rendering via
 
-export EMF_PLUS_DISABLE=1
+    export EMF_PLUS_DISABLE=1
 
 
-== Printing/PDF export ==
+## Printing/PDF Export
 
 Printing from Writer works like this:
 
@@ -174,7 +177,7 @@ Printing from Writer works like this:
 2) in drawinglayer, a VclMetafileProcessor2D is used to record everything on
    the page (because the OutputDevice has been set up to record a GDIMetaFile)
 3) the pages' GDIMetaFiles are converted to PDF by the vcl::PDFWriter
-   in vcl/source/gdi/pdfwriter*
+   in `vcl/source/gdi/pdfwriter*`
 
 Creating the ODF thumbnail for the first page works as above except step 3 is:
 
@@ -183,10 +186,10 @@ Creating the ODF thumbnail for the first page works as above except step 3 is:
 On-screen display differs in step 1 and 2:
 
 1) the VCL Window gets invalidated somehow and paints itself
-2) in drawinglayer, a VclPixelProcessor2D is used to display the content
+2) in drawinglayer, a `VclPixelProcessor2D` is used to display the content
 
 
-=== Debugging PDF export ===
+### Debugging PDF export
 
 Debugging the PDF export becomes much easier when
 compression is disabled (so the PDF file is directly readable) and
@@ -195,14 +198,14 @@ generated the following PDF content.
 
 The compression can be disabled even using an env. var:
 
-export VCL_DEBUG_DISABLE_PDFCOMPRESSION=1
+    export VCL_DEBUG_DISABLE_PDFCOMPRESSION=1
 
 To de-compress the contents of a PDF file written by a release build or
 other programs, use the "pdfunzip" tool:
 
-bin/run pdfunzip input.pdf output.pdf
+    bin/run pdfunzip input.pdf output.pdf
 
-=== SolarMutexGuard ===
+### SolarMutexGuard
 
 The solar mutex is the "big kernel lock" of LibreOffice, a global one. It's a
 recursive mutex, so it's allowed to take the lock on the same thread multiple
@@ -223,10 +226,10 @@ This way you ensure that code (not prepared for multithreading) is still
 executed only on a single thread.
 
 In case you expect that your caller takes the solar mutex, then you can use
-the DBG_TESTSOLARMUTEX() macro to assert that in dbgutil builds.
+the `DBG_TESTSOLARMUTEX()` macro to assert that in dbgutil builds.
 
 Event listeners are a special (but frequent) case of the "never call out with
-a mutex (SolarMutex or other) locked" fundamental rule:
+a mutex (`SolarMutex` or other) locked" fundamental rule:
 
 - UNO methods can be called from multiple threads, so most implementations
   take the solar mutex as their first action when necessary.