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, 105 insertions, 119 deletions

diff --git a/android/README.md b/android/README.md
index cfce3ddaa942..919122df38d1 100644
--- a/android/README.md
+++ b/android/README.md
@@ -1,128 +1,118 @@
-LibreOffice Android
-*******************
+# LibreOffice for Android
 
-Bootstrap
-*********
+## Bootstrap
 
 Contains common code for all projects on Android to bootstrap LibreOffice. In
-addition it is a home to LibreOfficeKit (LOK - see libreofficekit/README) JNI
+addition it is a home to `LibreOfficeKit` (LOK - see `libreofficekit/README.md`) JNI
 classes.
 
-stuff in source directory
-*************************
+## Stuff in Source Directory
 
 LibreOffice Android application - the code is based on Fennec (Firefox for Android).
 It uses OpenGL ES 2 for rendering of the document tiles which are gathered from
 LibreOffice using LOK. The application contains the LibreOffice core in one shared
-library: liblo-native-code.so, which is bundled together with the application.
+library: `liblo-native-code.so`, which is bundled together with the application.
 
-Architecture and Threading
-**************************
+## Architecture and Threading
 
 The application implements editing support using 4 threads:
+
 1. The Android UI thread, we can't perform anything here that would take a considerable
    amount of time.
 2. An OpenGL thread which contains the OpenGL context and is responsible for drawing
    all layers (including tiles) to the screen.
-3. A thread (LOKitThread), that performs LibreOfficeKit calls, which may take more time
+3. A thread (`LOKitThread`), that performs `LibreOfficeKit` calls, which may take more time
    to complete. In addition it also receives events from the soffice thread (see below)
    when the callback emits an event. Events are stored in a blocking queue (thread
    processes events in FCFS order, goes to sleep when no more event is available and
    awakens when there are events in the queue again).
 4. A native thread created by LibreOfficeKit (we call it the soffice thread), where
-   LibreOffice itself runs. It receives calls from LOKitThread, and may emit callback
+   LibreOffice itself runs. It receives calls from `LOKitThread`, and may emit callback
    events as necessary.
 
-LOKitThread
-***********
+## LOKitThread
 
-LOKitThread (org.libreoffice.LOKitThread) communicates with LO via JNI (this can
-be done only for one thread) and processes events (defined in org.libreoffice.LOEvent)
+`LOKitThread` (`org.libreoffice.LOKitThread`) communicates with LO via JNI (this can
+be done only for one thread) and processes events (defined in `org.libreoffice.LOEvent`)
 triggered from UI.
 
-Application Overview
-********************
+## Application Overview
 
-LibreOfficeMainActivity (org.libreoffice.LibreOfficeMainActivity) is the entry point
-of the application - everything starts up and tears down from here (onCreate, onResume,
-onPause, onStart, onStop, onDestroy).
+LibreOfficeMainActivity (`org.libreoffice.LibreOfficeMainActivity`) is the entry point
+of the application - everything starts up and tears down from here (`onCreate`, `onResume`,
+`onPause`, `onStart`, `onStop`, `onDestroy`).
 
-Document view
--------------
+### Document View
 
 From here on one of the most interesting pieces are the classes around document view,
 which includes listening to touch events, recalculating the viewport, tiled handling
 and rendering the layers to the document.
 
-Viewport - the viewport is the currently visible part of the document. It is defined
+`Viewport` - the viewport is the currently visible part of the document. It is defined
            by view rectangle and zoom.
 
-Layers - document view is rendered using many layers. Such layers are: document
+`Layers` - document view is rendered using many layers. Such layers are: document
          background, scroll handles, and also the document tiles.
 
-Document view classes
----------------------
+### Document View Classes
 
-- LayerView (org.mozilla.gecko.gfx.LayerView) is the document view of the application.
-  It uses the SurfaceView (android.view.SurfaceView) as the main surface to draw on
+- `LayerView` (`org.mozilla.gecko.gfx.LayerView`) is the document view of the application.
+  It uses the `SurfaceView` (`android.view.SurfaceView`) as the main surface to draw on
   using OpenGL ES 2.
 
-- GLController (org.mozilla.gecko.gfx.GLController) - holder of the OpenGL context.
+- `GLController` (`org.mozilla.gecko.gfx.GLController`) - holder of the OpenGL context.
 
-- RenderControllerThread (org.mozilla.gecko.gfx.RenderControllerThread) executes the
+- `RenderControllerThread` (`org.mozilla.gecko.gfx.RenderControllerThread`) executes the
   rendering requests through LayerRenderer.
 
-- LayerRenderer (org.mozilla.gecko.gfx.LayerRenderer) renders all the layers.
+- `LayerRenderer` (`org.mozilla.gecko.gfx.LayerRenderer`) renders all the layers.
 
-- GeckoLayerClient (org.mozilla.gecko.gfx.GeckoLayerClient) is the middle man of the
+- `GeckoLayerClient` (`org.mozilla.gecko.gfx.GeckoLayerClient`) is the middle man of the
   application, which connects all the bits together. It is the document view layer
   holder so the any management (including tiled rendering) usually go through this
-  class. It listens to draw requests and viewport changes from PanZoomController
+  class. It listens to draw requests and viewport changes from `PanZoomController`
   (see "Touch events").
 
-Touch events, scrolling and zooming
------------------------------------
+### Touch Events, Scrolling and Zooming
 
-The main class that handles the touch event, scrolling and zooming is JavaPanZoomController
-org.mozilla.gecko.gfx.JavaPanZoomController (implementation of PanZoomController interface).
+The main class that handles the touch event, scrolling and zooming is `JavaPanZoomController`
+`org.mozilla.gecko.gfx.JavaPanZoomController` (implementation of `PanZoomController` interface).
 When the user performs a touch action, the document view needs to change, which means the
-viewport changes. JavaPanZoomController changes the viewport and signals the change through
-PanZoomTarget (org.mozilla.gecko.gfx.PanZoomTarget).
+viewport changes. `JavaPanZoomController` changes the viewport and signals the change through
+`PanZoomTarget` (`org.mozilla.gecko.gfx.PanZoomTarget`).
 
-TiledRendering
---------------
+### Tiled Rendering
 
 Tiled rendering is a technique that splits the document to bitmaps of same size (typically
 256x256) which are fetched on demand.
 
-In the application the ComposedTileLayer (org.mozilla.gecko.gfx.ComposedTileLayer) is the
+In the application the `ComposedTileLayer` (`org.mozilla.gecko.gfx.ComposedTileLayer`) is the
 layer responsible for tracking and managing the tiles. Tiles are in this case also layers
-(sub layers?) implemented in SubTile (org.mozilla.gecko.gfx.SubTile), where each one is
+(sub layers?) implemented in `SubTile` (`org.mozilla.gecko.gfx.SubTile`), where each one is
 responsible for one tile bitmap (actually OpenGL texture once it has been uploaded).
 
-When the viewport changes, the request for tile rechecking is send to LOKitThread (see
+When the viewport changes, the request for tile rechecking is send to `LOKitThread` (see
 LOKitThread#tileReevaluationRequest), where the tiles are rechecked, add and removed if
 necessary.
 
-CompositeTileLayer is actually an abstract class, which has two implementations. One is
-DynamicTileLayer (org.mozilla.gecko.gfx.DynamicTileLayer), which is used for main tile
-view of the document, and FixedZoomTileLayer (org.mozilla.gecko.gfx.FixedZoomTileLayer),
+`CompositeTileLayer` is actually an abstract class, which has two implementations. One is
+`DynamicTileLayer` (`org.mozilla.gecko.gfx.DynamicTileLayer`), which is used for main tile
+view of the document, and `FixedZoomTileLayer` (`org.mozilla.gecko.gfx.FixedZoomTileLayer`),
 which just renders the tiles at a fixed zoom level. This is then used as a background
 low resolution layer.
 
-Tile invalidation
------------------
+### Tile Invalidation
 
 Tile can change in LibreOffice when user changes the content (adds, removes text or changes
 the properties). In this case, an invalidation rectangle is signaled from LibreOffice, which
-includes a rectangle that needs to be invalidated. In this case LOKitThread gets this request
+includes a rectangle that needs to be invalidated. In this case `LOKitThread` gets this request
 via callback, and rechecks all tiles if they need to be invalidated. For more details see
 LOKitThread#tileInvalidation).
 
-Editing
-*******
+## Editing
 
 For editing there are 2 coarse tasks that the LibreOffice app must do:
+
 1. send input events to LibreOffice core (keyboard, touch and mouse)
 2. listen to messages (provided via callback) from LibreOffice core and react accordingly
 
@@ -131,38 +121,35 @@ LO core follows. For example: when the user writes to the keyboard, key event is
 an invalidation request from LO core follows. When user touches an image, a mouse event is
 sent, and a "new graphic selection" message from LO core follows.
 
-All keyboard and touch events are sent to LOKitThread as LOEvents. In LOKitThread they are
-processed and sent to LibreOffice core. The touch events originate in JavaPanZoomController,
-the keyboard events in LOKitInputConnectionHandler (org.libreoffice.LOKitInputConnectionHandler),
+All keyboard and touch events are sent to `LOKitThread` as `LOEvents`. In `LOKitThread` they are
+processed and sent to LibreOffice core. The touch events originate in `JavaPanZoomController`,
+the keyboard events in `LOKitInputConnectionHandler` (`org.libreoffice.LOKitInputConnectionHandler`),
 however there are other parts too - depending on the need.
 
-InvalidationHandler (org.libreoffice.InvalidationHandler) is the class that is responsible
+`InvalidationHandler` (`org.libreoffice.InvalidationHandler`) is the class that is responsible
 to process messages from LibreOffice core and to track the state.
 
-Overlay
-*******
+## Overlay
 
 Overlay elements like cursor and selections aren't drawn by the LO core, instead the core
 only provides data (cursor position, selection rectangles) and the app needs to draw them.
-DocumentOverlay (org.libreoffice.overlay.DocumentOverlay) and DocumentOverlayView
-(org.libreoffice.overlay.DocumentOverlayView) are the classes that provide the overlay over
+`DocumentOverlay` (`org.libreoffice.overlay.DocumentOverlay`) and `DocumentOverlayView`
+(`org.libreoffice.overlay.DocumentOverlayView`) are the classes that provide the overlay over
 the document, where selections and the cursor is drawn.
 
 
-Icons
-*****
+## Icons
 
 App uses material design icons available at [1].
 
 
-[1] - https://www.google.com/design/icons/
+[1] - <https://www.google.com/design/icons/>
 
-Emulator and debugging notes
-****************************
+## Emulator and Debugging Notes
 
-For instructions on how to build for Android, see README.cross.
+For instructions on how to build for Android, see `README.cross`.
 
-* Getting something running
+### Getting Something Running
 
 Attach your device, so 'adb devices' shows it. Then run:
 
@@ -173,7 +160,7 @@ Attach your device, so 'adb devices' shows it. Then run:
 and if all goes well, you should have some nice debug output to enjoy when you
 start the app.
 
-* Using the emulator
+### Using the Emulator
 
 Create an AVD in the android UI, don't even try to get the data partition size
 right in the GUI, that is doomed to producing an AVD that doesn't work.
@@ -183,103 +170,102 @@ Instead start it from the console:
 
 where <Name> is the literal name of the AVD that you entered.
 
-[ In order to have proper acceleration, you need the 32-bit libGL.so:
+[ In order to have proper acceleration, you need the 32-bit `libGL.so`:
 
         sudo zypper in Mesa-libGL-devel-32bit
 
 and run emulator-arm after the installation. ]
 
-Then you can run ant/adb as described above.
+Then you can run `ant`/`adb` as described above.
 
 After a while of this loop you might find that you have lost a lot of
-space on your emulator's or device's /data volume. You can do:
+space on your emulator's or device's `/data` volume. You can do:
 
         adb shell stop; adb shell start
 
-Debugging
----------
+## Debugging
 
-First of all, you need to configure the build with --enable-debug or
---enable-dbgutil.  You may want to provide --enable-symbols to limit debuginfo,
-like --enable-symbols="sw/" or so, in order to fit into the memory
+First of all, you need to configure the build with `--enable-debug` or
+`--enable-dbgutil`.  You may want to provide `--enable-symbols` to limit debuginfo,
+like `--enable-symbols="sw/"` or so, in order to fit into the memory
 during linking.
 
 Building with all symbols is also possible but the linking is currently
 slow (around 10 to 15 minutes) and you need lots of memory (around 16GB + some
 swap).
 
-* Using ndk-gdb
+### Using ndk-gdb
 
-Direct support for using ndk-gdb has been removed from the build system. It is
+Direct support for using `ndk-gdb` has been removed from the build system. It is
 recommended that you give the lldb debugger a try that has the benefit of being
 nicely integrated into Android Studio (see below for instructions).
-If you nevertheless want to continue using ndk-gdb, use the following steps
-that are described in more detail here: https://stackoverflow.com/a/10539883
+If you nevertheless want to continue using `ndk-gdb`, use the following steps
+that are described in more detail here: <https://stackoverflow.com/a/10539883>
 
-    - add android:debuggable="true" to AndroidManifest.xml
-    - push gdbserver to device, launch and attach to application
-    - forward debugging port from host to device
-    - launch matching gdb on host and run following setup commands:
+- add `android:debuggable="true"` to `AndroidManifest.xml`
+- push `gdbserver` to device, launch and attach to application
+- forward debugging port from host to device
+- launch matching gdb on host and run following setup commands:
         - set solib-search-path obj/local/<appAbi>
         - file obj/local/<appAbi>/liblo-native-code.so
         - target remote :<portused>
 
 Pretty printers aren't loaded automatically due to the single shared
 object, but you can still load them manually. E.g. to have a pretty-printer for
-rtl::OString, you need:
+`rtl::OString`, you need:
 
         (gdb) python sys.path.insert(0, "/master/solenv/gdb")
         (gdb) source /master/instdir/program/libuno_sal.so.3-gdb.py
 
-* Using Android Studio (and thus lldb)
+### Using Android Studio (and Thus lldb)
 
-Note that lldb might not yield the same results as ndk-gdb. If you suspect a
-problem with lldb, you can try to manually use ndk-gdb as described above.
-Using lldb from within Android Studio is more comfortable though and works like this:
+Note that lldb might not yield the same results as `ndk-gdb`. If you suspect a
+problem with `lldb`, you can try to manually use `ndk-gdb` as described above.
+Using `lldb` from within Android Studio is more comfortable though and works like this:
 
-    - open android/source/build.gradle in Android Studio via File|New → Import Project
-    - make sure you select the right build variant (strippedUIDebug is what you want)
-    - use Run|Edit Configurations to create a new configuration of type "Android Native"
-        - on tab "General" pick module "source"
-        - on tab "Native Debugger" add android/obj/local/<hostarch> to
-          the Symbol directories
-        - on the LLDB startup commands tab add
-          "command script import /path/to/solenv/lldb/libreoffice/LO.py"
-          to get some pretty printing hooks for the various string classes
+- open `android/source/build.gradle` in Android Studio via File|New → Import Project
+- make sure you select the right build variant (`strippedUIDebug` is what you want)
+- use Run|Edit Configurations to create a new configuration of type "Android Native"
+	- on tab "General" pick module "source"
+	- on tab "Native Debugger" add `android/obj/local/<hostarch>` to
+	the Symbol directories
+	- on the LLDB startup commands tab add
+	"command script import `/path/to/solenv/lldb/libreoffice/LO.py`"
+	to get some pretty printing hooks for the various string classes
 
 Then you can select your new configuration and use Run | Debug to launch it.
-Note that lldb doesn't initially stop execution, so if you want to add
+Note that `lldb` doesn't initially stop execution, so if you want to add
 breakpoints using lldb prompt, you manually have to pause execution, then you
 can switch to the lldb tab and add your breakpoints. However making use of the
 editor just using File|Open .. to open the desired file in Android Studio and
 then toggling the breakpoint by clicking on the margin is more comfortable.
 
-* Debugging the Java part
+### Debugging the Java Part
 
-Open android/source/build.gradle in Android studio via File|New → Import
+Open `android/source/build.gradle` in Android studio via File|New → Import
 Project and you can use Android Studio's debugging interface.
 Just make sure you pick the correct build variant (strippedUIDebug)
 
 The alternative is to use the jdb command-line debugger. Steps to use it:
 
-1) Find out the JDWP ID of a debuggable application:
+1. Find out the JDWP ID of a debuggable application:
 
         adb jdwp
 
-From the list of currently active JDWP processes, the last number is the just
+    From the list of currently active JDWP processes, the last number is the just
 started debuggable application.
 
-2) Forward the remote JDWP port/process ID to a local port:
+2. Forward the remote JDWP port/process ID to a local port:
 
         adb forward tcp:7777 jdwp:31739
 
-3) Connect to the running application:
+3. Connect to the running application:
 
         jdb -sourcepath src/java/ -attach localhost:7777
 
 Assuming that you're already in the LOAndroid3 directory in your shell.
 
-* Debugging the missing services
+### Debugging the Missing Services
 
 Android library only include essential services that are compiled for
 LibreOffice in order to reduce the size of the apk. When developing,
@@ -287,40 +273,40 @@ some services might become useful and we should add those services
 to the combined library.
 
 In order to identify missing services, we need to be able to receive
-SAL_INFO from cppuhelper/source/shlib.cxx in logcat and therefore identify
+`SAL_INFO` from `cppuhelper/source/shlib.cxx` in logcat and therefore identify
 what services are missing. To do so, you may want add the following
 when configuring the build.
 
     --enable-symbols="cppuhelper/ sal/"
 
-[TODO: This is nonsense. --enable-symbols enables the -g option, not SAL_INFO.
-Perhaps this was a misunderstanding of meaning of --enable-selective-debuginfo,
+[TODO: This is nonsense. `--enable-symbols` enables the `-g` option, not `SAL_INFO`.
+Perhaps this was a misunderstanding of meaning of `--enable-selective-debuginfo`,
 the old name for the option.]
 
 Which services are combined in the android lib is determined by
 
     solenv/bin/native-code.py
 
-* Common Errors / Gotchas
+### Common Errors / Gotchas
 
-lo_dlneeds: Could not read ELF header of /data/data/org.libreoffice...libfoo.so
-        This (most likely) means that the install quietly failed, and that
-the file is truncated; check it out with adb shell ls -l /data/data/...
+    lo_dlneeds: Could not read ELF header of /data/data/org.libreoffice...libfoo.so
+This (most likely) means that the install quietly failed, and that
+the file is truncated; check it out with `adb shell ls -l /data/data/...`
 
-* Startup details
+### Startup Details
 
 All Android apps are basically Java programs. They run "in" a Dalvik
 (or on Android 5 or newer - ART) virtual machine. Yes, you can also
 have apps where all *your* code is native code, written in a compiled
 language like C or C++. But also such apps are actually started
-by system-provided Java bootstrapping code (NativeActivity) running
+by system-provided Java bootstrapping code (`NativeActivity`) running
 in a Dalvik VM.
 
 Such a native app (or actually, "activity") is not built as a
-executable program, but as a shared object. The Java NativeActivity
+executable program, but as a shared object. The Java `NativeActivity`
 bootstrapper loads that shared object with dlopen.
 
-Anyway, our current "experimental" apps are not based on NativeActivity.
+Anyway, our current "experimental" apps are not based on `NativeActivity`.
 They have normal Java code for the activity, and just call out to a single,
-app-specific native library (called liblo-native-code.so) to do all the
+app-specific native library (called `liblo-native-code.so`) to do all the
 heavy lifting.