diff options
| author | Hossein <hossein.ir@gmail.com> | 2021-03-29 21:55:26 +0430 |
|---|---|---|
| committer | Adolfo Jayme Barrientos <fitojb@ubuntu.com> | 2021-04-07 17:47:16 +0200 |
| commit | ea5641baeef73af60d025d185901a303844e2d85 (patch) | |
| tree | 94b343b35e7b8805beb9a1745fe1de2f382574fb | |
| parent | 33da78c21f4243a3e469fb7df79ed1745df70078 (diff) | |
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>
141 files changed, 1749 insertions, 1507 deletions
diff --git a/README.md b/README.md index 7da780aca76a..2e5561998892 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ to compile and build your code, it avoids any arbitrary limitations of our scripting APIs, and in general is far more simple and intuitive - if you are a reasonably able C++ programmer. -## The build chain and runtime baselines +## The Build Chain and Runtime Baselines These are the current minimal operating system and compiler versions to run and compile LibreOffice, also used by the TDF builds: @@ -62,13 +62,13 @@ the LibreOffice Development Environment For more information see the build instructions for your platform in the [TDF wiki](https://wiki.documentfoundation.org/Development). -## The important bits of code +## The Important Bits of Code -Each module should have a `README` file inside it which has some +Each module should have a `README.md` file inside it which has some degree of documentation for that module; patches are most welcome to improve those. We have those turned into a web page here: -https://docs.libreoffice.org/ +<https://docs.libreoffice.org/> However, there are two hundred modules, many of them of only peripheral interest for a specialist audience. So - where is the @@ -77,32 +77,32 @@ the most important ones: Module | Description ----------|------------------------------------------------- -sal/ | this provides a simple System Abstraction Layer -tools/ | this provides basic internal types: 'Rectangle', 'Color' etc. -vcl/ | this is the widget toolkit library and one rendering abstraction -framework | UNO framework, responsible for building toolbars, menus, status bars, and the chrome around the document using widgets from VCL, and XML descriptions from */uiconfig/* files -sfx2/ | legacy core framework used by Writer/Calc/Draw: document model / load/save / signals for actions etc. -svx/ | drawing model related helper code, including much of Draw/Impress +[sal/](sal) | this provides a simple System Abstraction Layer +[tools/](tools) | this provides basic internal types: `Rectangle`, `Color` etc. +[vcl/](vcl) | this is the widget toolkit library and one rendering abstraction +[framework/](framework) | UNO framework, responsible for building toolbars, menus, status bars, and the chrome around the document using widgets from VCL, and XML descriptions from `/uiconfig/` files +[sfx2/](sfx2) | legacy core framework used by Writer/Calc/Draw: document model / load/save / signals for actions etc. +[svx/](svx) | drawing model related helper code, including much of Draw/Impress Then applications Module | Description ----------|------------------------------------------------- -desktop/ | this is where the 'main' for the application lives, init / bootstrap. the name dates back to an ancient StarOffice that also drew a desktop -sw/ | Writer -sc/ | Calc -sd/ | Draw / Impress +[desktop/](desktop) | this is where the `main()` for the application lives, init / bootstrap. the name dates back to an ancient StarOffice that also drew a desktop +[sw/](sw/) | Writer +[sc/](sc/) | Calc +[sd/](sd/) | Draw / Impress There are several other libraries that are helpful from a graphical perspective: Module | Description ----------|------------------------------------------------- -basegfx/ | algorithms and data-types for graphics as used in the canvas -canvas/ | new (UNO) canvas rendering model with various backends -cppcanvas/ | C++ helper classes for using the UNO canvas -drawinglayer/ | View code to render drawable objects and break them down into primitives we can render more easily. +[basegfx/](basegfx) | algorithms and data-types for graphics as used in the canvas +[canvas/](canvas) | new (UNO) canvas rendering model with various backends +[cppcanvas/](cppcanvas) | C++ helper classes for using the UNO canvas +[drawinglayer/](drawinglayer) | View code to render drawable objects and break them down into primitives we can render more easily. -## Rules for #include directives (C/C++) +## Rules for #include Directives (C/C++) Use the `"..."` form if and only if the included file is found next to the including file. Otherwise, use the `<...>` form. (For further details, see the @@ -112,12 +112,12 @@ mail [Re: C[++]: Normalizing include syntax ("" vs The UNO API include files should consistently use double quotes, for the benefit of external users of this API. -loplugin:includeform (compilerplugins/clang/includeform.cxx) enforces these rules. +`loplugin:includeform (compilerplugins/clang/includeform.cxx)` enforces these rules. -## Finding out more +## Finding Out More -Beyond this, you can read the `README` files, send us patches, ask +Beyond this, you can read the `README.md` files, send us patches, ask on the mailing list libreoffice@lists.freedesktop.org (no subscription required) or poke people on IRC `#libreoffice-dev` on irc.freenode.net - we're a friendly and generally helpful mob. We know the code can be diff --git a/UnoControls/README.md b/UnoControls/README.md index 72348dc3715f..2a5d79a2e626 100644 --- a/UnoControls/README.md +++ b/UnoControls/README.md @@ -1 +1,3 @@ +# UNO Controls + Separate process and thread for progress bars, etc. diff --git a/accessibility/README.md b/accessibility/README.md index 9309e2725e01..6e11da1acee2 100644 --- a/accessibility/README.md +++ b/accessibility/README.md @@ -1 +1,3 @@ -Cares for accessibility. +# Accessibility Support for LibreOffice + +Provides accessible components for LibreOffice 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. diff --git a/animations/README.md b/animations/README.md index 00769956f0b2..d03a756a1682 100644 --- a/animations/README.md +++ b/animations/README.md @@ -1 +1,3 @@ -Contains containers for the css::animation UNO API, used in [[slideshow]] and [[sd]]. +# Containers for the css::animation animation UNO API + +Contains containers for the `css::animation` UNO API, used in `slideshow` and `sd`. diff --git a/apple_remote/README.md b/apple_remote/README.md index cf099f284750..aed352e42e4b 100644 --- a/apple_remote/README.md +++ b/apple_remote/README.md @@ -1,12 +1,17 @@ -Library to interact with the Apple Remote Control on Mac +# Apple Remote Control Support for Mac -This is an early version of Martin Kahr's Remote Control Wrapper +The library is used to interact with the "Apple Remote Control" on Mac. + +This is an early version of Martin Kahr's "Remote Control Wrapper" library (http://martinkahr.com/2007/07/26/remote-control-wrapper-20/index.html ) with modifications by Eric Bachard. Unfortunately the exact extent of (and rationale behind) the modifications done is unknown, at least until the original upstream source version it is based on is found. Version control of this just starts with the monolithic commit -of the appleremote01 CWS. Some technical detail can be found in the +of the `appleremote01` CWS. Some technical detail can be found in the OOo wiki: -http://wiki.openoffice.org/wiki/Mac_OS_X_Porting_-_Apple_Remote_implementation + +## See Also + +<http://wiki.openoffice.org/wiki/Mac_OS_X_Porting_-_Apple_Remote_implementation> diff --git a/avmedia/README.md b/avmedia/README.md index 32155b2ac1cf..51202cbe34b2 100644 --- a/avmedia/README.md +++ b/avmedia/README.md @@ -1,18 +1,18 @@ -Audio/Video media implementation. +# Audio / video Media Implementation. Provides per-platform implementations of multimedia functionality. Currently no stream API is provided, only a URI based one, so streaming has to be wrapped around it via temp files. -Also provides (in source/framework/mediacontrol.cxx) an implementation +Also provides (in `source/framework/mediacontrol.cxx`) an implementation of the graphical media playback control that appears in the toolbar / -mediaobject bar when media is selected under the .uno:AVMediaToolBox +mediaobject bar when media is selected under the `.uno:AVMediaToolBox` item. -== avmedia/gstreamer == +## avmedia / gstreamer -The avmedia component is implementation of manager service defined in -offapi/com/sun/star/media/. Radek has added implementation based on +The `avmedia` component is implementation of manager service defined in +`offapi/com/sun/star/media/`. Radek has added implementation based on gstreamer so that we can add audio and video files into impress presentation on Linux with gstreamer. @@ -22,4 +22,6 @@ problems when gstreamer installation is incomplete. In the beginning the media files were not embedded, Thorsten added support for that later. -FUTURE work: it might be worthwhile to revamp the avmedia UI +## Future Works + +it might be worthwhile to revamp the avmedia UI. diff --git a/basctl/README.md b/basctl/README.md index 44cdd8f6c46b..bf550607668f 100644 --- a/basctl/README.md +++ b/basctl/README.md @@ -1 +1,3 @@ -Controls and dialogs for Basic. Contains the Basic IDE. +# BASIC IDE Controls and Dialogs + +Controls and dialogs for BASIC. Contains the BASIC IDE. diff --git a/basegfx/README.md b/basegfx/README.md index 99f0feb7ae30..fd4660d8eab1 100644 --- a/basegfx/README.md +++ b/basegfx/README.md @@ -1 +1,3 @@ -Algorithms and data types for graphics (e.g. polygons, vectors, matrices and the like - see that used in [[canvas]]). +# Algorithms and Data Types for Graphics + +Algorithms and data types for graphics (e.g. polygons, vectors, matrices and the like - see that used in "canvas"). diff --git a/basic/README.md b/basic/README.md index c7e6654c1057..b1fcf8123b8b 100644 --- a/basic/README.md +++ b/basic/README.md @@ -1,8 +1,10 @@ +# StarBASIC Interpreter + Contains the StarBASIC Interpreter This implements a macro language that, when in VBA compatibility mode, is intended to be interoperable with Visual Basic for Applications, allowing people to run macros embedded in their documents. -See also: -[http://wiki.openoffice.org/wiki/Basic] +## See also +<http://wiki.openoffice.org/wiki/Basic> diff --git a/bean/README.md b/bean/README.md index 74fe28461ed6..7c8005bcb450 100644 --- a/bean/README.md +++ b/bean/README.md @@ -1,3 +1,3 @@ -To use LibreOffice from Java applications. +# API to Use LibreOffice from Java Applications (OfficeBean) LibreOffice's API is completely exposed so that all office components can be fully controlled. diff --git a/bin/README.md b/bin/README.md index d5d0829ce1d3..572be3174773 100644 --- a/bin/README.md +++ b/bin/README.md @@ -1,9 +1,11 @@ +# Tools and Non-Build Scripts + Tools and scripts mostly not used during the build This direction has a number of key pieces (?) that are used during the build, or are simply generally useful. One example is -bin/find-german-comments <directory> + bin/find-german-comments <directory> which will try to detect and extract all the German comments in a given source code hierarchy / directory. diff --git a/binaryurp/README.md b/binaryurp/README.md index 1f1e088944f6..ac26bec0621e 100644 --- a/binaryurp/README.md +++ b/binaryurp/README.md @@ -1,9 +1,8 @@ -UNO Remote Protocol (URP). A binary protocol. +# UNO Remote Protocol (URP) -UNO provides a protocol called the UNO Remote Protocol (URP) that provides +UNO provides a binary protocol called the UNO Remote Protocol (URP) that provides a bridge between UNO environments. This bridge allows processes and objects to send method calls and to receive return values. UNO objects in different environments are connected by way of this interprocess bridge. The underlying connection is made through a socket or pipe. Remote UNO objects are connected by means of TCP/IP using the high-level protocol of the URP. - diff --git a/bridges/README.md b/bridges/README.md index 7c0eee30bbba..37c4485eecc8 100644 --- a/bridges/README.md +++ b/bridges/README.md @@ -1,4 +1,6 @@ -Bridges from various C++ ABIs, Java JNI, MS .Net to UNO and back. +# UNO Bridges -Also implementation of the UNO Remote Protocol. And in ooo-build a bridge from Mono to UNO and back. +Bridges from various C++ ABIs, Java JNI, MS .NET to UNO and back. A bridge for .NET is in +`cli_ure`. +Also implementation of the UNO Remote Protocol. diff --git a/canvas/README.md b/canvas/README.md index b68da4c3bf5c..459b588d6f6a 100644 --- a/canvas/README.md +++ b/canvas/README.md @@ -1,46 +1,53 @@ +# UNO-based Graphics Backend + UNO-based graphics backend, lesser impedance to modern graphics APIs than vcl. -== The Canvas Framework == +## The canvas Framework -The canvas framework is the successor of the system GUI and graphics +The `canvas` framework is the successor of the system GUI and graphics backend VCL. Basic functionality is available, supplying just as much features as necessary to provide a VCL-equivalent feature set (except proper BiDi/CTL support). -The canvas framework consists of the following two modules, canvas and -cppcanvas. Additionally, a new generic graphics tooling is used (but +The `canvas` framework consists of the following two modules, `canvas` and +`cppcanvas`. Additionally, a new generic graphics tooling is used (but not exclusively by the canvas, Armin's drawinglayer module also make -use of it), which resides in basegfx. +use of it), which resides in `basegfx`. The UNO API used by the canvas is primarily under -css::rendering, with css::rendering::XCanvas +`css::rendering`, with `css::rendering::XCanvas` being the central interface. -== The slideshow engine == +## The slideshow Engine -The slideshow engine has replaced the former Impress-embedded +The `slideshow` engine has replaced the former Impress-embedded presentation framework with a fully independent UNO component, and it is based on the canvas. Some features used there are only available -from canvas, like double-buffering, and hardware-accelerated +from `canvas`, like double-buffering, and hardware-accelerated alpha-blending (currently not on all platforms). -== Cairo canvas == +## Cairo canvas -cairo canvas is one of backends of canvas component. canvas is mostly +Cairo `canvas` is one of backends of canvas component. `canvas` is mostly used for slideshow rendering and also for emf+ rendering. we hoped it will even be used by drawing layer, but it didn't happen (yet?) for -API look at offapi/com/sun/star/rendering/, the implementation is in -canvas and cppcanvas modules. +API look at `offapi/com/sun/star/rendering/`, the implementation is in +`canvas` and `cppcanvas` modules. -cairo canvas backend uses cairo library for rendering. main advantage +Cairo `canvas` backend uses Cairo library for rendering. Main advantage is support of alpha transparency and in some cases accelerated rendering. -the backend itself is quite old and stable, not many changes in that +The backend itself is quite old and stable, not many changes in that area lately, mostly changes for emf+ rendering, communication with vcl and bugfixes -FUTURE work: look at cairo canvas and situation when it is used -(mostly slideshow). TODO there still might be more cases when we +## Future Works + +Look at Cairo `canvas` and situation when it is used +(mostly slideshow). + +## TODO +There still might be more cases when we can save some roundtrips when exchanging data with vcl. diff --git a/chart2/README.md b/chart2/README.md index 56eb0ed08cd8..fa63da9bcc4e 100644 --- a/chart2/README.md +++ b/chart2/README.md @@ -1,9 +1,9 @@ -Chart implementation for LibreOffice Calc. +# Chart Implementation for LibreOffice Calc -The chart2 denotes a second generation re-write done to rid us of the +The `chart2` denotes a second generation re-write done to rid us of the foul and twisted legacy chart code. -== Debugging == +## Debugging -=== CTRL + F12 === -This creates a layout dump based on the XShapeDumper based on SAL_WARN("chart2", ... +### Shortcuts +CTRL + F12 creates a layout dump based on the `XShapeDumper` based on `SAL_WARN("chart2", ...` diff --git a/cli_ure/README.md b/cli_ure/README.md index 8f173dffe8ab..8cf07cf00b24 100644 --- a/cli_ure/README.md +++ b/cli_ure/README.md @@ -1,5 +1,6 @@ -Common Lang Infrastructure Uno Runtime Environment - support assemblies and tools for the MS .Net (and Mono) UNO binding. +# Common Language Infrastructure (CLI) UNO Runtime Environment -See also: -[git:cli_ure/source/readme.txt] +Support assemblies and tools for the MS .NET UNO binding. +## See also +`git:cli\_ure/readme.txt` diff --git a/codemaker/README.md b/codemaker/README.md index 436086cec5e5..c195112fde69 100644 --- a/codemaker/README.md +++ b/codemaker/README.md @@ -1,17 +1,19 @@ +# Language Code Generators for UNOIDL Entities + Generators for language-binding--specific representations of UNOIDL entities: -- cppumaker generates header (.hdl and .hpp) files for the C++ UNO language - binding -- javamaker generates class files for the JVM language binding -- the codemaker for .Net is in module cli_ure -Some of the code is re-used by the skeletonmakers in module unodevtools. +- `cppumaker` generates header (`.hdl` and `.hpp`) files for the C++ UNO language + binding +- `javamaker` generates class files for the JVM language binding +- the codemaker for .NET is in module `cli_ure` +Some of the code is re-used by the skeletonmakers in module `unodevtools`. Note the different terminology used by cppumaker vs. gbuild for the three variants that can be generated by cppumaker for some of the inline functions: - cppumaker switch: -L; cpputype.cxx: light; gbuild: normal; - cppumaker switch: none; cpputype.cxx: normal; gbuild: bootstrap; - cppumaker switch: -C; cpputype.cxx: comprehensive; gbuild: comprehensive; + cppumaker switch: -L; cpputype.cxx: light; gbuild: normal; + cppumaker switch: none; cpputype.cxx: normal; gbuild: bootstrap; + cppumaker switch: -C; cpputype.cxx: comprehensive; gbuild: comprehensive; -...a recipe for confusion. +which can be a source of confusion. diff --git a/comphelper/README.md b/comphelper/README.md index e27793533e9a..5369639e9885 100644 --- a/comphelper/README.md +++ b/comphelper/README.md @@ -1,4 +1,4 @@ -Helper functionality for implementing UNO components +# Helpers for Implementing UNO Components -...anything not generic/mature enough to end up in URE's stable interface at -cppuhelper etc. +Here goes anything not generic / mature enough to end up in URE's stable interface +at `cppuhelper`, etc. diff --git a/compilerplugins/README.md b/compilerplugins/README.md index c48341e0f0d2..e076f408f07a 100644 --- a/compilerplugins/README.md +++ b/compilerplugins/README.md @@ -1,69 +1,66 @@ -Compiler plugins. +# Compiler plugins - -== Overview == +## Overview This directory contains code for compiler plugins. These are used to perform additional actions during compilation (such as additional warnings) and also to perform mass code refactoring. -Currently only the Clang compiler is supported (http://wiki.documentfoundation.org/Development/Clang). - +Currently only the Clang compiler is supported <http://wiki.documentfoundation.org/Development/Clang>. -== Usage == +## Usage -Compiler plugins are enabled automatically by --enable-dbgutil if Clang headers -are found or explicitly using --enable-compiler-plugins. +Compiler plugins are enabled automatically by `--enable-dbgutil` if Clang headers +are found or explicitly using `--enable-compiler-plugins`. - -== Functionality == +## Functionality There are two kinds of plugin actions: + - compile checks - these are run during normal compilation - rewriters - these must be run manually and modify source files Each source has a comment saying whether it's compile check or a rewriter and description of functionality. -=== Compile checks === +### Compile Checks Used during normal compilation to perform additional checks. All warnings and errors are marked '[loplugin]' in the message. - -=== Rewriters === +### Rewriters Rewriters analyse and possibly modify given source files. -Usage: make COMPILER_PLUGIN_TOOL=<rewriter_name> +Usage: `make COMPILER_PLUGIN_TOOL=<rewriter_name>` Additional optional make arguments: -- it is possible to also pass FORCE_COMPILE_ALL=1 to make to trigger rebuild of all source files, + +- it is possible to also pass `FORCE_COMPILE_ALL=1` to make to trigger rebuild of all source files, even those that are up to date. -- UPDATE_FILES=<scope> - limits which modified files will be actually written back with the changes - - mainfile - only the main .cxx file will be modified (default) - - all - all source files involved will be modified (possibly even header files from other LO modules), +- `UPDATE_FILES=<scope>` - limits which modified files will be actually written back with the changes + - `mainfile` - only the main `.cxx` file will be modified (default) + - `all` - all source files involved will be modified (possibly even header files from other LO modules), 3rd party header files are however never modified - - <module> - only files in the given LO module (toplevel directory) will be modified (including headers) + - `<module>` - only files in the given LO module (toplevel directory) will be modified (including headers) Modifications will be written directly to the source files. Some rewriter plugins are dual-mode and can also be used in a non-rewriting mode in which they emit warnings for problematic code that they would otherwise -automatically rewrite. When any rewriter is enabled explicitly via "make -COMPILER_PLUGIN_TOOL=<rewriter_name>" it works in rewriting mode (and all other +automatically rewrite. When any rewriter is enabled explicitly via `make +COMPILER_PLUGIN_TOOL=<rewriter_name>` it works in rewriting mode (and all other plugins are disabled), but when no rewriter is explicitly enabled (i.e., just -"make"), all dual-mode rewriters are enabled in non-rewriting mode (along with +`make`), all dual-mode rewriters are enabled in non-rewriting mode (along with all non-rewriter plugins; and all non--dual-mode plugins are disabled). The typical process to use such a dual-mode rewriter X in rewriting mode is - make COMPILER_PLUGIN_WARNINGS_ONLY=X \ - && make COMPILER_PLUGIN_TOOL=X FORCE_COMPILE_ALL=1 UPDATE_FILES=all + make COMPILER_PLUGIN_WARNINGS_ONLY=X \ + && make COMPILER_PLUGIN_TOOL=X FORCE_COMPILE_ALL=1 UPDATE_FILES=all which first generates a full build without failing due to warnings from plugin -X in non-rewriting mode (in case of --enable-werror) and then repeats the build +X in non-rewriting mode (in case of `--enable-werror`) and then repeats the build in rewriting mode (during which no object files are generate). -== Code documentation / howtos == - -http://wiki.documentfoundation.org/Clang_plugins +## Code Documentation / HowTos +<http://wiki.documentfoundation.org/Clang_plugins> diff --git a/config_host/README.md b/config_host/README.md index 5dd2d5263481..af5030460d35 100644 --- a/config_host/README.md +++ b/config_host/README.md @@ -1,25 +1,24 @@ -These are configuration files for various features as detected by configure. +# C/C++ Configuration Created by configure Script + +These are configuration files for various features as detected by `configure`. Include only those files you need (in order to reduce rebuilds when a setting changes). -Settings here are only C/C++ #define directives, so they apply only to C/C++ source, +Settings here are only C/C++ `#define` directives, so they apply only to C/C++ source, not to Makefiles. +## Adding a New Setting: - -Adding a new setting: -===================== - -- do AC_DEFINE(HAVE_FOO) in configure.ac when a setting should be set -- choose the proper config_host/config_XXX.h file to use +- do `AC_DEFINE(HAVE_FOO)` in `configure.ac` when a setting should be set +- choose the proper `config_host/config_XXX.h` file to use - if it is a global setting (such as availability of a compiler feature), - use config_host/config_global.h - - otherwise check if there is a matching config_host/config_XXX.h file + use `config_host/config_global.h` + - otherwise check if there is a matching `config_host/config_XXX.h` file - if none matches, add a new one: - - add config_host/config_XXX.h.in here, with just #ifndef include guard - - add AC_CONFIG_HEADERS([config_host/config_XXX.h]) next to the others - in configure.ac -- add #define HAVE_FOO 0 to the config_host/config_XXX.h , possibly with a comment - (do not use #undef HAVE_FOO, unless the setting has more values than on/off) -- add #include <config_XXX.h> before any #if HAVE_FOO in a source file -- make sure you use #if HAVE_FOO for on/off settings, do not use #ifdef + - add `config_host/config_XXX.h.in` here, with just `#ifndef` include guard + - add `AC_CONFIG_HEADERS([config_host/config_XXX.h])` next to the others + in `configure.ac` +- add `#define HAVE_FOO 0` to the `config_host/config_XXX.h`, possibly with a comment + (do not use `#undef HAVE_FOO`, unless the setting has more values than on/off) +- add `#include <config_XXX.h>` before any #if `HAVE_FOO` in a source file +- make sure you use `#if HAVE_FOO` for on/off settings, do not use `#ifdef` diff --git a/configmgr/README.md b/configmgr/README.md index 36a1340ed82a..0534b592e79e 100644 --- a/configmgr/README.md +++ b/configmgr/README.md @@ -1,68 +1,68 @@ -UNO services to access the configuration database +# UNO Services to Access the Configuration Database -== Functional Overview == +## Functional Overview -This code parses the settings that are described in the [[officecfg]] +This code parses the settings that are described in the `officecfg` directory, and provides a UNO API that code can use to set and get settings. -== Source Overview == +## Source Overview -configurationprovider.cxx -configurationregistry.cxx -defaultprovider.cxx -services.cxx - UNO service implementations. + configurationprovider.cxx + configurationregistry.cxx + defaultprovider.cxx + services.cxx +UNO service implementations. -access.cxx -childaccess.cxx -rootaccess.cxx - UNO objects passed to clients. + access.cxx + childaccess.cxx + rootaccess.cxx +UNO objects passed to clients. -components.cxx - Central singleton that aggregates all data (reads in the XML files, manages - modifications and global notifications). + components.cxx +Central singleton that aggregates all data (reads in the XML files, manages +modifications and global notifications). -groupnode.cxx -localizedpropertynode.cxx -localizedvaluenode.cxx -node.cxx -propertynode.cxx -setnode.cxx - Internal representations of data nodes. + groupnode.cxx + localizedpropertynode.cxx + localizedvaluenode.cxx + node.cxx + propertynode.cxx + setnode.cxx +Internal representations of data nodes. -parsemanager.cxx -parser.hxx -valueparser.cxx -xcdparser.cxx -xcsparser.cxx -xcuparser.cxx -xmldata.cxx - XML file reading. + parsemanager.cxx + parser.hxx + valueparser.cxx + xcdparser.cxx + xcsparser.cxx + xcuparser.cxx + xmldata.cxx +XML file reading. -modifications.cxx -writemodfile.cxx - Modification management. + modifications.cxx + writemodfile.cxx +Modification management. -broadcaster.cxx - Notification management. + broadcaster.cxx +Notification management. -additions.hxx -update.cxx - Extension manager interface. + additions.hxx + update.cxx +Extension manager interface. -data.cxx -lock.cxx -nodemap.cxx -partial.cxx -path.hxx -type.cxx - Utilities. + data.cxx + lock.cxx + nodemap.cxx + partial.cxx + path.hxx + type.cxx +Utilities. -== Some Implementation Notes == +## Some Implementation Notes -=== Mandatory Set Members === +### Mandatory Set Members - A set member can be marked as "mandatory," meaning that a member of that name must always be present in a set. @@ -70,67 +70,68 @@ must always be present in a set. - The above definition implies that calling replaceByName on a mandatory set member is OK. -- The XCU format can contain oor:mandatory attributes on nodes. (The XCS format -does not support them. In the registrymodifications file, oor:mandatory +- The XCU format can contain `oor:mandatory` attributes on nodes. (The XCS format +does not support them. In the `registrymodifications` file, `oor:mandatory` attributes should never be needed, as being mandatory cannot be controlled via -the UNO API.) The XCU reading code only evaluates the oor:mandatory attribute +the UNO API.) The XCU reading code only evaluates the `oor:mandatory` attribute for set members, and ignores it everywhere else. -- Only true sets support mandatory members. A localized property for the "*" +- Only true sets support mandatory members. A localized property for the "`*`" locale, though acting much like a set, does not support mandatory members. -- The OpenOffice.org Registry Format document claims that group extension +- The LibreOffice Registry Format document claims that group extension properties are implicitly mandatory, but at least the new configmgr code does not treat them like that (i.e., they can be removed again). -- For simplicity, setMandatory/getMandatory are available as virtual functions -at the base Node, even though they can only make sense for GroupNodes and -SetNodes that are set members. The default getMandatory implementation returns -NO_LAYER, meaning oor:mandatory is not set to true in any layer. (Returning -NO_LAYER simplifies the code, e.g., removeByName does not have to check whether -getMandatory is called on a member of a true set to decide whether to forbid +- For simplicity, `setMandatory/getMandatory` are available as virtual functions +at the base `Node`, even though they can only make sense for `GroupNodes` and +SetNodes that are set members. The default `getMandatory` implementation returns +`NO_LAYER`, meaning `oor:mandatory` is not set to true in any layer. (Returning +`NO_LAYER` simplifies the code, e.g., `removeByName` does not have to check whether +`getMandatory` is called on a member of a true set to decide whether to forbid removal.) - When committing changes (made through the UNO API), the "mandatory" status of -inserted nodes must be updated (in case the insert is due to a replaceByName, or +inserted nodes must be updated (in case the insert is due to a `replaceByName`, or the "mandatory" flag was added by a concurrent modification of a lower layer). Also, for to-be-removed nodes, removal is ignored for (newly; due to concurrent modification of a lower layer) mandatory nodes (but still recorded in -registrymodifications, so may take effect once the lower layer addition is +`registrymodifications`, so may take effect once the lower layer addition is removed again---whether or not that is a good idea). -=== XcuParser Modification Recording === +### XcuParser Modification Recording -- XcuParser records modifications when reading user layer data -(valueParser_.getLayer() == Data::NO_LAYER). +- `XcuParser` records modifications when reading user layer data +(`valueParser_.getLayer() == Data::NO_LAYER`). -- oor:finalized and oor:mandatory attributes cannot be set via the UNO API, so +- `oor:finalized and `oor:mandatory` attributes cannot be set via the UNO API, so it is assumed that user layer data does not contain them (for one, they are not -written by writeModFile; for another, the logic to record modifications expects -a locprop(modify,fuse) to be followed by one or more value(fuse,remove), which -would not necessarily be true if the locprop were only present in the user layer +written by `writeModFile`; for another, the logic to record modifications expects +a `locprop(modify,fuse)` to be followed by one or more `value(fuse,remove)`, which +would not necessarily be true if the `locprop` were only present in the user layer data to flag it as finalized). - The logic to record modifications considers the top of the XML element stack. In the following list of all possible cases, items marked with an asterisk are recorded: - ... group(modify,fuse) - group(modify,fuse) - ... - ... group(modify,fuse) - set(modify,fuse) - ... - ... group(modify,fuse) - *prop(modify,fuse,replace) - value(fuse) - ... group(modify,fuse) - *prop(remove) - ... group(modify,fuse) - locprop(modify,fuse) - *value(fuse) - ... group(modify,fuse) - locprop(modify,fuse) - *value(remove) - ... group(modify,fuse) - *locprop(replace) ... - ... set(modify,fuse,replace) - group(modify/fuse) - ... - ... set(modify,fuse,replace) - *group(replace/fuse) - ... - ... set(modify,fuse,replace) - *group(remove) - ... set(modify,fuse,replace) - set(modify/fuse) - ... - ... set(modify,fuse,replace) - *set(replace/fuse) - ... - ... set(modify,fuse,replace) - *set(remove) -Legend: "...": zero or more further items - "- ...": one or more further items - "modify,fuse" etc.: any of those operations - "modify/fuse": a modify or a fuse on an existing member - "replace/fuse": a replace or a fuse on a non-existing member + ... group(modify,fuse) - group(modify,fuse) - ... + ... group(modify,fuse) - set(modify,fuse) - ... + ... group(modify,fuse) - *prop(modify,fuse,replace) - value(fuse) + ... group(modify,fuse) - *prop(remove) + ... group(modify,fuse) - locprop(modify,fuse) - *value(fuse) + ... group(modify,fuse) - locprop(modify,fuse) - *value(remove) + ... group(modify,fuse) - *locprop(replace) ... + ... set(modify,fuse,replace) - group(modify/fuse) - ... + ... set(modify,fuse,replace) - *group(replace/fuse) - ... + ... set(modify,fuse,replace) - *group(remove) + ... set(modify,fuse,replace) - set(modify/fuse) - ... + ... set(modify,fuse,replace) - *set(replace/fuse) - ... + ... set(modify,fuse,replace) - *set(remove) + Legend: + "...": zero or more further items + "- ...": one or more further items + "modify,fuse" etc.: any of those operations + "modify/fuse": a modify or a fuse on an existing member + "replace/fuse": a replace or a fuse on a non-existing member diff --git a/connectivity/README.md b/connectivity/README.md index 40525a522227..af57e1566daf 100644 --- a/connectivity/README.md +++ b/connectivity/README.md @@ -1,44 +1,50 @@ +# Database Connectivity + Contains database pieces, drivers, etc. -[[dbaccess]] builds UI on top of this. +`dbaccess` builds UI on top of this. -=== PostgreSQL === +## Testing +### PostgreSQL For testing, use: -podman pull postgres:latest -podman run --name=postgres -e POSTGRES_PASSWORD=foobarbaz -p 127.0.0.1:5432:5432 postgres:latest + podman pull postgres:latest + podman run --name=postgres -e POSTGRES_PASSWORD=foobarbaz -p 127.0.0.1:5432:5432 postgres:latest In Base, Connect to an existing database, select PostgreSQL: -URL: host=127.0.0.1 port=5432 dbname=postgres -User: postgres -Password: foobarbaz - -podman stop postgres -podman rm postgres + URL: host=127.0.0.1 port=5432 dbname=postgres + User: postgres + Password: foobarbaz + + podman stop postgres + podman rm postgres In order to test SCRAM authentication, create the container like this: -podman run --name=postgres -e POSTGRES_PASSWORD=foobarbaz -e POSTGRES_INITDB_ARGS=--auth-host=scram-sha-256 -e POSTGRES_HOST_AUTH_METHOD=scram-sha-256 -p 127.0.0.1:5432:5432 postgres:latest + podman run --name=postgres -e POSTGRES_PASSWORD=foobarbaz -e POSTGRES_INITDB_ARGS=--auth-host=scram-sha-256 -e POSTGRES_HOST_AUTH_METHOD=scram-sha-256 -p 127.0.0.1:5432:5432 postgres:latest -=== mysql_test === +### MySQL + +For mysql_test: - The CppunitTest_mysql_test unit test can be used to test the mysqlc - library with any versions of mysql or mariadb server of your choice. +library with any versions of mysql or mariadb server of your choice. - This test does not run automatically. It can be triggered with setting - the environment variable "CONNECTIVITY_TEST_MYSQL_DRIVER". +the environment variable "CONNECTIVITY_TEST_MYSQL_DRIVER". - The environment variable should contain a URL of the following format: - [user]/[passwd]@sdbc:mysql:mysqlc:[host]:[port]/db_name +`[user]/[passwd]@sdbc:mysql:mysqlc:[host]:[port]/db_name` - tl;dr: - podman pull mariadb/server - podman run --name=mariadb -e MYSQL_ROOT_PASSWORD=foobarbaz -p 127.0.0.1:3306:3306 mariadb/server - podman exec -it mariadb /bin/bash -c "echo -e CREATE DATABASE test | /usr/bin/mysql -u root" - (cd connectivity && make -srj8 CppunitTest_connectivity_mysql_test CONNECTIVITY_TEST_MYSQL_DRIVER="root/foobarbaz@sdbc:mysql:mysqlc:127.0.0.1:3306/test") - podman stop mariadb - podman rm mariadb - +``` + podman pull mariadb/server + podman run --name=mariadb -e MYSQL_ROOT_PASSWORD=foobarbaz -p 127.0.0.1:3306:3306 mariadb/server + podman exec -it mariadb /bin/bash -c "echo -e CREATE DATABASE test | /usr/bin/mysql -u root" + (cd connectivity && make -srj8 CppunitTest_connectivity_mysql_test CONNECTIVITY_TEST_MYSQL_DRIVER="root/foobarbaz@sdbc:mysql:mysqlc:127.0.0.1:3306/test") + podman stop mariadb + podman rm mariadb +``` diff --git a/cppcanvas/README.md b/cppcanvas/README.md index 1e9083101434..f32b026bb0d0 100644 --- a/cppcanvas/README.md +++ b/cppcanvas/README.md @@ -1,5 +1,7 @@ -Helper C++ classes for [[canvas]], plus a GDIMetaFile-to-XCanvas converter. +# C++ Helper Classes for canvas -== EMF+ == +Helper C++ classes for `canvas`, plus a `GDIMetaFile`-to-`XCanvas` converter. -For cppcanvas/source/mtfrenderer, see the README in vcl (the EMF+ part). +## EMF+ + +For `cppcanvas/source/mtfrenderer`, see the `README.md` in `vcl` (the EMF+ part). diff --git a/cppu/README.md b/cppu/README.md index 066170cd7840..3249d15e638e 100644 --- a/cppu/README.md +++ b/cppu/README.md @@ -1,4 +1,8 @@ -Type definitions/implementations for the core of UNO. The exported API is in C. +# Binary UNO Runtime -See also: -[http://wiki.openoffice.org/wiki/Uno/Binary/Modules/CPPU] +CPPU stands for C++ UNO and it contains type definitions / implementations for the core of UNO. The +exported API is in C, and there exists some C++ wrappers. + +## See also + +<http://wiki.openoffice.org/wiki/Uno/Binary/Modules/CPPU> diff --git a/cppuhelper/README.md b/cppuhelper/README.md index 4ea500109762..1da7282a9f07 100644 --- a/cppuhelper/README.md +++ b/cppuhelper/README.md @@ -1,4 +1,8 @@ -Helpers for using cppu in C++, e.g. templates for implementing UNO components, bootstrapping stuff. Get UNO up and running. +# C++ cppu Helpers -See also: -[http://wiki.openoffice.org/wiki/Uno/Cpp/Modules/CPPUhelper] +Helpers for using `cppu` in C++, e.g. templates for implementing UNO components, bootstrapping +stuff. Get UNO up and running. + +## See Also + +<http://wiki.openoffice.org/wiki/Uno/Cpp/Modules/CPPUhelper> diff --git a/cpputools/README.md b/cpputools/README.md index 9652827ca123..e6ab397cffaf 100644 --- a/cpputools/README.md +++ b/cpputools/README.md @@ -1 +1,3 @@ -Old way of doing component registration. Nowadays replaced by another stand-alone UI and tools called UNO package. +# Old Way of Doing Component Registration + +Nowadays replaced by another stand-alone UI and tools called UNO package. diff --git a/cui/README.md b/cui/README.md index 9afcf8873e2a..34b30ebef85c 100644 --- a/cui/README.md +++ b/cui/README.md @@ -1,8 +1,8 @@ -Common User Interface +# Common User Interface (cui) -It was moved out from svx in DEV300m68: +It was moved out from `svx` in DEV300m68: -http://www.mail-archive.com/dev@openoffice.org/msg12925.html +<http://www.mail-archive.com/dev@openoffice.org/msg12925.html> It contains dialogs used by more than one application, e.g. paragraph properties. diff --git a/dbaccess/README.md b/dbaccess/README.md index 555835a00ff0..8bcd4dd25dd8 100644 --- a/dbaccess/README.md +++ b/dbaccess/README.md @@ -1,3 +1,5 @@ -Database access tools, for "base" database application +# Database Access Tools for LibreOffice Base DB Apps -Builds on top of drivers in [[connectivity]]. +Database access tools, for `base` database application + +Builds on top of drivers in `connectivity`. diff --git a/desktop/README.md b/desktop/README.md index a49f0051ae1f..1474f11e2718 100644 --- a/desktop/README.md +++ b/desktop/README.md @@ -1,28 +1,28 @@ -What used to be the desktop in StarOffice 5 - now the binary. +# LibreOffice Binary +Code for the LibreOffice main binary (`soffice`) resides here. The `soffice_main` +function for the `soffice` binary can be found here. -Stable Interface -================ + +## Stable Interface Some of the artifacts built here are part of a LibreOffice installation set's stable interface, which (programmatic) clients can depend on. Among them are: -soffice -======= +### soffice -In the "program" directory ("program/" on Linux and Windows, "Contents/MacOS/" +In the `program` directory (`program/` on Linux and Windows, `Contents/MacOS/` on macOS). -unoinfo -======= +### unoinfo -In the "program" directory ("program/" on Linux and Windows, "Contents/MacOS/" +In the `program` directory (`program/` on Linux and Windows, `Contents/MacOS/` on macOS). -When called with a sole argument of "c++", it prints to stdout an absolute +When called with a sole argument of `c++`, it prints to stdout an absolute pathname denoting the directory where the public URE libraries are found. -When called with a sole argument of "java", it prints to stdout a marker +When called with a sole argument of `java`, it prints to stdout a marker character (either an ASCII '0' or '1') followed by a sequence of zero or more absolute pathnames denoting jars or directories that need to be included in a class loader's search locations. @@ -33,4 +33,9 @@ other by NUL bytes. If the marker character is '1' (on Windows), the pathnames are encoded as UTF-16-LE two-byte code units, and any two pathnames in the sequence are -separated from each other by two-byte NUL code units. +separated from each other by two-byte `NUL` code units. + +## Other Binaries + +### oosplash +Splash screen for the LibreOffice `soffice` binary. diff --git a/distro-configs/README.md b/distro-configs/README.md index 66a6e324d48a..7ae0450bfa31 100644 --- a/distro-configs/README.md +++ b/distro-configs/README.md @@ -1,28 +1,28 @@ -Pre-canned distribution configurations +# Pre-canned Distribution Configurations These files are supposed to correspond to the options used when creating the Document Foundation (or other "canonical") builds of LibreOffice for various platforms. They are *not* supposed to represent the "most useful" options for developers in general. On the -contrary, the intent is that just running ./autogen.sh without any +contrary, the intent is that just running `./autogen.sh` without any options at all should produce a buildable configuration for developers with interest in working on the most commonly used parts of the code. -See [[https://wiki.documentfoundation.org/Development/ReleaseBuilds]] for how -TDF builds make use of these switches. (Especially, since --with-package-format -now triggers whether or not installation sets are built, all the relevant *.conf -files specify it, except for LibreOfficeLinux.conf, where the TDF build -instructions pass an explicit --with-package-format="rpm deb" in addition to ---with-distro=LibreOfficeLinux.) +See <https://wiki.documentfoundation.org/Development/ReleaseBuilds> for how +TDF builds make use of these switches. (Especially, since `--with-package-format` +now triggers whether or not installation sets are built, all the relevant `*.conf` +files specify it, except for `LibreOfficeLinux.conf`, where the TDF build +instructions pass an explicit `--with-package-format="rpm deb"` in addition to +`--with-distro=LibreOfficeLinux`.) (Possibly the above is a misunderstanding, or maybe there never even has been any clear consensus what situations these files actually are intended for.) The files contain sets of configuration parameters, and can be passed -on the autogen.sh command line thus: +on the `autogen.sh` command line thus: -./autogen.sh --with-distro=LibreOfficeFoo + ./autogen.sh --with-distro=LibreOfficeFoo Contrary to the above, in the Android case the amount of parameters you just must use is so large, that for convenience it is always diff --git a/drawinglayer/README.md b/drawinglayer/README.md index b530ba6fedac..38bdc2197c70 100644 --- a/drawinglayer/README.md +++ b/drawinglayer/README.md @@ -1,6 +1,8 @@ +# Drawing API + Drawing API that can specify what to draw via a kind of display list. -Example of the DrawingLayer use is eg. in svx/source/xoutdev/xtabhtch.cxx:121. +Example of the DrawingLayer use is eg. in `svx/source/xoutdev/xtabhtch.cxx:121`. A stripped down version with extended comments: // Create a hatch primitive (here a rectangle that will be filled with @@ -39,7 +41,7 @@ A stripped down version with extended comments: // it in the widget. aRetval = aVirtualDevice.GetBitmap(Point(0, 0), aVirtualDevice.GetOutputSizePixel()); -== DrawingLayer glossary == +## DrawingLayer Glossary Primitives - classes that represent what should be drawn. It holds the data what to draw, but does not contain any kind of the rendering. Some of the @@ -49,31 +51,31 @@ primitives. Decomposition - a way how to break down the more complicated primitives into the basic primitives, and represent them via them; this logically makes the -plain Primitive2DSequence display list a hierarchy. -Eg. PolygonMarkerPrimitive2D can be decomposed to 2 hairlines -PolyPolygonHairlinePrimitive2D's, each with different color. +plain `Primitive2DSequence` display list a hierarchy. +Eg. `PolygonMarkerPrimitive2D` can be decomposed to 2 hairlines +`PolyPolygonHairlinePrimitive2D`'s, each with different color. Processor - a class that goes through the hierarchy of the Primitives, and -renders it some way. Various processors, like VclPixelProcessor2D (renders to -the screen), VclMetafileProcessor2D (renders to the VCL metafile, eg. for +renders it some way. Various processors, like `VclPixelProcessor2D` (renders to +the screen), `VclMetafileProcessor2D` (renders to the VCL metafile, eg. for printing), etc. -== How to Implement a new Primitive ("something new to draw") == +## How to Implement a New Primitive ("Something New to Draw") -* Create an ancestor of BasePrimitive2D +* Create an ancestor of `BasePrimitive2D` (or of its ancestor if it fits the purpose better) - * Assign it an ID [in drawinglayer_primitivetypes2d.hxx] + * Assign it an ID [in `drawinglayer_primitivetypes2d.hxx`] * Implement its decomposition - [virtual Primitive2DSequence create2DDecomposition(...)] + [`virtual Primitive2DSequence create2DDecomposition(...)`] * Extend the (various) processor(s) If you need more than relying on just the decomposition -== Where is DrawingLayer used == +## Where is DrawingLayer Used -* SdrObject(s) (rectangles, Circles, predefined shapes etc.) +* `SdrObject`(s) (rectangles, Circles, predefined shapes etc.) * Selections diff --git a/editeng/README.md b/editeng/README.md index 6eab9abaee4f..2407c073520e 100644 --- a/editeng/README.md +++ b/editeng/README.md @@ -1,12 +1,14 @@ -Edit engine. +# Edit Engine + +In OpenOffice.org build DEV300m72 this module was split off from `svx` but it +has no dependencies on `svx` (nor on `sfx2`) while in turn `svx` depends on editeng -In OO.o build DEV300m72 this module was split off from svx but it -has no dependencies on [[svx]] (nor on [[sfx2]]) while in turn svx depends on editeng Read more in the mailing list post: -[http://www.mail-archive.com/dev@openoffice.org/msg13237.html] +<http://www.mail-archive.com/dev@openoffice.org/msg13237.html> + +If you build LibreOffice with `dbgutil`, you have some extended debug keys: -If you build LibreOffice with dbgutil, you have some extended debug keys: -Ctrl+Alt+F1 - draws the paragraph rectangles in different colors -Ctrl+Alt+F11 - toggles dumping the edit engine state to the +- Ctrl+Alt+F1 - draws the paragraph rectangles in different colors +- Ctrl+Alt+F11 - toggles dumping the edit engine state to the "editenginedump.log" on draw -Ctrl+Alt+F12 - dumps the current edit engine state to "editenginedump.log" +- Ctrl+Alt+F12 - dumps the current edit engine state to "editenginedump.log" diff --git a/embeddedobj/README.md b/embeddedobj/README.md index 3fe564abd6b3..247ef1fda083 100644 --- a/embeddedobj/README.md +++ b/embeddedobj/README.md @@ -1 +1,3 @@ -Code for embedding objects into LibreOffice (reverse of embedserv module). +# Embedding Objects Into LibreOffice + +Code for embedding objects into LibreOffice (reverse of `embedserv` module). diff --git a/embedserv/README.md b/embedserv/README.md index fdc64c389ce8..cbdaebed110d 100644 --- a/embedserv/README.md +++ b/embedserv/README.md @@ -1 +1,3 @@ +# LibreOffice Embeddable Objects + To embed LibreOffice via OLE2. diff --git a/emfio/README.md b/emfio/README.md index 0b071d95c1e8..d659731650fd 100644 --- a/emfio/README.md +++ b/emfio/README.md @@ -1 +1,5 @@ -It contains emfio/source/reader which is used for "Insert->Picture->From File". +# WMF/EMF Reader + +It contains emfio/source/reader which is used for "Insert -> Picture -> From + File". It is used to read WMF (Windows Metafile), EMF (Enhanced Metafiles) and +also MF+ enhanced EMF files. diff --git a/eventattacher/README.md b/eventattacher/README.md index ecfdcf75ace5..addd1d7177b0 100644 --- a/eventattacher/README.md +++ b/eventattacher/README.md @@ -1 +1,8 @@ -How [[basic]] handles events +# Event Attacher + +This is how StarBasic handles events. + +## See Also + +- <https://wiki.openoffice.org/wiki/Documentation/DevGuide/Forms/Programmatic_Assignment_of_Scripts_to_Events> +- <https://wiki.openoffice.org/wiki/Documentation/DevGuide/Forms/Scripting_and_Events> diff --git a/extensions/README.md b/extensions/README.md index 38df77e37fba..94cf2acbebd6 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -1,45 +1,51 @@ -This module contains a grab-bag of unrelated misc. libraries, *none* of which is an extension. +# Miscellaneous Modules -== Application online update checking == +This module contains a grab-bag of unrelated miscellaneous libraries, *none* of +which is an extension. -When we start LO, first InitUpdateCheckJobThread is created, via -UpdateCheckJob::execute() (from extensions/source/update/check/updatecheckjob.cxx), -as a reaction to a "onFirstVisibleTask" event. It waits 25 seconds (so that it +## Application Online Update Checking + +When we start LO, first `InitUpdateCheckJobThread` is created, via +`UpdateCheckJob::execute()` (from `extensions/source/update/check/updatecheckjob.cxx`), +as a reaction to a `onFirstVisibleTask` event. It waits 25 seconds (so that it does not interfere with the startup itself), and then calls -UpdateCheck::initialize() (from extensions/source/update/check/updatecheck.cxx). +`UpdateCheck::initialize()` (from `extensions/source/update/check/updatecheck.cxx`). -This creates one more thread, UpdateCheckThread, that regularly checks whether +This creates one more thread, `UpdateCheckThread`, that regularly checks whether we have reached the time when we should ask for the update. If yes, asks for that, and shows the download button in the menu (if the new update is available). -== OLE automation bridge == +## OLE Automation Bridge A bridge between "OLE automation" and UNO, so you can use UNO services from JScript, VBScript, etc. -https://www.openoffice.org/udk/common/man/spec/ole_bridge.html +<https://www.openoffice.org/udk/common/man/spec/ole_bridge.html> -See udkapi/com/sun/star/bridge/oleautomation/ApplicationRegistration.idl +See `udkapi/com/sun/star/bridge/oleautomation/ApplicationRegistration.idl` -This is initialized in Desktop::Main() in Desktop::OpenClients_Impl() -by creating the service "com.sun.star.bridge.OleApplicationRegistration", -which is implemented by OleServer_Impl. +This is initialized in `Desktop::Main()` in `Desktop::OpenClients_Impl()` +by creating the service `com.sun.star.bridge.OleApplicationRegistration`, +which is implemented by `OleServer_Impl`. -See extensions/source/ole/ +See `extensions/source/ole/` -== ActiveX control == +## ActiveX Control This allows embedding LO into a Win32 application as an ActiveX control. -See extensions/source/activex/ -== Spotlight provider == +See `extensions/source/activex/` + +## Spotlight Provider On macOS, this allows indexing ODF documents with Spotlight. -See extensions/source/macosx/spotlight/ -== Scanner support == +See `extensions/source/macosx/spotlight/` + +## Scanner Support You can scan from LibreOffice, using platform specific backends like TWAIN/SANE. -See extensions/source/scanner/ + +See `extensions/source/scanner/` diff --git a/external/README.md b/external/README.md index 1f245df45bd1..29a2c9098a4e 100644 --- a/external/README.md +++ b/external/README.md @@ -1 +1,3 @@ +# External Projects + External projects bundled with LibreOffice. diff --git a/extras/README.md b/extras/README.md index 8644d990d5d9..84355c86d2f2 100644 --- a/extras/README.md +++ b/extras/README.md @@ -1,61 +1,63 @@ +# Extra Modules + Contains templates, clipart galleries, palettes, symbol font, autocorrections, autotexts etc. -How-to add a new gallery: - + create a directory extras/source/gallery/foo/ - + create a .str file extras/source/gallery/foo/foo.str - + add a [foo] section to extras/source/gallery/share/gallery_names.ulf - + add a Gallery_foo.mk at the top-level (and mention in Module_extra.mk) - + add a new GALLERY_FILELIST statement in scp2/ ++ How-to add a new gallery: + + create a directory `extras/source/gallery/foo/` + + create a `.str` file `extras/source/gallery/foo/foo.str` + + add a `foo` section to `extras/source/gallery/share/gallery_names.ulf` + + add a `Gallery_foo.mk` at the top-level (and mention in `Module_extra.mk`) + + add a new `GALLERY_FILELIST` statement in `scp2/` -How-to add a new autotext category - + create a directory extras/source/autotext/lang/xx/foo/ where xx is your lang code. xx must exactly fit with an UI lang code. - + unzip your foo.bau autotext file in this directory (including an empty mimetype file) - + add xx/foo.bau in extras/AllLangPackage_autotextshare.mk - + in extras/CustomTarget_autotextshare.mk: - + add xx/foo in extras_AUTOTEXTSHARE_AUTOTEXTS - + add all files contained in foo.bau (except mimetype) in extras_AUTOTEXTSHARE_XMLFILES - + if foo.bau contains files with other extension than .xml, .rdf, .svm and .png - + add a CPY call at the end of the file ++ How-to add a new autotext category + + create a directory `extras/source/autotext/lang/xx/foo/` where `xx` is your lang code. `xx` must exactly fit with an UI lang code. + + unzip your `foo.bau` autotext file in this directory (including an empty mimetype file) + + add `xx/foo.bau` in `extras/AllLangPackage_autotextshare.mk` + + in `extras/CustomTarget_autotextshare.mk`: + + add `xx/foo` in `extras_AUTOTEXTSHARE_AUTOTEXTS` + + add all files contained in `foo.bau` (except mimetype) in `extras_AUTOTEXTSHARE_XMLFILES` + + if `foo.bau` contains files with other extension than `.xml`, `.rdf`, `.svm` and `.png` + + add a `CPY` call at the end of the file -How-to add a new autotext to an existing category - + create a directory extras/source/autotext/lang/xx/standard/FOO/ to add it in category standard of lang xx - + add files of the autotext (at least FOO.xml for an unformatted autotext) - + add autotext name in extras/source/autotext/lang/xx/standard/BlockList.xml - + add all files of autotext in extras/source/autotext/lang/xx/standard/META-INF/manifest.xml - + in extras/CustomTarget_autotextshare.mk: - + add all files of autotext in extras_AUTOTEXTSHARE_XMLFILES - + if some files have different extension from .xml, .rdf, .svm and .png - + add a CPY call at the end of the file ++ How-to add a new autotext to an existing category + + create a directory `extras/source/autotext/lang/xx/standard/FOO/` to add it in category standard of lang `xx` + + add files of the autotext (at least `FOO.xml` for an unformatted autotext) + + add autotext name in `extras/source/autotext/lang/xx/standard/BlockList.xml` + + add all files of autotext in `extras/source/autotext/lang/xx/standard/META-INF/manifest.xml` + + in `extras/CustomTarget_autotextshare.mk`: + + add all files of autotext in `extras_AUTOTEXTSHARE_XMLFILES` + + if some files have different extension from `.xml`, `.rdf`, `.svm` and `.png` + + add a `CPY` call at the end of the file -How-to add a new Impress template - + clean-up template file as indicated on wiki https://wiki.documentfoundation.org/Documentation/HowTo/Impress/Make_template_language_independent - + add <dc:title>Foo</dc:title> in meta.xml to make presentation name translatable - + unzip Foo.otp file in extras/source/templates/presnt/Foo (no space allowed in any file names) - + add "Foo.otp" in Package_tplpresnt.mk - + in CustomTarget_tplpresnt.mk: - + add "Foo /" in extras_TEMPLATES_PRESENTATIONS - + add files names contained in Foo.otp (except mimetype) in extras_PRESENTATIONS_XMLFILES - + if Foo.otp contains files with other extension than .xml, .svm, .svg, .png and .jpg - + add a CPY call at the end of file ++ How-to add a new Impress template + + clean-up template file as indicated on wiki <https://wiki.documentfoundation.org/Documentation/HowTo/Impress/Make_template_language_independent> + + add `<dc:title>Foo</dc:title>` in `meta.xml` to make presentation name translatable + + unzip `Foo.otp` file in `extras/source/templates/presnt/Foo` (no space allowed in any file names) + + add `Foo.otp` in `Package_tplpresnt.mk` + + in `CustomTarget_tplpresnt.mk`: + + add `Foo /` in `extras_TEMPLATES_PRESENTATIONS` + + add files names contained in `Foo.otp` (except mimetype) in `extras_PRESENTATIONS_XMLFILES` + + if `Foo.otp` contains files with other extension than `.xml`, `.svm`, `.svg`, `.png` and `.jpg` + + add a `CPY` call at the end of file -How-to add a new Writer template - + clean-up template file as much as possible, and choose a template category <Category> - + unzip Foo.ott in extras/source/templates/<Category>/Foo (no space allowed in any file names) - + add Foo.ott in Package_<tplCategory>.mk - + in CustomTarget_<tplCategory>.mk: - + add Foo / in extras_TEMPLATES_<CATEGORY> - + add files names contained in Foo.otp (except mimetype) in extras_<CATEGORY>_XMLFILES - + if Foo.ott contains files with other extension than .xml, rdf, .svm, .svg, .png and .jpg - + add a CPY call at the end of file ++ How-to add a new Writer template + + clean-up template file as much as possible, and choose a template category `<Category>` + + unzip `Foo.ott` in `extras/source/templates/<Category>/Foo` (no space allowed in any file names) + + add `Foo.ott` in `Package_<tplCategory>.mk` + + in `CustomTarget_<tplCategory>.mk`: + + add `Foo /` in `extras_TEMPLATES_<CATEGORY>` + + add files names contained in `Foo.otp` (except mimetype) in `extras_<CATEGORY>_XMLFILES` + + if `Foo.ott` contains files with other extension than `.xml`, `.rdf`, `.svm`, `.svg`, `.png` and `.jpg` + + add a `CPY` call at the end of file -How-to add a new template category - + create a directory extras/source/templates/foo/ - + unzip your foo0.ott template files in extras/source/templates/foo/foo0 - + add Package_tplfoo and CustomTarget_tplfoo in Module_extras.mk - + use other category Package_tplcategory.mk to create Package_tplfoo.mk - + use other category CustomTarget_tplcategory.mk to create CustomTarget_tplfoo.mk - + replace all category by foo and CATEGORY by FOO - + add all files contained in foo0.ott (except mimetype) in extras_FOO_XMLFILES - + if foo0.ott contains files with other extension than .xml, .rdf, .svm, .svg, .png and .jpg - + add a CPY call at the end of the file ++ How-to add a new template category + + create a directory `extras/source/templates/foo/` + + unzip your foo0.ott template files in `extras/source/templates/foo/foo0` + + add `Package_tplfoo` and `CustomTarget_tplfoo` in `Module_extras.mk` + + use other category `Package_tplcategory.mk` to create `Package_tplfoo.mk` + + use other category `CustomTarget_tplcategory.mk` to create `CustomTarget_tplfoo.mk` + + replace all category by foo and `CATEGORY` by `FOO` + + add all files contained in `foo0.ott` (except mimetype) in `extras_FOO_XMLFILES` + + if `foo0.ott` contains files with other extension than `.xml`, `.rdf`, `.svm`, `.svg`, `.png` and `.jpg` + + add a `CPY` call at the end of the file + optionally, replace extension ott (4 places) diff --git a/filter/README.md b/filter/README.md index 78d469a6859f..19caeb73eaf9 100644 --- a/filter/README.md +++ b/filter/README.md @@ -1,24 +1,24 @@ +# LibreOffice Filters + Filter registration and some simple filters (also descriptions). Desperate splitting of code into small shared libraries for historical reasons presumably (OS/2 and Windows 3.x). The libraries produced from -the code in each subdirectory of filter/source/graphicfilter are +the code in each subdirectory of `filter/source/graphicfilter` are graphic format import or export filters. But they don't have uniform -API. Some have either a GraphicImport or GraphicExport entry point, +API. Some have either a `GraphicImport` or `GraphicExport` entry point, and are loaded and used in a uniform fashion from code in -svtools/source/filter/filter.cxx. Others have different API and are -loaded from other places. For instance "icgm" has ImportCGM, and is -loaded and used by sd/source/filter/cgm/sdcgmfilter.cxx (!). -Svgreader is used for "File->Open" and then to choose the svg file. -For "Insert->Picture->From File", see svgio/source/svgreader directory. +`svtools/source/filter/filter.cxx`. Others have different API and are +loaded from other places. For instance `icgm` has `ImportCGM`, and is +loaded and used by `sd/source/filter/cgm/sdcgmfilter.cxx` (!). +Svgreader is used for "File -> Open" and then to choose the svg file. +For "Insert -> Picture -> From File", see `svgio/source/svgreader` directory. -==================== -filter configuration -==================== +## Filter Configuration The filter configuration consists of two parts, the type definition in -filter/source/config/fragments/types/ and the actual filter definition -in filter/source/config/fragments/filters/. +`filter/source/config/fragments/types/` and the actual filter definition +in `filter/source/config/fragments/filters/`. Each file type e.g. text file should be represented by exactly one type definition. This type can then be referenced by several different diff --git a/forms/README.md b/forms/README.md index 248da82fe493..53a20e14b8b8 100644 --- a/forms/README.md +++ b/forms/README.md @@ -1 +1,3 @@ -Embedded forms control and pieces (design forms in documents, fields and database driven). +# Embedded Forms Control and Pieces + +design forms in documents, fields and database driven. diff --git a/formula/README.md b/formula/README.md index ab2c28a08c42..0704b107e895 100644 --- a/formula/README.md +++ b/formula/README.md @@ -1,5 +1,7 @@ -Contains parts of the formula parser used outside Calc code that has +# Formula Helper Code + +Contains parts of the formula parser used outside LibreOffice Calc code that has been pulled out from Calc's formula parser code. -Also contains some functions that are needed by code in both sc and -scaddins. Located here just for convenience. So sue me. +Also contains some functions that are needed by code in both `sc` and +`scaddins`. Located here just for convenience. So sue me. diff --git a/fpicker/README.md b/fpicker/README.md index ea21095c1601..6f4bae6c4bac 100644 --- a/fpicker/README.md +++ b/fpicker/README.md @@ -1 +1,3 @@ +# Native File Picker + Native file pickers for macOS and Windows (file open dialog). diff --git a/framework/README.md b/framework/README.md index 2efd636a8022..74711a9a6961 100644 --- a/framework/README.md +++ b/framework/README.md @@ -1,4 +1,7 @@ +# UNO Framework + Toolbars, menus, UNO stuff, including accelerators and interaction, etc. -See also: -http://wiki.openoffice.org/wiki/Framework +## See Also + +<http://wiki.openoffice.org/wiki/Framework> diff --git a/hwpfilter/README.md b/hwpfilter/README.md index 293e6a1bdff7..f59184bc9788 100644 --- a/hwpfilter/README.md +++ b/hwpfilter/README.md @@ -1,5 +1,7 @@ +# Filters for Korean (Hangul) Popular Word Processor Formats + Filter for a word processor file format popular in Korea (Hangul Word Processor). Unfortunately apparently there is a newer version of the file format in use nowadays and the code doesn't handle that correctly but -silently corrupts the input. See fdo#70097. +silently corrupts the input. See tdf#70097. diff --git a/i18nlangtag/README.md b/i18nlangtag/README.md index dcdb7be23144..8bb608c24e62 100644 --- a/i18nlangtag/README.md +++ b/i18nlangtag/README.md @@ -1,141 +1,143 @@ +# Language Tags + Code for language tags, LanguageTag wrapper for liblangtag and converter between BCP47 language tags, Locale(Language,Country,Variant) and MS-LangIDs. Basic functionality used by almost every other module including comphelper, so even don't use that string helpers in this code to not create circular dependencies. Stick with sal and rtl! -If Microsoft introduced a new LCID for a locale that we previously defined as LANGUAGE_USER_..., for example LANGUAGE_CATALAN_VALENCIAN that we had as LANGUAGE_USER_CATALAN_VALENCIAN: - -* include/i18nlangtag/lang.h -** add the new LANGUAGE_... value as defined by MS, here LANGUAGE_CATALAN_VALENCIAN -** rename the LANGUAGE_USER_... definition to LANGUAGE_OBSOLETE_USER_..., here LANGUAGE_USER_CATALAN_VALENCIAN to LANGUAGE_OBSOLETE_USER_CATALAN_VALENCIAN -** add a #define LANGUAGE_USER_CATALAN_VALENCIAN LANGUAGE_CATALAN_VALENCIAN -*** so svtools/source/misc/langtab.src (where the defined name is an identifier) and other places using LANGUAGE_USER_CATALAN_VALENCIAN do not need to be changed +If Microsoft introduced a new LCID for a locale that we previously defined as `LANGUAGE_USER_...`, for example `LANGUAGE_CATALAN_VALENCIAN` that we had as `LANGUAGE_USER_CATALAN_VALENCIAN`: -* i18nlangtag/source/isolang/isolang.cxx -** insert a mapping with LANGUAGE_CATALAN_VALENCIAN before (!) the existing LANGUAGE_USER_CATALAN_VALENCIAN -** rename the LANGUAGE_USER_CATALAN_VALENCIAN to LANGUAGE_OBSOLETE_USER_CATALAN_VALENCIAN -*** so converting the tag maps to the new LANGUAGE_CATALAN_VALENCIAN and converting the old LANGUAGE_OBSOLETE_USER_CATALAN_VALENCIAN still maps to the tag. +* `include/i18nlangtag/lang.h` + * add the new `LANGUAGE_...` value as defined by MS, here `LANGUAGE_CATALAN_VALENCIAN` + * rename the `LANGUAGE_USER_...` definition to `LANGUAGE_OBSOLETE_USER_...`, here `LANGUAGE_USER_CATALAN_VALENCIAN` to `LANGUAGE_OBSOLETE_USER_CATALAN_VALENCIAN` + * add a `#define LANGUAGE_USER_CATALAN_VALENCIAN LANGUAGE_CATALAN_VALENCIAN` + * so `svtools/source/misc/langtab.src` (where the defined name is an identifier) and other places using `LANGUAGE_USER_CATALAN_VALENCIAN` do not need to be changed -* i18nlangtag/source/isolang/mslangid.cxx -** add an entry to MsLangId::getReplacementForObsoleteLanguage() to convert LANGUAGE_OBSOLETE_USER_CATALAN_VALENCIAN to LANGUAGE_CATALAN_VALENCIAN +* `i18nlangtag/source/isolang/isolang.cxx` + * insert a mapping with `LANGUAGE_CATALAN_VALENCIAN` before (!) the existing `LANGUAGE_USER_CATALAN_VALENCIAN` + * rename the `LANGUAGE_USER_CATALAN_VALENCIAN` to `LANGUAGE_OBSOLETE_USER_CATALAN_VALENCIAN` + * so converting the tag maps to the new `LANGUAGE_CATALAN_VALENCIAN` and converting the old `LANGUAGE_OBSOLETE_USER_CATALAN_VALENCIAN` still maps to the tag. +* `i18nlangtag/source/isolang/mslangid.cxx` + * add an entry to `MsLangId::getReplacementForObsoleteLanguage()` to convert `LANGUAGE_OBSOLETE_USER_CATALAN_VALENCIAN` to `LANGUAGE_CATALAN_VALENCIAN` -When changing a (translation's) language tag (for example, 'ca-XV' to 'ca-valencia' or 'sh' to 'sr-Latn'): +When changing a (translation's) language tag (for example, `ca-XV` to `ca-valencia` or `sh` to `sr-Latn`): -* solenv/inc/langlist.mk -** replace the tag and sort alphabetically +* `solenv/inc/langlist.mk` + * replace the tag and sort alphabetically -* in translations/source do git mv old-tag new-tag -** note that translations is a git submodule so https://wiki.documentfoundation.org/Development/Submodules applies +* in `translations/source` do `git mv old-tag new-tag` + * note that translations is a git submodule so <https://wiki.documentfoundation.org/Development/Submodules applies> -* i18nlangtag/source/isolang/isolang.cxx -** maintain the old tag's mapping entry in aImplIsoLangEntries to be able to read existing documents using that code -** add the new tag's mapping to aImplBcp47CountryEntries or aImplIsoLangScriptEntries -** change mnOverride from 0 to kSAME in aImplIsoLangScriptEntries or aImplIsoLangEntries +* `i18nlangtag/source/isolang/isolang.cxx` + * maintain the old tag's mapping entry in `aImplIsoLangEntries` to be able to read existing documents using that code + * add the new tag's mapping to `aImplBcp47CountryEntries` or `aImplIsoLangScriptEntries` + * change `mnOverride` from 0 to `kSAME` in `aImplIsoLangScriptEntries` or `aImplIsoLangEntries` -* i18nlangtag/source/languagetag/languagetag.cxx -** add the new tag's fallback strings to the fallback of the old tag in LanguageTag::getFallbackStrings() +* `i18nlangtag/source/languagetag/languagetag.cxx` + * add the new tag's fallback strings to the fallback of the old tag in `LanguageTag::getFallbackStrings()` -* i18nlangtag/qa/cppunit/test_languagetag.cxx -** add a unit test for the new tag and old tag +* `i18nlangtag/qa/cppunit/test_languagetag.cxx` + * add a unit test for the new tag and old tag -* l10ntools/source/ulfconv/msi-encodinglist.txt -** replace the tag and sort alphabetically +* `l10ntools/source/ulfconv/msi-encodinglist.txt` + * replace the tag and sort alphabetically -* setup_native/source/packinfo/spellchecker_selection.txt -** replace the tag and sort alphabetically +* `setup_native/source/packinfo/spellchecker_selection.txt` + * replace the tag and sort alphabetically If locale data exists: -* i18npool/source/localedata/data/*.xml for example i18npool/source/localedata/data/sh_RS.xml -** in the <LC_INFO> element -*** change <LangID> to 'qlt' -*** after the <Country> element add a <Variant> element with the new full BCP 47 tag, for example 'sr-Latn-RS' -**** note that <Variant> has no <VariantID> or <DefaultName> child elements -** if any of the other *.xml files reference the locale in a ref="..." attribute, change those too; note that these references use '_' underscore instead of '-' hyphen just like the file names do -** rename sh_RS.xml to sr_Latn_RS.xml, git mv sh_RS.xml sr_Latn_RS.xml +* `i18npool/source/localedata/data/*.xml` for example `i18npool/source/localedata/data/sh_RS.xml` + * in the `<LC_INFO>` element + * change `<LangID>` to `qlt` + * after the `<Country>` element add a `<Variant>` element with the new full BCP 47 tag, for example `sr-Latn-RS` + * note that `<Variant>` has no `<VariantID>` or `<DefaultName>` child elements + * if any of the other `*.xml` files reference the locale in a `ref="..."` attribute, change those too; note that these references use '`_`' underscore instead of '`-`' hyphen just like the file names do + * rename `sh_RS.xml` to `sr_Latn_RS.xml`, `git mv sh_RS.xml sr_Latn_RS.xml` -* i18npool/source/localedata/localedata.cxx -** in aLibTable change the entry from old "sh_RS" to new "sr_Latn_RS", do not sort the table +* `i18npool/source/localedata/localedata.cxx` + * in `aLibTable` change the entry from old `sh_RS` to new `sr_Latn_RS`, do not sort the table -* i18npool/Library_localedata_*.mk for example i18npool/Library_localedata_euro.mk -** change the entry for the changed .xml file, for example CustomTarget/i18npool/localedata/localedata_sh_RS to CustomTarget/i18npool/localedata/localedata_sr_Latn_RS, sort the list alphabetically +* `i18npool/Library_localedata_*.mk` for example `i18npool/Library_localedata_euro.mk` + * change the entry for the changed `.xml` file, for example `CustomTarget/i18npool/localedata/localedata_sh_RS` to `CustomTarget/i18npool/localedata/localedata_sr_Latn_RS`, sort the list alphabetically If dictionary exists: -* dictionaries/*/dictionaries.xcu for example dictionaries/sr/dictionaries.xcu -** change the affected <node oor:name="..."> elements to something corresponding, for example <node oor:name="HunSpellDic_sh" ...> to <node oor:name="HunSpellDic_sr_Latn" ...> -** in the "Locales" properties change the <value> element, for example <value>sh-RS</value> to <value>sr-Latn-RS</value> - -If dictionary is to be renamed, for example ku-TR to kmr-Latn: - -* dictionaries/*/* for example dictionaries/ku_TR/* -** if appropriate rename *.dic and *.aff files, for example ku_TR.dic to kmr_Latn.dic and ku_TR.aff to kmr_Latn.aff -* dictionaries/Dictionary_*.mk for example dictionaries/Dictionary_ku_TR.mk -** rename file, for example to Dictionary_kmr_Latn.mk -** change all locale dependent file names and target, for example *ku_TR* to *kmr_Latn* AND ku-TR to kmr-Latn; note '-' and '_' separators, both are used! -* dictionaries/Module_dictionaries.mk -** change Dictionary_* (Dictionary_ku-TR to Dictionary_kmr-Latn) and sort alphabetically -* scp2/source/ooo/common_brand.scp -** DosName = "dict-ku-TR"; -*** change to "dict-kmr-Latn" -* scp2/source/ooo/file_ooo.scp -** File gid_File_Extension_Dictionary_Ku_Tr -*** change to gid_File_Extension_Dictionary_Kmr_Latn -** Name = "Dictionary/dict-ku-TR.filelist"; -*** change to "Dictionary/dict-kmr-Latn.filelist" -* scp2/source/ooo/module_ooo.scp -** Module gid_Module_Root_Extension_Dictionary_Ku_Tr -*** change to gid_Module_Root_Extension_Dictionary_Kmr_Latn -** MOD_NAME_DESC ( MODULE_EXTENSION_DICTIONARY_KU_TR ); -*** change to MODULE_EXTENSION_DICTIONARY_KMR_LATN -** Files = (gid_File_Extension_Dictionary_Ku_Tr); -*** change to gid_File_Extension_Dictionary_Kmr_Latn -** Spellcheckerlanguage = "ku-TR"; -*** change to "kmr-Latn" -* scp2/source/ooo/module_ooo.ulf -** [STR_NAME_MODULE_EXTENSION_DICTIONARY_KU_TR] -*** change to STR_NAME_MODULE_EXTENSION_DICTIONARY_KMR_LATN -** en-US = "Kurdish (Turkey)" -*** change to "Kurdish, Northern, Latin script" -** [STR_DESC_MODULE_EXTENSION_DICTIONARY_KU_TR] -*** change to STR_DESC_MODULE_EXTENSION_DICTIONARY_KMR_LATN -** en-US = "Kurdish (Turkey) spelling dictionary" -*** change to "Kurdish, Northern, Latin script spelling dictionary" -* setup_native/source/packinfo/packinfo_office.txt -** module = "gid_Module_Root_Extension_Dictionary_Ku_Tr" -*** change to "gid_Module_Root_Extension_Dictionary_Kmr_Latn" -** solarispackagename = "%PACKAGEPREFIX%WITHOUTDOTUNIXPRODUCTNAME%BRANDPACKAGEVERSION-dict-ku-TR" -*** change to "...-dict-kmr-Latn" -** packagename = "%UNIXPRODUCTNAME%BRANDPACKAGEVERSION-dict-ku-TR" -*** change to "...-dict-kmr-Latn" -** description = "Ku-TR dictionary for %PRODUCTNAME %PRODUCTVERSION" -*** change to "Kmr-Latn dictionary ..." - -If extras exist, for example extras/source/autotext/*: - -* extras/Package_autocorr.mk -** replace acor_* entry, for example acor_sh-RS.dat to acor_sr-Latn-RS.dat, sort alphabetically - -* extras/CustomTarget_autocorr.mk -** in extras_AUTOCORR_LANGS change map entry, for example sh-RS:sh-RS to sr-Latn-RS:sr-Latn-Rs -** in extras_AUTOCORR_XMLFILES change directory entries, for example sh-RS/acor/DocumentList.xml to sr-Latn-RS/acor/DocumentList.xml - -* rename files accordingly, for example in extras/source/autotext/lang/ git mv sh-RS sr-Latn-RS - -If helpcontent exists: - -* helpcontent2/source/auxiliary/*/* for example helpcontent2/source/auxiliary/sh/* -** change Language=..., for example Language=sh to Language=sr-Latn in helpcontent2/source/auxiliary/sh/*.cfg -** rename helpcontent2/source/auxiliary/sh/ git mv sh sr-Latn +* `dictionaries/*/dictionaries.xcu` for example `dictionaries/sr/dictionaries.xcu` + * change the affected `<node oor:name="...">` elements to something corresponding, for example `<node oor:name="HunSpellDic_sh" ...>` to `<node oor:name="HunSpellDic_sr_Latn" ...>` + * in the `Locales` properties change the `<value>` element, for example `<value>sh-RS</value>` to `<value>sr-Latn-RS</value>` + +If dictionary is to be renamed, for example `ku-TR` to `kmr-Latn`: + +* `dictionaries/*/*` for example `dictionaries/ku_TR/*` + * if appropriate rename `*.dic` and `*.aff` files, for example `ku_TR.dic` to `kmr_Latn.dic` and `ku_TR.aff` to `kmr_Latn.aff` +* `dictionaries/Dictionary_*.mk` for example `dictionaries/Dictionary_ku_TR.mk` + * rename file, for example to `Dictionary_kmr_Latn.mk` + * change all locale dependent file names and target, for example `ku_TR` to `kmr_Latn` AND `ku-TR` to `kmr-Latn`; note '`-`' and '`_`' separators, both are used! +* `dictionaries/Module_dictionaries.mk` + * change `Dictionary_*` (`Dictionary_ku-TR` to `Dictionary_kmr-Latn`) and sort alphabetically +* `scp2/source/ooo/common_brand.scp` + * `DosName = "dict-ku-TR";` + * change to `"dict-kmr-Latn"` +* `scp2/source/ooo/file_ooo.scp` + * File `gid_File_Extension_Dictionary_Ku_Tr` + * change to `gid_File_Extension_Dictionary_Kmr_Latn` + * `Name = "Dictionary/dict-ku-TR.filelist";` + * change to `"Dictionary/dict-kmr-Latn.filelist"` +* `scp2/source/ooo/module_ooo.scp` + * Module `gid_Module_Root_Extension_Dictionary_Ku_Tr` + * change to `gid_Module_Root_Extension_Dictionary_Kmr_Latn` + * `MOD_NAME_DESC` ( `MODULE_EXTENSION_DICTIONARY_KU_TR` ); + * change to `MODULE_EXTENSION_DICTIONARY_KMR_LATN` + * `Files = (gid_File_Extension_Dictionary_Ku_Tr);` + * change to `gid_File_Extension_Dictionary_Kmr_Latn` + * `Spellcheckerlanguage = "ku-TR";` + * change to `"kmr-Latn"` +* `scp2/source/ooo/module_ooo.ulf` + * [`STR_NAME_MODULE_EXTENSION_DICTIONARY_KU_TR`] + * change to `STR_NAME_MODULE_EXTENSION_DICTIONARY_KMR_LATN` + * `en-US = "Kurdish (Turkey)"` + * change to `"Kurdish, Northern, Latin script"` + * [`STR_DESC_MODULE_EXTENSION_DICTIONARY_KU_TR`] + * change to `STR_DESC_MODULE_EXTENSION_DICTIONARY_KMR_LATN` + * `en-US = "Kurdish (Turkey)` spelling dictionary" + * change to `"Kurdish, Northern, Latin script spelling dictionary"` +* `setup_native/source/packinfo/packinfo_office.txt` + * `module = "gid_Module_Root_Extension_Dictionary_Ku_Tr"` + * change to `"gid_Module_Root_Extension_Dictionary_Kmr_Latn"` + * `solarispackagename = "%PACKAGEPREFIX%WITHOUTDOTUNIXPRODUCTNAME%BRANDPACKAGEVERSION-dict-ku-TR"` + * change to `"...-dict-kmr-Latn"` + * `packagename = "%UNIXPRODUCTNAME%BRANDPACKAGEVERSION-dict-ku-TR"` + * change to `"...-dict-kmr-Latn"` + * `description = "Ku-TR dictionary for %PRODUCTNAME %PRODUCTVERSION"` + * change to `"Kmr-Latn dictionary ..."` + +If `extras` exist, for example `extras/source/autotext/*`: + +* `extras/Package_autocorr.mk` + * replace `acor_*` entry, for example `acor_sh-RS.dat` to `acor_sr-Latn-RS.dat`, sort alphabetically + +* `extras/CustomTarget_autocorr.mk` + * in `extras_AUTOCORR_LANGS change` map entry, for example `sh-RS:sh-RS` to `sr-Latn-RS:sr-Latn-Rs` + * in `extras_AUTOCORR_XMLFILES` change directory entries, for example `sh-RS/acor/DocumentList.xml` to `sr-Latn-RS/acor/DocumentList.xml` + +* rename files accordingly, for example in `extras/source/autotext/lang/` `git mv sh-RS sr-Latn-RS` + +If `helpcontent` exists: + +* `helpcontent2/source/auxiliary/*/*` for example `helpcontent2/source/auxiliary/sh/*` + * change `Language=...`, for example `Language=sh` to `Language=sr-Latn` in `helpcontent2/source/auxiliary/sh/*.cfg` + * rename `helpcontent2/source/auxiliary/sh/` `git mv sh sr-Latn` For language packs: -* scp2/source/ooo/module_langpack.ulf -* scp2/source/accessories/module_templates_accessories.ulf -* scp2/source/accessories/module_samples_accessories.ulf -* scp2/source/extensions/module_extensions_sun_templates.ulf +* `scp2/source/ooo/module_langpack.ulf` +* `scp2/source/accessories/module_templates_accessories.ulf` +* `scp2/source/accessories/module_samples_accessories.ulf` +* `scp2/source/extensions/module_extensions_sun_templates.ulf` + + * If the upper-cased tag appears in any of these, replace it, for example `STR_NAME_MODULE_LANGPACK_SH` to `STR_NAME_MODULE_LANGPACK_SR_LATN` -** If the upper-cased tag appears in any of these, replace it, for example STR_NAME_MODULE_LANGPACK_SH to STR_NAME_MODULE_LANGPACK_SR_LATN diff --git a/i18npool/README.md b/i18npool/README.md index 9e1a04f3f329..5d48e8dcd73b 100644 --- a/i18npool/README.md +++ b/i18npool/README.md @@ -1,11 +1,12 @@ -Internationalisation (i18npool) framework ensures that the suite is adaptable to the requirements of different -native languages, their local settings and customs, etc without source code modification. (Wow, that is such marketing-speak...) +# Internationalisation Pool (i18npool) Framework -Specifically for locale data documentation please see i18npool/source/localedata/data/locale.dtd +Internationalisation pool (i18npool) framework ensures that the suite is adaptable to the +requirements of different native languages, their local settings and customs, etc without source +code modification. (Wow, that is such marketing-speak...) -See also [http://wiki.documentfoundation.org/Category:I18n] +Specifically for locale data documentation please see `i18npool/source/localedata/data/locale.dtd` -On iOS we put the largest data generated here, the dict_ja and dict_zh +On iOS we put the largest data generated here, the `dict_ja` and `dict_zh` stuff, into separate files and not into code to keep the size of an app binary down. Temporary test code: @@ -17,3 +18,7 @@ app binary down. Temporary test code: uno::Reference< uno::XInterface > xInterface = xMultiComponentFactoryClient->createInstanceWithContext( "com.sun.star.i18n.BreakIterator_ja", xComponentContext ); } + +## See Also + +<http://wiki.documentfoundation.org/Category:I18n> diff --git a/i18nutil/README.md b/i18nutil/README.md index 2f93fe54cedf..aa90a90135a8 100644 --- a/i18nutil/README.md +++ b/i18nutil/README.md @@ -1,4 +1,4 @@ -i18nutil is internationalization related utilities +# Internationalization Related Utilities (i18nutil) -It comprises of honest c++ code which you just link to directly, while i18npool -tends to consist of code you interact with via uno. +It comprises of honest c++ code which you just link to directly, while `i18npool` +tends to consist of code you interact with via UNO. diff --git a/icon-themes/README.md b/icon-themes/README.md index 79ca0ed54b87..81230417501a 100644 --- a/icon-themes/README.md +++ b/icon-themes/README.md @@ -1,42 +1,41 @@ -Icon repository for the applications +# Icon Repository for the Applications All of the icons, separated by themes are included in this -directory. These icons are built into .zip files, and re-ordered / +directory. These icons are built into `.zip` files, and re-ordered `/` packed for efficiency reasons based on our UI configuration by the -postprocess/CustomTarget_images.mk. +`postprocess/CustomTarget_images.mk`. An icon theme does not need to contain all images, since these can be layered one on top of another. In general the layering is done like this: -<leaf theme> -breeze -colibre + <leaf theme> + breeze + colibre -How to add a new image set: ---------------------------- +## How to Add a New Image Set -- Create a directory for it here (let's call it e.g. new_set) +- Create a directory for it here (let's call it e.g. `new_set`) - FIXME: It is important to use an underscore '_' to delimit more words. - scp2 compilation crashes when using a dash '-'. + FIXME: It is important to use an underscore `_` to delimit more words. + `scp2` compilation crashes when using a dash `-`. It evidently splits the name into two strings. - ^ It's probably not true anymore with filelists. - ^ if this gets changed, IconThemeSelector::SetPreferredIconTheme needs to change too -- Add its name (new_set) to WITH_THEMES variable in configure.ac + + It's probably not true anymore with filelists. + + if this gets changed, `IconThemeSelector::SetPreferredIconTheme` needs to change too -- The fallback for particular icons is defined be packimages_CUSTOM_FALLBACK_1 - in packimages/CustomTarget_images.mk +- Add its name (`new_set`) to `WITH_THEMES` variable in `configure.ac` +- The fallback for particular icons is defined be `packimages_CUSTOM_FALLBACK_1` + in `packimages/CustomTarget_images.mk` -How to add a new icon for a new command: ----------------------------------------- + +## How to Add a New Icon for a New Command - Assume you defined a dispatch command in officecfg like the following: - in officecfg/registry/data/org/openoffice/Office/UI/CalcCommands.xcu +in `officecfg/registry/data/org/openoffice/Office/UI/CalcCommands.xcu` <node oor:name=".uno:OpenFromCalc" oor:op="replace"> <prop oor:name="Label" oor:type="xs:string"> @@ -50,17 +49,16 @@ How to add a new icon for a new command: Here, you need to define a property named "Properties", with its value set to 1 so that the icons show up. -- Now, you need to add 2 new icon images under icon-themes/colibre/cmd/, one +- Now, you need to add 2 new icon images under `icon-themes/colibre/cmd/`, one for the large size and one for the smaller size. The name of each image - must be lc_<command name>.png and sc_<command name>.png. Here, the command - name is the name given in the above .xcu file without the ".uno:" prefix and + must be `lc_<command name>.png` and `sc_<command name>.png`. Here, the command + name is the name given in the above `.xcu` file without the `.uno:` prefix and all its letters lower-cased. In this example, the file names will be - lc_openfromcalc.png and sc_openfromcalc.png. Note that you need to add new + `lc_openfromcalc.png` and `sc_openfromcalc.png`. Note that you need to add new images to the colibre theme for them to show up in any themes at all. -How to call optipng to optimize size: ---------------------------- +## How to Call optipng to Optimize Size -8 bit palettes are on the slow path for quartz/svp/gtk3 so avoid using palettes with... +8 bit palettes are on the slow path for `quartz/svp/gtk3` so avoid using palettes with... -$ optipng -nc <file> + $ optipng -nc <file> diff --git a/idl/README.md b/idl/README.md index b494f10abac5..019126c70f2c 100644 --- a/idl/README.md +++ b/idl/README.md @@ -1,7 +1,9 @@ -SvIDL Compiler that generates C++ slot headers from SDI files in modules' sdi/ +# SvIDL Compiler + +SvIDL Compiler that generates C++ slot headers from SDI files in modules' `sdi/` subdirectory. There is an overview of basic architecture of the markup of SDI files in the -OOo wiki: +OpenOffice wiki: -https://wiki.openoffice.org/wiki/Framework/Article/Implementation_of_the_Dispatch_API_In_SFX2 +<https://wiki.openoffice.org/wiki/Framework/Article/Implementation_of_the_Dispatch_API_In_SFX2> diff --git a/idlc/README.md b/idlc/README.md index 90f015c7794a..621a767b36ea 100644 --- a/idlc/README.md +++ b/idlc/README.md @@ -1,6 +1,7 @@ -Contains the UNO IDL compiler: idlc, depends on preprocessor: ucpp +# UNO IDL Compiler (idlc) -This compiler generates binary RDB fragments that can be assembled -into a RDB (UNO type library) with the "regmerge" tool, as is done -primarily in the offapi and udkapi directories. +Contains the UNO IDL compiler: `idlc`, depends on preprocessor: `ucpp` +This compiler generates binary RDB fragments that can be assembled +into a RDB (UNO type library) with the `regmerge` tool, as is done +primarily in the `offapi` and `udkapi` directories. diff --git a/instsetoo_native/README.md b/instsetoo_native/README.md index 3597a528cd7e..e097a6d7f207 100644 --- a/instsetoo_native/README.md +++ b/instsetoo_native/README.md @@ -1,11 +1,11 @@ -native install-set creation +# Native Install-Set Creation This is where you will find your natively packaged builds after the -build has completed. On windows these would live in: +build has completed. On Windows these would live in: -workdir/*/installation/LibreOffice_Dev/native/install/en-US/*.msi + workdir/*/installation/LibreOffice_Dev/native/install/en-US/*.msi for example (nothing like a few long directory names before breakfast). -Also generates ini files for the instdir/ tree (which are unfortunately -duplicated for now between instsetoo_native/CustomTarget_setup.mk and scp2). +Also generates `.ini` files for the `instdir/` tree (which are unfortunately +duplicated for now between `instsetoo_native/CustomTarget_setup.mk` and `scp2`). diff --git a/io/README.md b/io/README.md index 229153f04c1c..706d9705f0c8 100644 --- a/io/README.md +++ b/io/README.md @@ -1,3 +1,4 @@ -Simple IO wrapper UNO components - +# Simple IO Wrapper UNO Components +Simple IO wrapper UNO components which includes `TextInputStream`, +`TextOutputStream`, pipes and stream helpers diff --git a/javaunohelper/README.md b/javaunohelper/README.md index 9896ef15c629..6b26e4aef764 100644 --- a/javaunohelper/README.md +++ b/javaunohelper/README.md @@ -1,2 +1,3 @@ -Makes it easier to use UNO with Java. +# Java UNO Helper +Makes it easier to use UNO with Java. diff --git a/jurt/README.md b/jurt/README.md index a2281d24bdca..f44052bf4d3f 100644 --- a/jurt/README.md +++ b/jurt/README.md @@ -1,2 +1,3 @@ -JURT means Java Uno Runtime and implements most of Java UNO. +# Java UNO Runtime (jurt) +JURT means Java UNO Runtime and implements most of Java UNO. diff --git a/jvmaccess/README.md b/jvmaccess/README.md index 54af22469516..f035e8f968ee 100644 --- a/jvmaccess/README.md +++ b/jvmaccess/README.md @@ -1 +1,4 @@ -Wrappers so you can use all the Java Runtime Environments with their slightly incompatible APIs with more ease. +# JVM Access Wrappers + +Wrappers so you can use all the Java Runtime Environments with their slightly +incompatible APIs with more ease. diff --git a/jvmfwk/README.md b/jvmfwk/README.md index 7cb338e14f32..b21540851683 100644 --- a/jvmfwk/README.md +++ b/jvmfwk/README.md @@ -1,15 +1,20 @@ +# JVM Framework Wrappers + Wrappers so you can use all the Java Runtime Environments with their slightly incompatible APIs with more ease. Used to use an over-engineered "plugin" mechanism although there was only one "plugin", called "sunmajor", that handles all possible JREs. -IMPORTANT: The <updated> element in vmfwk/distributions/OpenOfficeorg/javavendors_*.xml files +IMPORTANT: The `<updated>` element in `vmfwk/distributions/OpenOfficeorg/javavendors_*.xml` files should only be updated for incompatible changes, not for compatible ones. As stated in the commit -message of <https://gerrit.libreoffice.org/#/c/69730/> "javavendors_*.xml <updated> should not have -been updated...": "Changing <updated> causes jfw_startVM and jfw_getSelectedJRE (both -jvmfwk/source/framework.cxx) to fail with JFW_E_INVALID_SETTINGS, which in turn causes functionality +message of <https://gerrit.libreoffice.org/#/c/69730/> in LibreOffice gerrit: + +"**javavendors\_\*.xml \<updated\> should not have been updated...** + +Changing `<updated>` causes `jfw_startVM` and `jfw_getSelectedJRE` (both +`jvmfwk/source/framework.cxx`) to fail with `JFW_E_INVALID_SETTINGS`, which in turn causes functionality that requires a JVM to issue a GUI error dialog stating that the user must select a new JRE in the Options dialog. While that behavior makes sense if a JRE was selected that would no longer be -supported by the modified javavendors_*.xml, it is just annoying if an already selected JRE is still -supported. And a compatible change to javavendors_*.xml implies that an already selected JRE will +supported by the modified `javavendors_*.xml`, it is just annoying if an already selected JRE is still +supported. And a compatible change to `javavendors_*.xml` implies that an already selected JRE will still be supported." diff --git a/l10ntools/README.md b/l10ntools/README.md index c3cf50b13eca..b55377cf4a3a 100644 --- a/l10ntools/README.md +++ b/l10ntools/README.md @@ -1,3 +1,5 @@ -l10ntools (l10n = localization) contains a number of tools that extract +# Localization (l10n) Tools + +`l10ntools` (l10n = localization) contains a number of tools that extract translatable content from source code and merge translations back to source code during the build. diff --git a/librelogo/README.md b/librelogo/README.md index af75698f5f2d..1cbc48611c16 100644 --- a/librelogo/README.md +++ b/librelogo/README.md @@ -1 +1,3 @@ +# LibreLogo Programming Language + LibreLogo is a Logo-like programming language with interactive vectorgraphics for education and DTP diff --git a/libreofficekit/README.md b/libreofficekit/README.md index d346770e0e1d..4932b791d319 100644 --- a/libreofficekit/README.md +++ b/libreofficekit/README.md @@ -1,5 +1,4 @@ -LibreOfficeKit -************** +# LibreOfficeKit LibreOfficeKit can be used for accessing LibreOffice functionality through C/C++, without any need to use UNO. @@ -7,8 +6,7 @@ through C/C++, without any need to use UNO. For now it only offers document conversion (in addition to an experimental tiled rendering API). -Integrating LOK into other software ------------------------------------ +## Integrating LOK Into Other Software LOK functionality can be accessed by including LibreOfficeKit.h[xx] in your program. @@ -23,11 +21,10 @@ functionality as in LibreOfficeKit.h.) An example program can be seen on: https://gitlab.com/ojwb/lloconv -Tiled Rendering ---------------- +## Tiled Rendering To use LOK Tiled Rendering you will need the following before the LOK includes: -#define LOK_USE_UNSTABLE_API + #define LOK_USE_UNSTABLE_API (This must be define before ANY LOK header, i.e. including the Init header.) @@ -36,8 +33,7 @@ colorspace (further alternatives could feasibly be implemented as needed). Scanlines are ordered top-down (whereas LibreOffice will internally default to bottom-up). -Tiled Editing -------------- +## Tiled Editing On top of the tiled rendering API, a set of new methods have been added to the lok::Document class to allow basic editing, too. Communication between the LOK @@ -46,14 +42,14 @@ by calling the above mentioned methods. The most important methods for the client -> LibreOffice communication are: - initializeForRendering(), expected to be called right after - lok::Office::documentLoad() returned a lok::Document*. -- postKeyEvent(), expected to be called when the user provides input on the + `lok::Office::documentLoad()` returned a `lok::Document*`. +- `postKeyEvent()`, expected to be called when the user provides input on the (soft-)keyboard. -- postMouseEvent(), expected to be called when the user generated a touch or +- `postMouseEvent()`, expected to be called when the user generated a touch or mouse event. In general, all coordinates are always in absolute twips (20th of a point, or: -1" = 1440 twips). See lok::Document in LibreOfficeKit.hxx for a full list of +1" = 1440 twips). See `lok::Document` in `LibreOfficeKit.hxx` for a full list of methods and their documentation. The other way around (LibreOffice -> LOK client) is implemented using a @@ -64,11 +60,11 @@ LibreOfficeKitCallbackType enumeration in LibreOfficeKitEnums.h, the callback function signature itself is provided by the LibreOfficeKitCallback typedef in LibreOfficeKitTypes.h. The most important callback types: -- LOK_CALLBACK_INVALIDATE_TILES: drop all tiles cached on client-side that +- `LOK_CALLBACK_INVALIDATE_TILES`: drop all tiles cached on client-side that intersect with the provided rectangle -- LOK_CALLBACK_INVALIDATE_VISIBLE_CURSOR: need to set the position and/or the +- `LOK_CALLBACK_INVALIDATE_VISIBLE_CURSOR`: need to set the position and/or the size of the cursor -- LOK_CALLBACK_TEXT_SELECTION: need to adjust the selection overlay provided +- `LOK_CALLBACK_TEXT_SELECTION`: need to adjust the selection overlay provided by the client as the set of rectangles describing the selection overlay changed @@ -90,7 +86,7 @@ To run gtktiledviewer: bin/run gtktiledviewer --lo-path=$PWD/instdir/program path/to/test.odt -To receive all incoming events from core use G_MESSAGES_DEBUG=all +To receive all incoming events from core use `G_MESSAGES_DEBUG=all` G_MESSAGES_DEBUG=all bin/run gtktiledviewer --lo-path=$PWD/instdir/program ../test.odt @@ -100,10 +96,9 @@ To debug with gdb: before bin/run, this will run gtktiledviewer in the debugger instead. -LibreOfficeKitGtk -***************** +## LibreOfficeKitGtk -Currently consists of only a very basic GTK+ document viewer widget. +Currently consists of only a very basic GTK document viewer widget. -The widget uses g_info() instead of SAL_INFO(), use the 'G_MESSAGES_DEBUG=all' +The widget uses `g_info()` instead of `SAL_INFO()`, use the `G_MESSAGES_DEBUG=all` environment variable to display those messages. diff --git a/lingucomponent/README.md b/lingucomponent/README.md index b2e6717a7fec..b9e1ef5e8dc9 100644 --- a/lingucomponent/README.md +++ b/lingucomponent/README.md @@ -1 +1,3 @@ -Spellcheck, hyphenator, thesaurus, etc. +# Lingustics Components + +`lingucomponent` contains spellcheck, hyphenator, thesaurus, etc. diff --git a/linguistic/README.md b/linguistic/README.md index 39f447ce1121..f77438a6cde8 100644 --- a/linguistic/README.md +++ b/linguistic/README.md @@ -1 +1,3 @@ -Handles registered modules for spellchecker, hyphenator and thesaurus. +# Linguistics Components Manager + +`linguistic` module handles the registered modules for spellchecker, hyphenator and thesaurus. diff --git a/lotuswordpro/README.md b/lotuswordpro/README.md index a1e3c20e0167..fc58c3fe439c 100644 --- a/lotuswordpro/README.md +++ b/lotuswordpro/README.md @@ -1,31 +1,31 @@ -Import filter for file format of Lotus Word Pro. +# Import Filter for File Format of Lotus Word Pro (lwp) -== Description == +## Description The import is not direct, but via an intermediate format: StarOffice XML, the predecessor of ODF (yes, the code is old). The entry point to the filter is class LotusWordProImportFilter (refer to Source code section), but that just hooks up the necessary machinery for processing StarOffice XML produced by the filter. The real fun starts in function -ReadWordproFile() (source/filter/lwpfilter.cxx); this function -initializes the parser (class Lwp9Reader) and the SAX XML handler that -produces the output (class XFSaxStream). The Lwp9Reader class then does +`ReadWordproFile()` (`source/filter/lwpfilter.cxx`); this function +initializes the parser (class `Lwp9Reader`) and the SAX XML handler that +produces the output (class `XFSaxStream`). The Lwp9Reader class then does the actual parsing. If the module is built with debug level greater than 0, it is possible to examine the intermediate XML: set environment variable -DBG_LWPIMPORT_DIR= to an existing directory and, on opening an lwp -document, a file named lwpimport.xml will be created in that directory. +`DBG_LWPIMPORT_DIR=` to an existing directory and, on opening an lwp +document, a file named `lwpimport.xml` will be created in that directory. -== Source code == +## Source Code -=== Module contents === -* inc: module-global headers (can be included by any file in source) -* qa: cppunit tests -* source: the filter itself -* util: UNO passive registration config +### Module Contents +* `inc`: module-global headers (can be included by any file in source) +* `qa`: `cppunit` tests +* `source`: the filter itself +* `util`: UNO passive registration config -=== Source contents === -* filter: lwp document format parser -* filter/LotusWordProImportFilter.cxx: the entry point to the filter -* filter/xfilter: export to StarOffice XML +### Source Contents +* `filter`: `lwp` document format parser +* `filter/LotusWordProImportFilter.cxx`: the entry point to the filter +* `filter/xfilter`: export to StarOffice XML diff --git a/m4/README.md b/m4/README.md index 33ac576e2685..a174a61ef23f 100644 --- a/m4/README.md +++ b/m4/README.md @@ -1 +1,3 @@ -m4 - Macros to locate and utilise pkg-config. +# m4 Macros + +m4 - Macros to locate and utilise `pkg-config`. diff --git a/nlpsolver/README.md b/nlpsolver/README.md index 4142e4344a0d..4f929e0d3dc9 100644 --- a/nlpsolver/README.md +++ b/nlpsolver/README.md @@ -1,4 +1,7 @@ -This extension integrates into Calc and offers new Solver engines to use for optimizing nonlinear programming models. +# New Linear Programming Solver (nlpsolver) -As there is no known upstream source for nlpsolver/ThirdParty/EvolutionarySolver, -the code is considered internal and can be modified like any other internal code.
\ No newline at end of file +This extension integrates into LibreOffice Calc and offers new Solver engines to use for optimizing +nonlinear programming models. + +As there is no known upstream source for `nlpsolver/ThirdParty/EvolutionarySolver`, +the code is considered internal and can be modified like any other internal code. diff --git a/o3tl/README.md b/o3tl/README.md index 7900e70171d0..89cb9a5c1315 100644 --- a/o3tl/README.md +++ b/o3tl/README.md @@ -1,30 +1,38 @@ -Very basic template functionality, a bit like boost or stl, but specific to LibO +# LibreOffice Template Library -o3tl stands for "OOo [o3, get it?] template library" +Very basic template functionality, a bit like boost or STL, but specific to LibreOffice. -From [http://blog.thebehrens.net/2006/01/15/update-cow_wrapper-is-available-now/] +o3tl stands for "OOo [o3, get it?] template library", in which OOo stands for OpenOffice.org, +predecessor of LibreOffice. + +From <https://blog.thebehrens.net/2006/01/15/update-cow_wrapper-is-available-now/> The scope for o3tl is admittedly kind of ambitious, as it should contain "...very basic (template) functionality, comparable to what's provided by boost or stl, but specific to OOo (what comes to mind -are e.g. stl adapters for our own data types and UNO, and stuff that could in principle be upstreamed +are e.g. STL adapters for our own data types and UNO, and stuff that could in principle be upstreamed to boost, but isn't as of now)." -== Class overview == +## Class Overview + +- `git:o3tl/inc/o3tl/cow_wrapper.hxx` + + A copy-on-write wrapper. + +- `git:o3tl/inc/o3tl/lazy_update.hxx` + + This template collects data in input type, and updates the output type with the given update functor, + but only if the output is requested. Useful if updating is expensive, or input changes frequently, but + output is only comparatively seldom used. + +- `git:o3tl/inc/o3tl/range.hxx` -[git:o3tl/inc/o3tl/cow_wrapper.hxx] -A copy-on-write wrapper. + Represents a range of integer or iterator values. -[git:o3tl/inc/o3tl/lazy_update.hxx] -This template collects data in input type, and updates the output type with the given update functor, -but only if the output is requested. Useful if updating is expensive, or input changes frequently, but -output is only comparatively seldom used. +- `git:o3tl/inc/o3tl/vector_pool.hxx` -[git:o3tl/inc/o3tl/range.hxx] -Represents a range of integer or iterator values. + Simple vector-based memory pool allocator. -[git:o3tl/inc/o3tl/vector_pool.hxx] -Simple vector-based memory pool allocator. +- `git:o3tl/inc/o3tl/functional.hxx` -[git:o3tl/inc/o3tl/functional.hxx] -Some more templates, leftovers in spirit of STLport's old functional -header that are not part of the C++ standard (STLport has been -replaced by direct use of the C++ STL in LibreOffice). + Some more templates, leftovers in spirit of STLport's old functional + header that are not part of the C++ standard (STLport has been + replaced by direct use of the C++ STL in LibreOffice). diff --git a/odk/README.md b/odk/README.md index 4370e63e594f..ee54679bb13c 100644 --- a/odk/README.md +++ b/odk/README.md @@ -1,27 +1,29 @@ -Office development kit - implements the first step on the way to the LibreOffice SDK tarball. +# Office Development Kit (odk) -Part of the SDK; to build you need to add --enable-odk. +Office development kit (`odk`) - implements the first step on the way to the LibreOffice SDK +tarball. +Part of the SDK; to build you need to add `--enable-odk`. -Testing the examples: -===================== -* Go to instdir/sdk (Don't try directly in odk/) +## Testing the Examples: + +* Go to `instdir/sdk` (Don't try directly in `odk/`) * See <https://api.libreoffice.org/docs/install.html> how to set up the SDK. -** When asked about it during configuration, tell the SDK to do automatic - deployment of the example extensions that get built. + * When asked about it during configuration, tell the SDK to do automatic + deployment of the example extensions that get built. -* In a shell set up for SDK development, build (calling "make") and test - (following the instructions given at the end of each "make" invocation) each - of the SDK's examples/ sub-directories. +* In a shell set up for SDK development, build (calling `make`) and test + (following the instructions given at the end of each `make` invocation) each + of the SDK's `examples/` sub-directories. -** An example script to build (though not test) the various examples in batch - mode is + * An example script to build (though not test) the various examples in batch + mode is - find examples \( -type d -name nativelib -prune \) -o \ - \( -name Makefile -a -print -a \( -execdir make \; -o -quit \) \) + `find examples \( -type d -name nativelib -prune \) -o \` + `\( -name Makefile -a -print -a \( -execdir make \; -o -quit \) \)` - (Note that one of the example extensions asks you to accept an example - license on stdin during deployment.) + (Note that one of the example extensions asks you to accept an example + license on stdin during deployment.) diff --git a/offapi/README.md b/offapi/README.md index 80c60484d1c7..1d35bd2ca51a 100644 --- a/offapi/README.md +++ b/offapi/README.md @@ -1,19 +1,21 @@ -Contains all of the IDL files except those in [[udkapi]] +# LibreOffice API IDL Files Except UDK API + +Contains all of the IDL files except those in `udkapi`. i.e. the interfaces that are specific to the LibreOffice application. An artificial (?) separation. -The reference offapi/type_reference/offapi.idl and -udkapi/type_reference/udkapi.idl (formerly combined into a single -offapi/type_reference/types.rdb) are used to detect inadvertent incompatible -changes. They are plain-text .idl files (not strictly lexicographically sorted, -though, so they satisfy the .idl file requirements for no forward dependencies), +The reference `offapi/type_reference/offapi.idl` and +`udkapi/type_reference/udkapi.idl` (formerly combined into a single +`offapi/type_reference/types.rdb`) are used to detect inadvertent incompatible +changes. They are plain-text `.idl` files (not strictly lexicographically sorted, +though, so they satisfy the `.idl` file requirements for no forward dependencies), so in cases where we deliberately /do/ become incompatible they can be modified manually. Old such cases of deliberately becoming incompatible are listed in -offapi/type_reference/typelibrary_history.txt, newer such cases are recorded in -the git logs of (now superseded) offapi/type_reference/types.rdb, -offapi/type_reference/offapi.rdb, and udkapi/type_reference/udkapi.rdb, new such -cases are recorded in the git logs of offapi/type_reference/offapi.idl and -udkapi/type_reference/udkapi.idl. +`offapi/type_reference/typelibrary_history.txt`, newer such cases are recorded in +the `git log`s of (now superseded) `offapi/type_reference/types.rdb`, +`offapi/type_reference/offapi.rdb`, and `udkapi/type_reference/udkapi.rdb`, new such +cases are recorded in the `git log`s of `offapi/type_reference/offapi.idl` and +`udkapi/type_reference/udkapi.idl`. diff --git a/officecfg/README.md b/officecfg/README.md index f8861307d0db..c3af00834232 100644 --- a/officecfg/README.md +++ b/officecfg/README.md @@ -1,11 +1,12 @@ -The schema and default settings for the OpenOffice.org configuration database. +# Default Settings for LibreOffice + +The schema and default settings for the LibreOffice configuration database. If you change a file in this module, then a make postprocess is needed after make officecfg. -See also: -[[configmgr]] +See also: `configmgr` -AcceleratorKeyChecker.fodt in the util folder is a tool written in Basic that check menus for +`AcceleratorKeyChecker.fodt` in the `util` folder is a tool written in Basic that check menus for entries that use the same accelerator key. The tool goes through the menus using the accessibility api and checks the accelerator keys. For information on how to use the tool open the fodt file in LibreOffice. diff --git a/onlineupdate/README.md b/onlineupdate/README.md index 485a718499b3..0162776a618c 100644 --- a/onlineupdate/README.md +++ b/onlineupdate/README.md @@ -1,25 +1,38 @@ +# Online Update + Online update implementation based on Mozilla's MAR format + update mechanism Parts of this code are copied from the mozilla repository, and adapted to LibreOffice needs: -firefox/modules/libmar -> onlineupdate/source/libmar -firefox/toolkit/mozapps/update -> onlineupdate/source/update +`firefox/modules/libmar` -> `onlineupdate/source/libmar` +`firefox/toolkit/mozapps/update` -> `onlineupdate/source/update` + +The source/service directory contains the code for the silent windows updater that avoids the +repeated administrator check for an update. -The source/service directory contains the code for the silent windows updater that avoids the repeated administrator check for an update. +## Note -== NOTE == -The updater executable should not depend on any other dynamic library in the LibreOffice installation as we would need to copy that one also to a temporary directory during update. We can't update any library or executable that is currently in use. For the updater executable we solve this problem by copying the updater before using it to a temporary directory. +The updater executable should not depend on any other dynamic library in the LibreOffice +installation as we would need to copy that one also to a temporary directory during update. We can't +update any library or executable that is currently in use. For the updater executable we solve this +problem by copying the updater before using it to a temporary directory. On Windows we use the system to provide us with a crypto library whereas on Linux we use NSS. -== Update procedure == +## Update Procedure -The updater executable is run two times. In a first run, the current installation is copied to a "update" directory and the update is applied in this "update" directory. During the next run, a replacement request is executed. The replacement request removes the old installation directory and replaces it with the content of the "update" directory. +The updater executable is run two times. In a first run, the current installation is copied to an +`update` directory and the update is applied in this `update` directory. During the next run, a +replacement request is executed. The replacement request removes the old installation directory and +replaces it with the content of the `update` directory. -=== User profile in the installation directory === +### User Profile in the Installation Directory -The archive based installations have the user profile by default inside of the installation directory. During the update process this causes some problems that need special handling in the updater. +The archive based installations have the user profile by default inside of the installation +directory. During the update process this causes some problems that need special handling in the +updater. -* The "update" directory is inside of the user profile resulting in recursive copying. -* During the replacement request the updater log is in the user profile, which changes location from the actual location to a backup location. +* The `update` directory is inside of the user profile resulting in recursive copying. +* During the replacement request the updater log is in the user profile, which changes location from +the actual location to a backup location. diff --git a/oovbaapi/README.md b/oovbaapi/README.md index e869b5e45741..7f3399956a20 100644 --- a/oovbaapi/README.md +++ b/oovbaapi/README.md @@ -1,5 +1,8 @@ -Module for OpenOffice - VisualBasic interoperability. +# Visual Basic Interoperability -See also: -[http://wiki.openoffice.org/wiki/VBA] -[http://wiki.openoffice.org/wiki/Oovbaapi] +Visual Basic interoperability module for LibreOffice + +## See also + +- <http://wiki.openoffice.org/wiki/VBA> +- <http://wiki.openoffice.org/wiki/Oovbaapi> diff --git a/oox/README.md b/oox/README.md index 6c459f58c92a..8f42418dd902 100644 --- a/oox/README.md +++ b/oox/README.md @@ -1,15 +1,16 @@ -Support for Office Open XML, the office XML-format designed by Microsoft. +# Office Open XML (ooxml) Support +Support for Office Open XML, the office XML-format designed by Microsoft. -== DrawingML Custom shapes and presets == +## DrawingML Custom shapes and presets Custom shapes are part of DrawingML and are different to binary ppt and VML in older formats. -The import happens in oox/source/drawingml, where they are +The import happens in `oox/source/drawingml`, where they are imported as LO's enhanced custom shape's. see -offapi/com/sun/star/drawing/CustomShape.idl and -offapi/com/sun/star/drawing/EnhancedCustomShape*.idl -Check CustomShapeProperties::pushToPropSet() and see +`offapi/com/sun/star/drawing/CustomShape.idl` and +`offapi/com/sun/star/drawing/EnhancedCustomShape*.idl` +Check `CustomShapeProperties::pushToPropSet()` and see how custom shape properties are converted. Preset shapes are custom shapes whose guides and handles @@ -120,8 +121,8 @@ example of drawingml custom shape (equal to star5 preset): </pathLst> we needed to extend our custom shapes for missing features and so 5 -new segment commands were added. G command for arcto drawingml record -and H I J K commands for darken, darkenless, lighten, lightenless +new segment commands were added. `G` command for arcto drawingml record +and `H` `I` `J` `K` commands for darken, darkenless, lighten, lightenless records. the commands are save into ODF in special namespace drawooo, which is extension not yet in the standard. Thorsten suggested to put it in such a namespace and keep original (incomplete) geometry for @@ -132,14 +133,14 @@ needed. In order to convert preset shapes to LO's enhanced custom shape, we need to load shape definition of preset shapes. The procedure to convert the definition from OOXML spec for LO is documented -( also a script ) in oox/source/drawingml/customshapes/README. -The scripts in oox/source/drawingml/customshapes/ also generate pptx +(also a script) in `oox/source/drawingml/customshapes/README.md`. +The scripts in `oox/source/drawingml/customshapes/` also generate pptx files for single presets and also for all presets -cshape-all.pptx. The cshape-all.pptx file is then loaded into Impress +`cshape-all.pptx`. The cshape-all.pptx file is then loaded into Impress build with debug enabled in oox and the command line output contains -information. The generated definition is oox-drawingml-cs-presets. +information. The generated definition is `oox-drawingml-cs-presets`. -Check CustomShapeProperties::initializePresetDataMap() to see how +Check `CustomShapeProperties::initializePresetDataMap()` to see how generated presets data are loaded into LO. While importing presets, we prefix the name with "ooxml-" so that we can detect it on export as save it again as preset. @@ -151,12 +152,12 @@ problem with these pptx as they cannot be imported into powerpoint, but that can be fixed quickly. when fixed, we can use it to test powerpoint odp export and see how complete it is regarding custom shapes. OpenXML SDK tools might help when fixing -cshape-all.pptx -http://www.microsoft.com/en-us/download/details.aspx?id=30425 +`cshape-all.pptx` +<http://www.microsoft.com/en-us/download/details.aspx?id=30425> -== Export == +## Export Here is how LO's enhanced custom shapes are exported: -* Shape name is ooxml-* - they are imported from ooxml, export as is. +* Shape name is `ooxml-*` - they are imported from ooxml, export as is. * Denylist - ODF presets that has OOXML equivalent. We convert adjustment values case by case. Microsoft Office is rather strict about adjustment values, either none of them @@ -166,20 +167,19 @@ Here is how LO's enhanced custom shapes are exported: so that default values suitable for the odf one need to be provided. * Allowlist - ODF presets that has OOXML equivalent but looks a bit -different, export them as PolyPolygon. +different, export them as `PolyPolygon`. -Check Andras Timar's presentation[1] and ShapeExport::WriteCustomShape() +Check Andras Timar's presentation[1] and `ShapeExport::WriteCustomShape()` for further detail. -FUTURE WORK: because we have to make sure that all the roundtrips +## Future Works +Because we have to make sure that all the roundtrips like PPTX --> ODP --> PPTX work correctly and doesn't lose data. the only problematic part is probably saving custom shapes (ie. not presets) to PPTX. that part of code predates work on custom shapes and is unable to export general custom shapes yet. It will need a bit -of work as LO has more complex equations than DrawingML. other parts +of work as LO has more complex equations than `DrawingML`. other parts should work OK, PPTX --> ODP should work and don't lose any data. presets should already survive PPTX --> ODP --> PPTX roundtrip -[1]https://archive.fosdem.org/2016/schedule/event/drawingml/attachments/ -slides/1184/export/events/attachments/drawingml/slides/1184/ -andras_timar_fosdem_2016.pdf +[1] <https://archive.fosdem.org/2016/schedule/event/drawingml/attachments/slides/1184/export/events/attachments/drawingml/slides/1184/andras_timar_fosdem_2016.pdf> diff --git a/opencl/README.md b/opencl/README.md index c5699e797a50..9d9be77a7a36 100644 --- a/opencl/README.md +++ b/opencl/README.md @@ -1,3 +1,5 @@ +# OpenCL Support + OpenCL-related code that is not specific to any particular functionality OpenCL is used for. (Like formula group calculation in Calc.) diff --git a/osx/README.md b/osx/README.md index 260a7ed48276..d52607e9673a 100644 --- a/osx/README.md +++ b/osx/README.md @@ -1,4 +1,6 @@ -Just an Xcode project to make it easier to debug a running soffice +# Xcode Project for Debugging LibreOffice on macOS + +Just an Xcode project to make it easier to debug a running `soffice` instance on macOS. Not intended for other use. The Xcode project has references to a fairly arbitrary bunch of source files from here and -there in LO that I have happened to been debugging in Xcode on macOS.
\ No newline at end of file +there in LibreOffice that I have happened to debug in Xcode on macOS. diff --git a/package/README.md b/package/README.md index c9055dfee91a..c85ce979044d 100644 --- a/package/README.md +++ b/package/README.md @@ -1 +1,3 @@ -Reading and writing ZIPs. +# ZIP Support + +Reading and writing ZIP files. diff --git a/pch/README.md b/pch/README.md index b6c8ca9dd932..4aebbc94b3de 100644 --- a/pch/README.md +++ b/pch/README.md @@ -1,3 +1,5 @@ +# Precompiled Headers + The purpose of this directory is to generate global precompiled headers -that can be used by any other gbuild library/executable. +that can be used by any other gbuild library / executable. The libraries themselves are not used. diff --git a/postprocess/README.md b/postprocess/README.md index a29596729bd0..aa642247e77d 100644 --- a/postprocess/README.md +++ b/postprocess/README.md @@ -1,6 +1,8 @@ +# Postprocessing and Checking + Postprocessing and checking of files delivered by other modules. This module has to be the last one built before creating install sets -in module 'instset_native'. Thus it ties together all the dependencies +in module `instset_native`. Thus it ties together all the dependencies of all the other de-coupled modules. See the first line of -[[postprocess/prj/build.lst]] for that. +`postprocess/prj/build.lst` for that. diff --git a/pyuno/README.md b/pyuno/README.md index 4d88391229f1..95e487706788 100644 --- a/pyuno/README.md +++ b/pyuno/README.md @@ -1,19 +1,22 @@ +# Python UNO Bindings + UNO bindings for the Python programming language. -To have much joy debugging python extensions you need to: - a) edit pythonloader.py in your install setting DEBUG=1 at the top - b) touch pyuno/source/module/pyuno_runtime.cxx and 'make debug=true' in pyuno +To have much joy debugging Python extensions you need to: + ++ a) edit `pythonloader.py` in your install setting `DEBUG=1` at the top ++ b) `touch pyuno/source/module/pyuno_runtime.cxx` and `make debug=true` in `pyuno` Then you'll start to see your exceptions on the console instead of them getting lost at the UNO interface. Python also comes with a gdb script -libpython$(PYTHON_VERSION_MAJOR).$(PYTHON_VERSION_MINOR)m.so.1.0-gdb.py -that is copied to instdir and will be auto-loaded by gdb; -it provides commands like "py-bt" to get a python-level backtrace, -and "py-print" to print python variables. +`libpython$(PYTHON_VERSION_MAJOR).$(PYTHON_VERSION_MINOR)m.so.1.0-gdb.py` +that is copied to `instdir` and will be auto-loaded by `gdb`; +it provides commands like `py-bt` to get a Python-level backtrace, +and `py-print` to print Python variables. -Another way to debug Python code is to use pdb: edit some initialization -function to insert "import pdb; pdb.set_trace()" (somewhere so that it is -executed early), then run soffice from a terminal and a command-line python -debugger will appear where you can set python-level breakpoints. +Another way to debug Python code is to use `pdb`: edit some initialization +function to insert `import pdb; pdb.set_trace()` (somewhere so that it is +executed early), then run `soffice` from a terminal and a command-line Python +debugger will appear where you can set Python-level breakpoints. diff --git a/qadevOOo/README.md b/qadevOOo/README.md index 50569304a383..91c1431263f9 100644 --- a/qadevOOo/README.md +++ b/qadevOOo/README.md @@ -1,3 +1,3 @@ -Testsuite. +# Test Suite -You can import this as a project into Eclipse (select the qadevOOo folder).
\ No newline at end of file +You can import this as a project into Eclipse (select the `qadevOOo` folder). diff --git a/readlicense_oo/README.md b/readlicense_oo/README.md index eb6c4482df15..2eae0bf5c3a6 100644 --- a/readlicense_oo/README.md +++ b/readlicense_oo/README.md @@ -1,33 +1,34 @@ +# LibreOffice Licensing Blurb + Contains the stock libreoffice licensing blurb, as distributed in the install directory, and also potentially at run-time. -Generating licence files ------------------------- +## Generating Licence Files -License files are generated from a single source file (license/license.xml). +License files are generated from a single source file (`license/license.xml`). Output file formats are plain text and html. -- The plain text and the html format is generated with xslt. There are two - separate xsl files for plain text and html. +- The plain text and the html format is generated with XSLT. There are two + separate XSL files for plain text and html. -Conditional text ----------------- +## Conditional Text The contents of the license file depends on the build configuration. Several externals may or may not be shipped with LibreOffice. Therefore, we need to pass -information about build configuration to the xslt processor. +information about build configuration to the XSLT processor. Variables used for conditional text: -- BUILD_TYPE: A space separated list of libraries/externals. If an external is +- `BUILD_TYPE`: A space separated list of libraries/externals. If an external is present in that list, then the related license text should be included. -- MPL_SUBSET: If the variable is defined, then GPL and LGPL license text will not +- `MPL_SUBSET`: If the variable is defined, then GPL and LGPL license text will not be included, because none of the built-in code need it. -- OS: The target platform. E.g. MSVC Runtime is packaged and used only on Windows. +- `OS`: The target platform. E.g. MSVC Runtime is packaged and used only on Windows. + +- `WITH_THEMES`: A space separated list of icon sets that are used in the build. -- WITH_THEMES: A space separated list of icon sets that are used in the build. +Conditional text are surrounded by and extra `<div>` tag. The class attribute of +that `<div>` tag decides which parameter values are taken into consideration. -Conditional text are surrounded by and extra <div> tag. The class attribute of -that <div> tag decides which parameter values are taken into consideration. diff --git a/registry/README.md b/registry/README.md index 914db30a2f01..617ef4a73b81 100644 --- a/registry/README.md +++ b/registry/README.md @@ -1,8 +1,8 @@ -Registry reading, etc. +# Registry Reading, etc This provides tools for dealing with the legacy binary types database format, still in use by extensions and the core code. While the actual -binary file format is implemented by the [[store]] code, the wrapper +binary file format is implemented by the `store` code, the wrapper that turns this into a type registry is implemented here. While this code is primarily used in only two modes: diff --git a/remotebridges/README.md b/remotebridges/README.md index cfe0d196afef..8f1879f865a7 100644 --- a/remotebridges/README.md +++ b/remotebridges/README.md @@ -1 +1,3 @@ +# Bridges to UNO Services + UNO services dealing with interprocess bridges. diff --git a/reportbuilder/README.md b/reportbuilder/README.md index 696cc4b4830a..a1a9ab2a5a30 100644 --- a/reportbuilder/README.md +++ b/reportbuilder/README.md @@ -1,7 +1,9 @@ +# Report Builder + Report Builder, or "new style reports", replacing legacy reports (in reportdesign). Started as an extension called "Sun Report Builder" then "Oracle Report Builder" -[http://extensions.services.openoffice.org/project/reportdesign], +<https://extensions.openoffice.org/project/reportdesign>, which got bundled with LibreOffice, then converted to an optionally installable (but installed by default) part of LibreOffice proper. -Uses the Pentaho Reporting Flow Engine of Pentaho BI [http://www.pentaho.com/]. +Uses the Pentaho Reporting Flow Engine of Pentaho BI <http://www.pentaho.com/>. diff --git a/reportdesign/README.md b/reportdesign/README.md index 0cffd43da3ef..7f90d985ac2d 100644 --- a/reportdesign/README.md +++ b/reportdesign/README.md @@ -1 +1,3 @@ +# Legacy Reports + Legacy Reports for LibreOffice Base diff --git a/ridljar/README.md b/ridljar/README.md index 0f3afff183a8..437f24c2cd10 100644 --- a/ridljar/README.md +++ b/ridljar/README.md @@ -1 +1,3 @@ -Implements types for the Java Uno typesystem. +# Java UNO Types Generator + +Implements types for the Java UNO typesystem. diff --git a/sal/README.md b/sal/README.md index 324c64fa4a78..deaf7b4c0417 100644 --- a/sal/README.md +++ b/sal/README.md @@ -1,9 +1,11 @@ +# System Abstraction Layer (SAL) + System abstraction layer; rtl, osl and sal -rtl: +`rtl`: Platform independent strings -osl: +`osl`: platform specific stuff, threads, dynamic loading, process, ipc, etc Exports only C API and some inline-methods (only C++ API). diff --git a/salhelper/README.md b/salhelper/README.md index 019a562df485..bc76adb2973e 100644 --- a/salhelper/README.md +++ b/salhelper/README.md @@ -1 +1,3 @@ -C++ helpers to make use of sal easier. +# C++ Helpers for SAL + +C++ helpers to make use of SAL easier. diff --git a/sax/README.md b/sax/README.md index 00ca0f1af5ae..30ae23197afa 100644 --- a/sax/README.md +++ b/sax/README.md @@ -1,13 +1,15 @@ +# UNO Services for SAX + UNO services for SAX parsing and C++ functions for XMLSchema-2 data types. -* source/expwrap: +* `source/expwrap`: string-based SAX parser UNO service wrapping expat -* source/fastparser: +* `source/fastparser`: multi-threaded token-based SAX parser UNO service wrapping libxml2 -* source/tools: +* `source/tools`: + C++ wrapper for fast SAX parser + C++ XMLSchema-2 data type conversion helpers Multi-threading in FastParser can be disabled for debugging purposes with: -SAX_DISABLE_THREADS=1 SAL_LOG="+INFO.sax.fastparser+WARN" + SAX_DISABLE_THREADS=1 SAL_LOG="+INFO.sax.fastparser+WARN" diff --git a/sc/README.md b/sc/README.md index e355e0c3c612..b28b1b769c71 100644 --- a/sc/README.md +++ b/sc/README.md @@ -1,36 +1,38 @@ -Spreadsheet application code. +# Spreadsheet Application Code You can dump some information in a dbgutil build: -=== CTRL+SHIFT+F12 === +## Shortcuts + +### CTRL+SHIFT+F12 Dumps the column width of the first 20 columns. -=== CTRL+SHIFT+F11 === +### CTRL+SHIFT+F11 Dumps the graphic objects and their position and size in pixel. -=== CTRL+SHIFT+F6 === +### CTRL+SHIFT+F6 Dumps the SfxItemSet representing the cell properties' of the current selection as a xml file. The file will be named dump.xml -=== The Cache Format === +## The Cache Format ScDocument::StoreTabToCache allows storing the content (not the formatting) of a table to a binary cache format. The format is column orientated which allows quick serialization of the table. -Header: +* Header: * Number of Columns: 64 bit unsigned integer -Column: +* Column: * Column Index: 64 bit unsigned integer * Column Size: 64 bit unsigned integer * For each cell type block a new ColumnBlock -ColumnBlock: +* ColumnBlock: * Start Row: 64 bit unsigned integer * Block Size: 64 bit unsigned integer * Type: 8 bit unsigned integer @@ -42,8 +44,7 @@ ColumnBlock: - 3 : formula * for each cell: 32 bit signed string length followed by the formula in R1C1 notation as a string - -=== Functions supporting Wildcards or Regular Expressions === +## Functions Supporting Wildcards or Regular Expressions As this comes up every now and then, and rather should be documented in an extra list of the Help system, functions that support Wildcards or Regular @@ -82,3 +83,4 @@ https://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os-part2.html * AVERAGEIFS * Text Functions * SEARCH + diff --git a/scaddins/README.md b/scaddins/README.md index 1e0f88eacbcf..6900c1da0b9f 100644 --- a/scaddins/README.md +++ b/scaddins/README.md @@ -1,8 +1,9 @@ -Extra functions for calc. +# Extra Functions for LibreOffice Calc -These provide UNO components that implement more exotic calc +These provide UNO components that implement more exotic LibreOffice Calc functions. If you want to do the same, here can be a good place to start. -See also: -[http://wiki.openoffice.org/wiki/Scaddins] +## See also + +- <https://wiki.openoffice.org/wiki/Scaddins> diff --git a/sccomp/README.md b/sccomp/README.md index 30cc7490cef3..7927fcda415d 100644 --- a/sccomp/README.md +++ b/sccomp/README.md @@ -1 +1,3 @@ +# Linear Solver for LibreOffice Calc + The (linear) solver for LibreOffice Calc. diff --git a/schema/README.md b/schema/README.md index f32038ed82c8..0df864e087b3 100644 --- a/schema/README.md +++ b/schema/README.md @@ -1,20 +1,23 @@ -schemas that can be used for validating ODF files +# Schemas for Validating ODF Files + +Schemas that can be used for validating ODF files subdirs: -- mathml2: W3C MathML 2.0 XML Schema (needed for Math embedded objects) -- odf1.0, odf1.1, odf1.2: official OASIS RelaxNG schemas -- odf1.3: current OASIS draft ODF 1.3 RelaxNG schema -- libreoffice: draft ODF schema, with additional LO extensions -The extension schema in "libreoffice/" is used by all unit tests if ---with-export-validation is given, which is the default. +- `mathml2`: W3C MathML 2.0 XML Schema (needed for Math embedded objects) +- `odf1.0`, `odf1.1`, `odf1.2`: official OASIS RelaxNG schemas +- `odf1.3`: current OASIS draft ODF 1.3 RelaxNG schema +- `libreoffice`: draft ODF schema, with additional LO extensions + +The extension schema in `libreoffice/` is used by all unit tests if +`--with-export-validation` is given, which is the default. Notably this means that if you add a new feature to the ODF filters and you add the required unit test for the new feature, then most likely the test will fail with a complaint from the validator; in this case the schema needs to be updated to contain the new elements and attributes. -The extension schema uses the RelaxNG "include" feature to refer to the ODF +The extension schema uses the `RelaxNG` "`include`" feature to refer to the ODF schema; this means that it only contains those parts of the schema that actually need to be changed - this works well in many cases because the ODF schema is quite well structured with many named patterns, but unfortunately @@ -22,7 +25,7 @@ there are a few places where that isn't the case and large chunks needed to be copied to override them. In the easy case, to add an attribute you just want to search for the -corresponding element, which will have a "foo-attlist" named pattern, and then +corresponding element, which will have a "`foo-attlist`" named pattern, and then add another attribute like this: <rng:define name="draw-enhanced-geometry-attlist" combine="interleave"> @@ -42,6 +45,6 @@ Unfortunately it turned out that there are a lot of extensions already for which no proposal exists [1], and in many cases not even an entry on the Wiki [2], so clearly something like this extension schema is needed. -[1] git grep TODO schema/libreoffice -[2] https://wiki.documentfoundation.org/Development/ODF_Implementer_Notes/List_of_LibreOffice_ODF_Extensions +[1] `git grep TODO schema/libreoffice` +[2] <https://wiki.documentfoundation.org/Development/ODF_Implementer_Notes/List_of_LibreOffice_ODF_Extensions> diff --git a/scp2/README.md b/scp2/README.md index 8f9d58356093..162e736b944f 100644 --- a/scp2/README.md +++ b/scp2/README.md @@ -1,6 +1,6 @@ -SCript Particle installer +# SCript Particle Installer This contains code that describes which pieces of the project should be packaged and installed - it is used to build among other things -a setup_osl.inf or .ins file - that is used by solenv/bin/make_installer.pl +a `setup_osl.inf` or `.ins` file - that is used by `solenv/bin/make_installer.pl` to build the installation. diff --git a/scripting/README.md b/scripting/README.md index 3a019e27d254..0560a73b9786 100644 --- a/scripting/README.md +++ b/scripting/README.md @@ -1,68 +1,70 @@ +# Scripting Framework + This module provides the source code for the Scripting Framework. For more information on the Scripting Framework, see the project web page: -[https://framework.openoffice.org/scripting/] +<https://framework.openoffice.org/scripting/> This module uses astyle to keep consistent java coding style. Please run -./Format_java_code.sh + ./Format_java_code.sh before committing. -== Source Code Structure == +## Source Code Structure The following directories contain the source code currently used by the Scripting Framework: -- source/provider +- `source/provider` -C++ source for the implementations of the com.sun.star.script.provider.* -and com.sun.star.script.browse.* UNO types. These types are used for +C++ source for the implementations of the `com.sun.star.script.provider.*` +and `com.sun.star.script.browse.*` UNO types. These types are used for browsing and executing scripts. -- source/protocolhandler +- `source/protocolhandler` -C++ for a ProtocolHandler implementation that handles vnd.sun.star.script +C++ for a `ProtocolHandler` implementation that handles `vnd.sun.star.script` URIs and dispatches them for execution to the Scripting Framework. -- source/basprov +- `source/basprov` -C++ implementation of the LanguageScriptProvider UNO service for Basic +C++ implementation of the `LanguageScriptProvider` UNO service for Basic -- source/dlgprov +- `source/dlgprov` -C++ implementation of the DialogProvider UNO service used for loading +C++ implementation of the `DialogProvider` UNO service used for loading UNO dialogs from various languages -- source/pyprov +- `source/pyprov` -LanguageScriptProvider for Python +`LanguageScriptProvider` for Python -- java/com/sun/star/script/framework/provider +- `java/com/sun/star/script/framework/provider` Implementation of an abstract base class ScriptProvider which provides -core methods for implementing Java based LanguageScriptProvider implementations +core methods for implementing Java based `LanguageScriptProvider` implementations -- java/com/sun/star/script/framework/provider/* +- `java/com/sun/star/script/framework/provider/*` -BeanShell, JavaScript and Java LanguageScriptProvider implementations +`BeanShell`, JavaScript and Java `LanguageScriptProvider` implementations -- java/com/sun/star/script/framework/browse/* +- `java/com/sun/star/script/framework/browse/*` -BrowseNode implementations for the Java based LanguageScriptProviders +`BrowseNode` implementations for the Java based `LanguageScriptProviders` -- java/com/sun/star/script/framework/io -- java/com/sun/star/script/framework/container +- `java/com/sun/star/script/framework/io` +- `java/com/sun/star/script/framework/container` Classes for performing script IO -- examples +- `examples` Example scripts in BeanShell, JavaScript, Java and Python -== Deprecated Code == +## Deprecated Code -- java/org/openoffice/* +- `java/org/openoffice/*` Support for developing scripts in IDEs such as NetBeans. diff --git a/sd/README.md b/sd/README.md index c250d81e7c6c..4413a0776210 100644 --- a/sd/README.md +++ b/sd/README.md @@ -1,43 +1,45 @@ +# LibreOffice Impress / Draw Application + The core directory for the impress/draw applications. Think of impress as a hack on top of draw. - -sd module contains impress/draw specific code, non-shared UI and part -of ppt and pptx filter, few other filters too. +`sd` module contains impress/draw specific code, non-shared UI and part +of `ppt` and `pptx` filter, few other filters too. the slideshow UI lives here as well, the slideshow engine is in -slideshow module though (including the 3D transitions engine -slideshow/source/engine/opengl). +`slideshow` module though (including the 3D transitions engine +`slideshow/source/engine/opengl`). -the most used filters are ODF's odp, binary ppt and OOXML's -pptx. their locations are listed below: +the most used filters are ODF's `odp`, binary ppt and OOXML's +`pptx`. their locations are listed below: - * odp import and export filters are in xmloff module (mostly xmloff/source/draw) + * `odp` import and export filters are in `xmloff` module (mostly `xmloff/source/draw`) - * ppt import is in sd/source/filter/ppt (big shared chunks are also in svx) - * ppt export is in sd/source/filter/eppt (big shared chunks are also in svx) + * `ppt` import is in `sd/source/filter/ppt` (big shared chunks are also in `svx`) + * `ppt` export is in `sd/source/filter/eppt` (big shared chunks are also in `svx`) - * pptx import is in oox/source/ppt (and uses a lot of - oox/source/drawingml and oox/source/*) - * pptx export is in sd/source/filter/eppt (mostly in pptx-* source - files) and shared part is in oox/source/export + * `pptx` import is in `oox/source/ppt` (and uses a lot of + `oox/source/drawingml` and `oox/source/*`) + * `pptx` export is in `sd/source/filter/eppt` (mostly in `pptx-*` source + files) and shared part is in `oox/source/export` -== PPTX export/import filters == +## PPTX Export / Import Filters PPTX export filter is split into 2 parts. Impress related part is in -sd/source/filter/eppt/pptx-* and the other part is in -oox/source/export/ because it contains mostly code related to -DrawingML, which is shared with writer and calc ooxml export. +`sd/source/filter/eppt/pptx-*` and the other part is in +`oox/source/export/` because it contains mostly code related to +`DrawingML`, which is shared with writer and calc ooxml export. The export filter was written in 2009 IIRC and was not much extended feature-wise lately. -FUTURE work: add custom shapes export (see below). enhance text +## Future Works +Add custom shapes export (see below). enhance text output, we don't write text style for indentation levels now, need to -export a:lvl1pPr, a:lvl2pPr, ... elements. +export `a:lvl1pPr`, `a:lvl2pPr`, ... elements. -PPTX import was written by Sun/Oracle and then extended in LibreOffice -a lot during bug fixing. It is located in oox/source/ppt and -oox/source/drawingml. The areas with most bugs (at least until today) +`PPTX` import was written by Sun/Oracle and then extended in LibreOffice +a lot during bug fixing. It is located in `oox/source/ppt` and +`oox/source/drawingml`. The areas with most bugs (at least until today) were shape placeholders and text style inheritance. diff --git a/sdext/README.md b/sdext/README.md index 63bfd6d0a793..86cb1d2af7ca 100644 --- a/sdext/README.md +++ b/sdext/README.md @@ -1,30 +1,30 @@ -Extensions for the Impress and Draw applications. +# Extensions for the Impress and Draw Applications -source/pdfimport/ - PDF import +`source/pdfimport/` - PDF import - Uses an external poppler process to parse and handle PDF - import as draw shapes. +Uses an external poppler process to parse and handle PDF +import as draw shapes. -source/minimizer/ - Presentation Minimizer +`source/minimizer/` - Presentation Minimizer - Shrinks presentations by down-scaling images, and removing - extraneous eg. embedded OLE content. +Shrinks presentations by down-scaling images, and removing +extraneous eg. embedded OLE content. -source/presenter/ - Impress / Presenter Console. +`source/presenter/` - Impress / Presenter Console. - This couples to sd/ in rather strange ways. Its design is - heavily mangled by an attempt to use only UNO interfaces - which are highly inadequate. This leads to somewhat - ridiculous situations. Activating in response to - configuration keys (for example), and the 'XPresenterHelper' - interface inside sd/ used to create and manage windows. +This couples to `sd/` in rather strange ways. Its design is +heavily mangled by an attempt to use only UNO interfaces +which are highly inadequate. This leads to somewhat +ridiculous situations. Activating in response to +configuration keys (for example), and the `XPresenterHelper` +interface inside `sd/` used to create and manage windows. - The main screen uses a hardware-accelerated - canvas (e.g. cairo canvas), while the entire secondary screen - uses a VCL-canvas that is created in - sd::framework::FullScreenPane::CreateCanvas(). +The main screen uses a hardware-accelerated +canvas (e.g. cairo canvas), while the entire secondary screen +uses a VCL-canvas that is created in +`sd::framework::FullScreenPane::CreateCanvas()`. - The secondary screen contains 3 "Panes" which each have - 2 XWindows for the border area & the actual content, - and each content Pane is backed by a sd::presenter::PresenterCanvas - that wraps the FullScreenPane's canvas and does clipping. +The secondary screen contains 3 `Pane`s which each have +2 `XWindows` for the border area & the actual content, +and each content Pane is backed by a `sd::presenter::PresenterCanvas` +that wraps the `FullScreenPane`'s canvas and does clipping. diff --git a/sfx2/README.md b/sfx2/README.md index 9726870a6019..58e97d62361d 100644 --- a/sfx2/README.md +++ b/sfx2/README.md @@ -1,28 +1,30 @@ -SFX is the "old" framework, used for historical reasons. +# Legacy Framework -An attempt of documentation of this module is located in [git:sfx2/doc]. +`SFX` is the "old" framework, used for historical reasons. + +An attempt of documentation of this module is located in `git:sfx2/doc`. It contains base classes for document model, view and controller, used -by "old" applications like sw, sc, sd (while "new" applications +by "old" applications like `sw`, `sc`, `sd` (while "new" applications are based on the "new" UNO based framework in "framework"). The SFX framework is based on dispatching slots identified by integers -(SlotIDs) to SfxShells, and there is a dedicated IDL compiler (svidl) -involved that generates C++ slot headers from SDI files in modules' sdi/ +(`SlotIDs`) to `SfxShells`, and there is a dedicated IDL compiler (`svidl`) +involved that generates C++ slot headers from SDI files in modules' `sdi/` subdirectory. Documentation about SFX dispatch, SDI etc.: -https://wiki.openoffice.org/wiki/Framework/Article/Implementation_of_the_Dispatch_API_In_SFX2 +<https://wiki.openoffice.org/wiki/Framework/Article/Implementation_of_the_Dispatch_API_In_SFX2> -Document load/save code is maintained in [git:sfx2/source/doc/docfile.cxx] -SfxMedium class, which handles all the twisty load and save corner cases. +Document load/save code is maintained in `git:sfx2/source/doc/docfile.cxx` +`SfxMedium` class, which handles all the twisty load and save corner cases. -[git:sfx2/source/appl/sfxhelp.cxx] Start procedure for the online +`git:sfx2/source/appl/sfxhelp.cxx` Start procedure for the online help viewer top level window; handling of help URL creation and dispatch. There are also some UNO services here that could really be implemented -anywhere, e.g. the DocumentProperties or DocumentMetadataAccess. +anywhere, e.g. the `DocumentProperties` or `DocumentMetadataAccess`. Notable files: -sfx2/source/dialog/backingwindow.cxx Startcenter buttons and the corresponding event handler. +`sfx2/source/dialog/backingwindow.cxx` `Startcenter` buttons and the corresponding event handler. diff --git a/shell/README.md b/shell/README.md index b8e821a66ae1..294eef9dc2e2 100644 --- a/shell/README.md +++ b/shell/README.md @@ -1 +1,2 @@ -System helpers - launching URI, system integration, external mailer support etc. +# System Helpers +Launching URI, system integration, external mailer support etc. diff --git a/slideshow/README.md b/slideshow/README.md index e67379f43c89..69fa42aebcfb 100644 --- a/slideshow/README.md +++ b/slideshow/README.md @@ -1,32 +1,33 @@ -The Impress slideshow engine +# Impress Slideshow Engine -== 3D transitions == +## 3D Transitions The 3D transitions are slideshow transition engine using OpenGL and -are located in slideshow/source/engine/OGLTrans/. They were initially +are located in `slideshow/source/engine/OGLTrans/`. They were initially written by GSOC student Shane.M.Mathews. Radek has later polished the code a bit, added few new 3D transitions, added infrastructure for vertex and fragment shaders. Wrote few transitions with fragment shader too. -== Physics Animation Effects == +## Physics Animation Effects Physics animation effects are simulated by external 2d physics engine -library Box2D. They don't directly call Box2D functions but instead +library `Box2D`. They don't directly call `Box2D` functions but instead use the wrapper in: -* slideshow/source/inc/box2dtools.hxx -* slideshow/source/engine/box2dtools.cxx -The wrapper has two corresponding classes to manage the Box2D world -and Box2D bodies. +* `slideshow/source/inc/box2dtools.hxx` +* `slideshow/source/engine/box2dtools.cxx` -When a physics animation starts, a Box2DWorld is initiated and +The wrapper has two corresponding classes to manage the `Box2D` world +and `Box2D` bodies. + +When a physics animation starts, a `Box2DWorld` is initiated and populated with every shape that is part of the foreground (which are shapes that do not belong to the master slide and not a background shape). After creation until the end of the slide (not the whole slideshow) -the Box2D World isn't destroyed and reused. But the bodies that +the `Box2D` World isn't destroyed and reused. But the bodies that represent the shapes in the slide get destroyed when there's a point in time that there's no physics animation in progress. And recreated when another physics animation starts. @@ -36,8 +37,8 @@ takes the role of stepping through the simulation. If there are other animation effects that go in parallel which change the shape position, rotation, or visibility - they also report the -change to Box2D World. These updates are collected in a queue in -Box2DWorld and processed before stepping through the simulation. +change to `Box2DWorld`. These updates are collected in a queue in +`Box2DWorld` and processed before stepping through the simulation. To achieve convincing results these updates are performed by setting -the box2d body's linear velocity or angular velocity instead of +the `Box2D` body's linear velocity or angular velocity instead of setting directly it's position or rotation. diff --git a/smoketest/README.md b/smoketest/README.md index 30dceb678ff0..5cd48ecb38f9 100644 --- a/smoketest/README.md +++ b/smoketest/README.md @@ -1,18 +1,19 @@ +# Smoke Test Smoke test for each component of LibreOffice. -* smoketest: +* `smoketest`: - The main smoketest.cxx is launched connects via binary UNO +The main `smoketest.cxx` is launched connects via binary UNO over a socket to a remote LibreOffice instance. This loads a document -which is zipped at build time into the workdir/ from the data/ +which is zipped at build time into the `workdir/` from the `data/` directory. This in turn contains a set of macros in -data/Basic/Standard. +`data/Basic/Standard`. - Smoketest.cxx does a remote the StartTestWithDefaultOptions -macro and waits for a dispatchFinished from the macro's execution. To -debug this best load workdir/Zip/smoketestdoc.sxw - and hit 'start -smoketest' - this will launch a number of components and build a +`smoketest.cxx` does a remote the `StartTestWithDefaultOptions` +macro and waits for a `dispatchFinished` from the macro's execution. To +debug this best load `workdir/Zip/smoketestdoc.sxw` - and hit `start +smoketest` - this will launch a number of components and build a suitable report in the form of a table. - The StarBasic smoketests also log their output, this ends up -in instdir/user/temp/smoketest.log. +The StarBasic smoketests also log their output, this ends up +in `instdir/user/temp/smoketest.log`. diff --git a/solenv/README.md b/solenv/README.md index b5a730746674..fd45397e2fb8 100644 --- a/solenv/README.md +++ b/solenv/README.md @@ -1,41 +1,47 @@ -Tools and makefile fragments necessary for compilation +# Tools and Makefile Fragments Necessary for Compilation This module contains many tools and makefile configuration pieces, critical for building LibreOffice: -bin/ - contains lots of tools used during the build: +- `bin/` - concat-deps* - these aggregate, and remove duplicates from module - dependencies, to accelerate build times. + - contains lots of tools used during the build: - make_installer.pl - this script executes the compiled instructions from - the scp2/ module to create an installer, and/or to - do a local install for the smoketest. + - `concat-deps*` + these aggregate, and remove duplicates from module + dependencies, to accelerate build times. + + - `make_installer.pl` + this script executes the compiled instructions from + the `scp2/` module to create an installer, and/or to + do a local install for the smoketest. + +- `gbuild/` -gbuild/ implementation of the LibreOffice build system - See gbuild/README for more info. + See `gbuild/README` for more info. + +- `gdb/` -gdb/ lots of nice python helpers to make debugging -much- easier that (eg.) print UCS2 strings as UTF-8 on the console to help with debugging. -inc/ - old / increasingly obsolete dmake setup and includes, we are +- `inc/` + + old `/` increasingly obsolete dmake setup and includes, we are trying to entirely rid ourselves of this -src/ - useful standard / re-usable component map files for components +- `src/` + + useful standard `/` re-usable component map files for components which shouldn't export anything more than a few registration symbols. -flatpak-manifest.in - This file is used by flatpak/build.sh from the LO dev-tools - repository to generate the flatpak package. download.lst is - a Makefile snippet, so there seems to be no easy way to use - download.lst for the manifest generation (build.sh uses sed), +- `flatpak-manifest.in` + + This file is used by `flatpak/build.sh` from the LO `dev-tools` + repository to generate the flatpak package. `download.lst` is + a `Makefile` snippet, so there seems to be no easy way to use + `download.lst` for the manifest generation (`build.sh` uses `sed`), and its information must be kept in sync manually. diff --git a/soltools/README.md b/soltools/README.md new file mode 100644 index 000000000000..50784b34de40 --- /dev/null +++ b/soltools/README.md @@ -0,0 +1,3 @@ +# Build Tools + +Different build tools. diff --git a/sot/README.md b/sot/README.md index 2abadba76756..692114b0f5ad 100644 --- a/sot/README.md +++ b/sot/README.md @@ -1 +1,3 @@ -Compound file storage tools code. +# Compound File Storage Tools Code + +`sot` contains compound file storage tools code. diff --git a/starmath/README.md b/starmath/README.md index d84b3d8e0483..c2a8fcaf0ade 100644 --- a/starmath/README.md +++ b/starmath/README.md @@ -1,4 +1,5 @@ -Formula editor code for writer ([[sw]]). +# Formula Editor Code for LibreOffice Writer Good overview from the original developer: -http://www.mail-archive.com/dev@sw.openoffice.org/msg00200.html + +<http://www.mail-archive.com/dev@sw.openoffice.org/msg00200.html> diff --git a/stoc/README.md b/stoc/README.md index 58f0c6f1a26a..47fd36d20fae 100644 --- a/stoc/README.md +++ b/stoc/README.md @@ -1,5 +1,4 @@ -Registries, reflection, introspection implementation for UNO. - +# Registries, Reflection, Introspection Implementation for UNO The UNO types and services bootstrapping code is very old, and concepts are tightly knit together. Whenever you want to change something you risk @@ -9,32 +8,32 @@ up doing minimally invasive changes. That way, you have a chance of surviving the process. But you also pile up guilt. At the heart of the matter there is the old binary "store" file structure -and the XRegistry interface on top of it. At runtime, both all the UNO -type information (scattered across a number of binary rdb files) and -all the UNO service information (scattered across a number of rdb files +and the `XRegistry` interface on top of it. At runtime, both all the UNO +type information (scattered across a number of binary `.rdb` files) and +all the UNO service information (scattered across a number of `.rdb` files that used to be binary but have been mostly changed to XML now) are -represented by a single XRegistry instance each. +represented by a single `XRegistry` instance each. -The way the respective information is represented in the XRegistry +The way the respective information is represented in the `XRegistry` interface simply corresponds to the way the information is stored in the -binary rdb files. Those files are designed for storage of hierarchically +binary `.rdb` files. Those files are designed for storage of hierarchically nested small blobs of information. Hence, for example information about -a UNO interface type com.sun.star.foo.XBar is stored in a nested "folder" -with path com - sun - star - foo - XBar, containing little blobs of +a UNO interface type `com.sun.star.foo.XBar` is stored in a nested "folder" +with path `com - sun - star - foo - XBar`, containing little blobs of information about the type's ancestors, its methods, etc. Similarly -for information about instantiable services like com.sun.star.baz.Boz. +for information about instantiable services like `com.sun.star.baz.Boz`. -As there are typically multiple rdb files containing types resp. +As there are typically multiple `.rdb` files containing types resp. services (URE specific, LO specific, from extensions, ...), but they need -to be represented by a single XRegistry instance, so "nested registries" -were invented. They effectively form a linear list of chaining XRegistry +to be represented by a single `XRegistry` instance, so "nested registries" +were invented. They effectively form a linear list of chaining `XRegistry` instances together. Whenever a path needs to be looked up in the top-level registry, it effectively searches through the linear list of nested -registries. All with the cumbersome UNO XRegistry interface between +registries. All with the cumbersome UNO `XRegistry` interface between the individual parts. Horror. -When the XML service rdbs were introduced, we chickened out (see above -for rationale) and put them behind an XRegistry facade, so that they -would seamlessly integrate with the existing mess. We postponed -systematic clean-up to the pie-in-the-sky days of LO 4 (or, "once we'll -become incompatible with OOo," as the phrase used to be back then) +When the XML service `.rdb`s were introduced, we chickened out (see above +for rationale) and put them behind an `XRegistry` facade, so that they +would seamlessly integrate with the existing mess. We postponed +systematic clean-up to the pie-in-the-sky days of LibreOffice 4 (or, "once we'll +become incompatible with OpenOffice.org," as the phrase used to be back then) diff --git a/store/README.md b/store/README.md index 46641014c7b9..864f48458b87 100644 --- a/store/README.md +++ b/store/README.md @@ -1,5 +1,5 @@ -The legacy .rdb format. +# The Legacy .rdb Format -Originally used for services and types .rdb files, before the former were +Originally used for services and types `.rdb` files, before the former were replaced with XML files and the latter with the new unoidl format, but still needed for backwards compatibility. diff --git a/svgio/README.md b/svgio/README.md index 722f6c0769b6..76505a6725f2 100644 --- a/svgio/README.md +++ b/svgio/README.md @@ -1 +1,3 @@ -It contains svgio/source/svgreader which is used for "Insert->Picture->From File". +# SVG Reader + +It contains `svgio/source/svgreader` which is used for "Insert -> Picture -> From File". diff --git a/svl/README.md b/svl/README.md index ce257747987b..984d6ecfe2f9 100644 --- a/svl/README.md +++ b/svl/README.md @@ -1,50 +1,51 @@ +# Non-Graphical Helper Code (svtools light) + Contains non-graphical helper code for office applications. Specifically this module does not depend on or use includes from module vcl. Originally all code in svtools that did not depend on vcl was split off into this svl ("svtools light") module. -In particular the SfxItemSet is a property-bag like container that +In particular the `SfxItemSet` is a property-bag like container that stores arbitrary sets of properties for everything from text run formats, to Chart regression line properties. There are lots of other useful helpers in here for various office -tasks; much of this code was originally moved from svx/sfx2. +tasks; much of this code was originally moved from `svx/sfx2`. -== Items, Pools and Sets == +## Items, Pools and Sets -=== SfxPoolItem === +### SfxPoolItem A small reference counted piece of data. Many subclasses, each with a -unique integer to identify its type (WhichId). Can be compared for equality -(operator==), Clone()d, and converted to/from uno::Any (QueryValue/PutValue). +unique integer to identify its type (`WhichId`). Can be compared for equality +(`operator==`), `Clone()`d, and converted to/from `uno::Any` (`QueryValue/PutValue`). A pool item may have value semantics ("poolable"), meaning that there will generally be only one instance that compares equal per item pool, -or not, in which case the item will be Clone()d quite a bit. +or not, in which case the item will be `Clone()`d quite a bit. -=== SfxItemPool === +### SfxItemPool -Usually there is one item pool per document, with a range of valid WhichIds +Usually there is one item pool per document, with a range of valid `WhichId`s that is specific to the type of document. -The item pool owns all instances of SfxPoolItem or its subclasses that have +The item pool owns all instances of `SfxPoolItem` or its subclasses that have ever been added to an item set. It also contains a default item for every WhichId, which will be (depending on parameters) returned from item -sets if the set does not contain an item at this WhichId. +sets if the set does not contain an item at this `WhichId`. -=== SfxItemSet === +### SfxItemSet -The item set can be created with a user-supplied range of WhichIds; it -will accept SfxPoolItems with matching WhichIds and ignore attempts to -insert items with non-matching WhichIds. +The item set can be created with a user-supplied range of `WhichId`s; it +will accept `SfxPoolItems` with matching `WhichId`s and ignore attempts to +insert items with non-matching `WhichId`s. Items that are successfully inserted into the set will be stored in the -set's SfxItemPool, and for poolable items only a single instance that -compares equal under the predicate operator== will be stored in the pool, +set's `SfxItemPool`, and for poolable items only a single instance that +compares equal under the predicate `operator==` will be stored in the pool, regardless of how many sets contain it, thus conserving memory. -There are members m_pWhichRanges for the valid ranges (as pairs of WhichIds), -m_nCount for the number of items contained, and m_pItems for the pointers to +There are members `m_pWhichRanges` for the valid ranges (as pairs of `WhichId`s), +`m_nCount` for the number of items contained, and `m_pItems` for the pointers to the actual items. - diff --git a/svtools/README.md b/svtools/README.md index dc35c3f38702..b1c2b81b8580 100644 --- a/svtools/README.md +++ b/svtools/README.md @@ -1 +1,3 @@ -Tools on top of VCL. Common dialogs, file and print dialogs, wizards, vcl filters, lots of helper code. +# Tools on the Top of VCL + +Common dialogs, file and print dialogs, wizards, vcl filters, lots of helper code. diff --git a/svx/README.md b/svx/README.md index 30e946547695..adf52ccacd1f 100644 --- a/svx/README.md +++ b/svx/README.md @@ -1,101 +1,105 @@ +# Graphics Related Helper Code + Contains graphics related helper code. Lots of the draw and impress code is in this shared library. -xoutdev -this is where a lot of wht work would happen to move to the canvas. (what does that mean?) +- `xoutdev` + + this is where a lot of wht work would happen to move to the canvas. (what does that mean?) + +- `svdraw` -svdraw -transparent gradient stuff. [seriously? surely much more, too] + transparent gradient stuff. [seriously? surely much more, too] -== SdrObject == +## SdrObject The shapes you can see in LibreOffice (like rectangle, etc.) are SdrObjects. They are declared as a hierarchy: -SdrObject <- SdrAttrObj <- E3dObject <- E3dCompoundObject <- E3dCubeObj - ^ ^ ^ ^ ^ | | ^ ^ - | | | | | | | | +--- E3dExtrudeObj - | | | | | | | +----- E3dLatheObj - | | | | | | +------- E3dPolygonObj - | | | | | +--------- E3dSphereObj - | | | | +--- E3dScene... - | | | | - | | | +--- SdrTextObj <- SdrObjCustomShape... - | | | ^ ^ ^ ^ ^ - | | | | | | | +--- SdrEdgeObj... - | | | | | | +----- SdrMeasureObj... - | | | | | +------- SdrPathObj... - | | | | +--------- SdrRectObj... - | | | +----------- SdrTableObj... - | | +--- SdrObjGroup... - | + ---- SdrPageObj... - +------- SdrVirtObj... + SdrObject <- SdrAttrObj <- E3dObject <- E3dCompoundObject <- E3dCubeObj + ^ ^ ^ ^ ^ | | ^ ^ + | | | | | | | | +--- E3dExtrudeObj + | | | | | | | +----- E3dLatheObj + | | | | | | +------- E3dPolygonObj + | | | | | +--------- E3dSphereObj + | | | | +--- E3dScene... + | | | | + | | | +--- SdrTextObj <- SdrObjCustomShape... + | | | ^ ^ ^ ^ ^ + | | | | | | | +--- SdrEdgeObj... + | | | | | | +----- SdrMeasureObj... + | | | | | +------- SdrPathObj... + | | | | +--------- SdrRectObj... + | | | +----------- SdrTableObj... + | | +--- SdrObjGroup... + | + ---- SdrPageObj... + +------- SdrVirtObj... The above is incomplete of course. -== SdrModel / SdrView == +## SdrModel / SdrView -Copied from svdview.hxx: +Copied from `svdview.hxx`: - First of all the app creates a SdrModel. - Then it opens a Win and creates a SdrView. - ShowSdrPage() announces a page at SdrView. - It's possible to show SdrView in any Wins at once. + First of all the app creates a `SdrModel`. + Then it opens a Win and creates a `SdrView`. + `ShowSdrPage()` announces a page at `SdrView`. + It's possible to show `SdrView` in any Wins at once. - SdrView can show as many Wins as it wants at once. Pages are announced - or checked out with the help of ShowSdrPage()/HideSdrPage(). For every announced - page there is a SdrPageView instance in container aPages. If more than one page - is showed, you have to pay attention that the offset parameter of ShowSdrPage() + `SdrView` can show as many Wins as it wants at once. Pages are announced + or checked out with the help of `ShowSdrPage()`/`HideSdrPage()`. For every announced + page there is a `SdrPageView` instance in container aPages. If more than one page + is showed, you have to pay attention that the offset parameter of `ShowSdrPage()` is conformed to the size of the page (to prevent overlapping of two pages). -SdrView itself is inherited from many objects in a chain of inheritance (all -that starts with SdrPaintView - that is itself inherited from few classes +`SdrView` itself is inherited from many objects in a chain of inheritance (all +that starts with `SdrPaintView` - that is itself inherited from few classes too): -SdrPaintView <- SdrSnapView <- SdrMarkView <- SdrEditView <- SdrPolyEditView - ^ - +----------------------------------------------------------------+ - | - SdrGlueEditView <- SdrObjEditView <- SdrExchangeView <- SdrDragView - ^ - +----------------------------------------------------------------+ - | - SdrCreateView <- SdrView + SdrPaintView <- SdrSnapView <- SdrMarkView <- SdrEditView <- SdrPolyEditView + ^ + +----------------------------------------------------------------+ + | + SdrGlueEditView <- SdrObjEditView <- SdrExchangeView <- SdrDragView + ^ + +----------------------------------------------------------------+ + | + SdrCreateView <- SdrView -From SdrView on, it is not flat, but a real hierarchy again. +From `SdrView` on, it is not flat, but a real hierarchy again. -== Drawing Layer / SdrObject(s) == +## Drawing Layer / SdrObject(s) -See drawinglayer/README for general information about drawinglayer. +See `drawinglayer/README.md` for general information about drawinglayer. Below is the class diagram that comes from -http://www.openoffice.org/marketing/ooocon2006/presentations/wednesday_g11.odp, +<http://www.openoffice.org/marketing/ooocon2006/presentations/wednesday_g11.odp>, slide number 6. -.------- Model --------------. .------- View -----------------------------------------. -| SdrObject - ViewContact | 1..* | ViewObjectContact | -| getChild() |------| getPrimitiveList() -----> Object(s) ---> SdrView | -| getVOC() | | getRecPrimitiveList() Contact | -| getViewInd... | |________|_____________________________________________| -| ...ependentPrimitiveList() | | -|____________________________| generates - | ______ - V / | - .----------------------. | - | basePrimitive | | - | getRange() |<---' - | getDecomposition() | - |______________________| - -For SdrObjects, there are own DrawingLayer primitives in -svx/source/sdr/primitive2d - -The ViewContact / ViewObject / ViewObjectContact are in svx/source/sdr/contact -Decomposes the SdrObjects, and does all sort of operations on them. - -If the number of visualizable objects (e.g. SdrObjects) is X, and the number of -SdrViews is Y, then: - -- there are X ViewContact instances (1:1 relation with a visualizable object) -- there are Y ObjectContact instances (1:1 relation with an SdrView) -- there are X*Y ViewObjecContact instances (1:N relation to both - visualizable objects and SdrViews) + .------- Model --------------. .------- View -----------------------------------------. + | SdrObject - ViewContact | 1..* | ViewObjectContact | + | getChild() |------| getPrimitiveList() -----> Object(s) ---> SdrView | + | getVOC() | | getRecPrimitiveList() Contact | + | getViewInd... | |________|_____________________________________________| + | ...ependentPrimitiveList() | | + |____________________________| generates + | ______ + V / | + .----------------------. | + | basePrimitive | | + | getRange() |<---' + | getDecomposition() | + |______________________| + +For `SdrObjects`, there are own `DrawingLayer` primitives in +`svx/source/sdr/primitive2d` + +The `ViewContact` / `ViewObject` / `ViewObjectContact` are in `svx/source/sdr/contact` +Decomposes the `SdrObjects`, and does all sort of operations on them. + +If the number of visualizable objects (e.g. `SdrObjects`) is `X`, and the number of +`SdrViews` is `Y`, then: + +- there are `X` `ViewContact` instances (1:1 relation with a visualizable object) +- there are `Y` `ObjectContact` instances (1:1 relation with an `SdrView`) +- there are `X*Y` `ViewObjecContact` instances (1:N relation to both + visualizable objects and `SdrView`s) diff --git a/sw/README.md b/sw/README.md index 54feb78fa7d1..f4c6e44e1c28 100644 --- a/sw/README.md +++ b/sw/README.md @@ -1,10 +1,10 @@ -Writer application code. +# Writer Application Code Exact history was lost before Sept. 18th, 2000, but old source code comments show that Writer core dates back until at least November 1990. -== Module contents == +## Module Contents * inc: headers available to all source files inside the module * qa: unit, slow and subsequent tests * sdi @@ -12,7 +12,7 @@ comments show that Writer core dates back until at least November * uiconfig: user interface configuration * util: UNO passive registration config -== Source contents == +## Source Contents * core: Writer core (document model, layout, UNO API implementation) * filter: Writer internal filters * ascii: plain text filter @@ -27,19 +27,19 @@ comments show that Writer core dates back until at least November * uibase: user interface (those parts that are linked into sw & always loaded) * ui: user interface (optional parts that are loaded on demand (swui)) -== Core == +## Core There is a good overview documentation of basic architecture of Writer core in the OOo wiki: -http://wiki.openoffice.org/wiki/Writer/Core_And_Layout -http://wiki.openoffice.org/wiki/Writer/Text_Formatting +- http://wiki.openoffice.org/wiki/Writer/Core_And_Layout +- http://wiki.openoffice.org/wiki/Writer/Text_Formatting Writer specific WhichIds are defined in sw/inc/hintids.hxx. The details below are mainly about details missing from the Wiki pages. -=== SwDoc === +### SwDoc The central class for a document is SwDoc, which represents a document. @@ -50,7 +50,7 @@ SwDoc::getIDocument*() methods to retrieve the managers. However there are still too many members and methods in this class, many of which could be moved to some Manager or other... -=== SwNodes === +### SwNodes Basically a (fancy) array of SwNode pointers. There are special subclasses of SwNode (SwStartNode and SwEndNode) which are used to encode a nested tree @@ -67,7 +67,7 @@ The SwNodes contains the following top-level sections: 4. Deleted Change Tracking content 5. Body content -=== Undo === +### Undo The Undo/Redo information is stored in a sw::UndoManager member of SwDoc, which implements the IDocumentUndoRedo interface. @@ -79,7 +79,7 @@ Undo/Redo step. There are also ListActions which internally contain several individual SwUndo actions; these are created by the StartUndo/EndUndo wrapper methods. -=== Text Attributes === +### Text Attributes The sub-structure of paragraphs is stored in the SwpHintsArray member SwTextNode::m_pSwpHints. There is a base class SwTextAttr with numerous @@ -106,7 +106,7 @@ There are several sub-categories of SwTextAttr: These all have a corresponding dummy character in the paragraph text, which is a placeholder for the "expansion" of the attribute, e.g. field content. -=== Fields === +### Fields There are multiple model classes involved for fields: @@ -140,7 +140,7 @@ There are multiple model classes involved for fields: Its life-cycle is determined by UNO clients outside of sw; it will get disposed when the SwFormatField dies. -=== Lists === +### Lists - SwNumFormat (subclass of SvxNumFormat) determines the formatting of a single numbering level. @@ -197,9 +197,9 @@ There are multiple model classes involved for fields: Note that there is no UNO service to represent a list. -=== Layout === +### Layout -The layout is a tree of SwFrame subclasses, the following relationships are +The layout is a tree of `SwFrame` subclasses, the following relationships are possible between frames: - You can visit the tree by following the upper, lower, next and previous pointers. diff --git a/swext/README.md b/swext/README.md index 71eaa268cddf..6ddc53d11ee8 100644 --- a/swext/README.md +++ b/swext/README.md @@ -1 +1,3 @@ -Writer extensions (currently only MediaWiki Extension). +# Writer Extensions + +Currently only contains MediaWiki extension. diff --git a/sysui/README.md b/sysui/README.md index beedede865db..951b89fdd1b8 100644 --- a/sysui/README.md +++ b/sysui/README.md @@ -1 +1,3 @@ -.desktop files for various Linux distros, and similar stuff for other OSes +# Desktop System Integration + +`.desktop` files for various Linux distros, and similar stuff for other operating systems. diff --git a/test/README.md b/test/README.md index dc0afd80a8d9..0845e3f7354a 100644 --- a/test/README.md +++ b/test/README.md @@ -1,4 +1,4 @@ -Test harness code for C++ unit testing +# Test Harness Code for C++ Unit Testing Many of these tests are run during the build process. In that case on -unix, if a test fails follow the error messages to debug it under gdb. +unix, if a test fails follow the error messages to debug it under `gdb`. diff --git a/testtools/README.md b/testtools/README.md index c71e4c8b607d..f238c512293f 100644 --- a/testtools/README.md +++ b/testtools/README.md @@ -1,34 +1,35 @@ -Testing tools +# Testing Tools -== How to check compatibility between compilers == +## How to Check Compatibility Between Compilers Since the interfaces used in the cpp bridgetest are not changed often -one can just build the cppobj.uno.dll and the constructors.uno.dll -(testtools/source/bridgetest) in an +one can just build the `cppobj.uno.dll` and the `constructors.uno.dll` +(`testtools/source/bridgetest`) in an old environment and then use them in the new environment. That is the files -are copied into the testtools/wntmsciXX.pro folder which corresponds to the +are copied into the `testtools/wntmsciXX.pro` folder which corresponds to the new environment. On Windows this test will typically fail because the tests use the -cppu::getCaughtException function, which only works when all libs are build +`cppu::getCaughtException` function, which only works when all libs are build using the same runtime. This part of the test can switched off. To do this go into the -testtools/source/bridgetest folder and call -dmake compcheck=1 +`testtools/source/bridgetest` folder and call -This will add a new compiler define (-DCOMPCHECK) and will be used in the -bridgetest.cxx to switch off the code which uses the getCaughtException function. + dmake compcheck=1 + +This will add a new compiler define (`-DCOMPCHECK`) and will be used in the +`bridgetest.cxx` to switch off the code which uses the `getCaughtException` function. However, there is still a test which causes the test component to throw -and IllegalArgumentException. This still works. +and `IllegalArgumentException`. This still works. -== Using source/bridgetest for stress testing == +## Using source / bridgetest for Stress Testing -Start a modified bridgetest_server (with the final "--singleaccept" argument -removed from the uno executable call) or a modified bridgetest_javaserver (with -the final "singleaccept" argument replaced with "multi" in the java executable -call), then start a modified bridgetest_client (with a final "stress" argument +Start a modified `bridgetest_server` (with the final `--singleaccept` argument +removed from the uno executable call) or a modified `bridgetest_javaserver` (with +the final `singleaccept` argument replaced with `multi` in the java executable +call), then start a modified `bridgetest_client` (with a final `stress` argument added to the uno executable call). The client will continuously establish connections to the server which are immediately destroyed again. The test will run forever, unless an error occurs. diff --git a/toolkit/README.md b/toolkit/README.md index b67f037b08cc..f41fb3760cbd 100644 --- a/toolkit/README.md +++ b/toolkit/README.md @@ -1,11 +1,15 @@ +# Abstract Windowing Toolkit + "Abstract" windowing thing. UNO implementations of windowing stuff so that it can be used from Basic or Java. But also stuff that has no connection to Basic or Java. -Note that the "awt" here has no relation to the Java awt, as far as I know. It +## Notes + +The "awt" here has no relation to the Java AWT, as far as I know. It might be inspired by it API-wise, perhaps. (If you know differently, feel free -to improve this README file.) +to improve this `README.md` file.) -Note that toolkit/ is itself not really a toolkit, it is at root a -reasonably simple wrapper of vcl/. If you came here looking for a -toolkit, please look at vcl/ instead. +Also note that `toolkit/` is itself not really a toolkit, it is at root a +reasonably simple wrapper of `vcl/`. If you came here looking for a +toolkit, please look at `vcl/` instead. diff --git a/tools/README.md b/tools/README.md index 4b98a7342af5..5bb9f46d678e 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,3 +1,5 @@ +# Old Tools (Deprecated) + Predates sal - string functions, url manipulation, stream stuff, polygons, etc. @@ -5,5 +7,5 @@ Exact history is lost before Sept. 18th, 2000, but old source code comments show that part of the tools library dates back until at least April 1991. -This directory will be removed in the near future (see fdo#39445 or -fdo#63154). +This directory will be removed in the near future (see tdf#39445 or +tdf#63154). diff --git a/ucb/README.md b/ucb/README.md index c6b153130e9c..5af5487d7c5d 100644 --- a/ucb/README.md +++ b/ucb/README.md @@ -1,6 +1,8 @@ +# Universal Content Broker (UCB) + Universal Content Broker (has ucp) which do things like convert files to strings in content broker world. -mmeeks: so - I renamed the old LGPLv3 webdav code to webdav-neon, and imported +mmeeks: so - I renamed the old LGPLv3 webdav code to `webdav-neon`, and imported the (not built) serf webdav ucp into the old space. so that in future, we can merge changes more easily - and still choose which to use. cbosdonnat kindly volunteered to do some comparative analysis of the two codebases to decide which diff --git a/ucbhelper/README.md b/ucbhelper/README.md index ff3d49b0b8f6..86ecaf8662b4 100644 --- a/ucbhelper/README.md +++ b/ucbhelper/README.md @@ -1 +1,3 @@ +# C++ Wrappers for UCB + C++ wrappers to help make using content providers easy. diff --git a/udkapi/README.md b/udkapi/README.md index 9fb99e8ae013..64a9fd63f48e 100644 --- a/udkapi/README.md +++ b/udkapi/README.md @@ -1,9 +1,10 @@ -Low level UNO stuff API IDL files +# APIs for UNO Core -i.e. those that are part of the standalone URE. +Low level UNO stuff API IDL files, i.e. those that are part of the standalone URE. -During the build the resulting .rdb file is known as udkapi.rdb. In the -installation set, it is known as types.rdb (in the URE's sub-tree). +During the build the resulting `.rdb` file is known as `udkapi.rdb`. In the +installation set, it is known as `types.rdb` (in the URE's sub-tree). -See also: -[[offapi]] +## See also + +- `offapi` diff --git a/uitest/README.md b/uitest/README.md index c941673e7927..8c872bed6f27 100644 --- a/uitest/README.md +++ b/uitest/README.md @@ -1 +1,3 @@ +# UI Testing Framework + The code for the UI testing framework and the UI tests. diff --git a/unodevtools/README.md b/unodevtools/README.md index f53328e9a0a3..16692e371e55 100644 --- a/unodevtools/README.md +++ b/unodevtools/README.md @@ -1,6 +1,6 @@ -Helper tools for external UNO component developers +# Helper Tools for External UNO Component Developers This module contains some tools for people writing UNO components. In particular it will auto-generate skeletons for implementing UNO interfaces - that declare all the relevant methods leaving the code to -be filled in. This can be done for C++ or Java.
\ No newline at end of file +be filled in. This can be done for C++ or Java. diff --git a/unoidl/README.md b/unoidl/README.md index 9a2f9d263382..792038429d18 100644 --- a/unoidl/README.md +++ b/unoidl/README.md @@ -1,39 +1,39 @@ -Support for UNOIDL registry formats +# Support for UNOIDL Registry Formats -Library_unoidl contains the unoidl::Manager and unoidl::Provider implementations +`Library_unoidl` contains the `unoidl::Manager` and `unoidl::Provider` implementations for the following registry formats: -* The new UNOIDL binary types.rdb format. -* The old legacy binary types.rdb format (based on modules [[store]] and - [[registry]]). -* A source-file format, reading (multiple) UNOIDL entity definitions directly - from a single .idl source file. -* A source-tree format, reading UNOIDL entity definitions directly from a tree - of .idl source files rooted at a given directory. (Where an entity named - foo.bar.Baz is expected in a file named foo/bar/Baz.idl within that tree.) - -(While .idl files still contain #include directives for legacy idlc, the source- -based formats ignore any preprocessing directives starting with "#" in the .idl -files.) unoidl::Manager::addProvider transparently detects the registry format +* The new `UNOIDL` binary `types.rdb` format. +* The old legacy binary `types.rdb` format (based on modules "store" and + "registry"). +* A source-file format, reading (multiple) `UNOIDL` entity definitions directly + from a single `.idl` source file. +* A source-tree format, reading `UNOIDL` entity definitions directly from a tree + of `.idl` source files rooted at a given directory. (Where an entity named + `foo.bar.Baz` is expected in a file named `foo/bar/Baz.idl` within that tree.) + +(While `.idl` files still contain `#include` directives for legacy idlc, the source- +based formats ignore any preprocessing directives starting with `#` in the `.idl` +files.) `unoidl::Manager::addProvider` transparently detects the registry format for a given URI and instantiates the corresponding provider implementation. -Executable_unoidl-write is a helper tool to convert from any of the registry -formats to the UNOIDL format. It is used at build-time to compile UNOIDL format -.rdb files (that are used at build-time only, or included in installation sets -in URE or program/types/ or as part of bundled extensions that are created -during the build and not merely included as pre-built .oxt files) from source -.idl files. (The SDK still uses idlc and generates legacy format .rdb files for +`Executable_unoidl-write` is a helper tool to convert from any of the registry +formats to the `UNOIDL` format. It is used at build-time to compile `UNOIDL` format +`.rdb` files (that are used at build-time only, or included in installation sets +in `URE` or `program/types/` or as part of bundled extensions that are created +during the build and not merely included as pre-built `.oxt` files) from source +`.idl` files. (The SDK still uses idlc and generates legacy format `.rdb` files for now.) -Executable_unoidl-read is a helper tool to convert from any of the registry +`Executable_unoidl-read` is a helper tool to convert from any of the registry formats to the source-file format. It can be used manually after a LibreOffice -version update to create new reference registries for Executable_unoidl-check. +version update to create new reference registries for `Executable_unoidl-check`. -Executable_unoidl-check is a helper tool to check that one registry is +`Executable_unoidl-check` is a helper tool to check that one registry is backwards-compatible with another registry. It is used at build-time to detect inadvertent breakage of the udkapi and offapi APIs. -== Specification of the new UNOIDL types.rdb format == +## Specification of the New UNOIDL types.rdb Format The format uses byte-oriented, platform-independent, binary files. Larger quantities are stored LSB first, without alignment requirements. Offsets are @@ -46,238 +46,238 @@ entities (e.g., both for an interface type definition and for a direct method of an interface type definition; the idea is that it can be added for direct parts that forma a "many-to-one" relationship; there is a tradeoff between generality of concept and size of representation, esp. for the C++ representation types in -namespace unoidl) and consist of arbitrary sequences of name/value strings. +namespace `unoidl`) and consist of arbitrary sequences of name/value strings. Each name/value string is encoded as a single UTF-8 string containing a name (an -arbitrary sequence of Unicode code points not containing U+003D EQUALS SIGN), -optionally followed by U+003D EQUALS SIGN and a value (an arbitrary sequence of +arbitrary sequence of Unicode code points not containing `U+003D EQUALS SIGN`), +optionally followed by `U+003D EQUALS SIGN` and a value (an arbitrary sequence of Unicode code points). The only annotation name currently in use is "deprecated" (without a value). The following definitions are used throughout: -* UInt16: 2-byte value, LSB first -* UInt32: 4-byte value, LSB first -* UInt64: 8-byte value, LSB first -* Offset: UInt32 value, counting bytes from start of file -* NUL-Name: zero or more non-NUL US-ASCII bytes followed by a NUL byte -* Len-String: UInt32 number of characters, with 0x80000000 bit 0, followed by - that many US-ASCII (for UNOIDL related names) resp. UTF-8 (for annotations) +* `UInt16`: 2-byte value, LSB first +* `UInt32`: 4-byte value, LSB first +* `UInt64`: 8-byte value, LSB first +* Offset: `UInt32` value, counting bytes from start of file +* `NUL`-Name: zero or more non-`NUL` US-ASCII bytes followed by a `NUL` byte +* Len-String: UInt32 number of characters, with `0x80000000` bit 0, followed by + that many US-ASCII (for `UNOIDL` related names) resp. UTF-8 (for annotations) bytes -* Idx-String: either an Offset (with 0x80000000 bit 1) of a Len-String, or a +* Idx-String: either an Offset (with `0x80000000` bit 1) of a Len-String, or a Len-String -* Annotations: UInt32 number N of annotations followed by N * Idx-String -* Entry: Offset of NUL-Name followed by Offset of payload +* Annotations: `UInt32` number `N` of annotations followed by `N * Idx-String` +* Entry: Offset of `NUL`-Name followed by Offset of payload * Map: zero or more Entries The file starts with an 8 byte header, followed by information about the root -map (unoidl-write generates files in a single depth-first pass, so the root map +map (`unoidl-write` generates files in a single depth-first pass, so the root map itself is at the end of the file): -* 7 byte magic header "UNOIDL\xFF" +* 7 byte magic header `UNOIDL\xFF` * version byte 0 * Offset of root Map -* UInt32 number of entries of root Map +* `UInt32` number of entries of root Map ... Files generated by unoidl-write follow that by a - "\0** Created by LibreOffice " LIBO_VERSION_DOTTED " unoidl-write **\0" + "\0** Created by LibreOffice " LIBO_VERSION_DOTTED " unoidl-write **\0" -banner (cf. config_host/config_version.h.in), as a debugging aid. (Old versions -used "reg2unoidl" instead of "unoidl-write" in that banner.) +banner (cf. `config_host/config_version.h.in`), as a debugging aid. (Old versions +used `reg2unoidl` instead of `unoidl-write` in that banner.) Layout of per-entry payload in the root or a module Map: * kind byte: -** 0: module -*** followed by: -**** UInt32 number N1 of entries of Map -**** N1 * Entry - -** otherwise: -*** 0x80 bit: 1 if published -*** 0x40 bit: 1 if annotated -*** 0x20 bit: flag (may only be 1 for certain kinds, see below) -*** remaining bits: - -**** 1: enum type -***** followed by: -****** UInt32 number N1 of members -****** N1 * tuple of: -******* Idx-String -******* UInt32 -******* if annotated: Annotations - -**** 2: plain struct type (with base if flag is 1) -***** followed by: -****** if "with base": Idx-String -****** UInt32 number N1 of direct members -****** N1 * tuple of: -******* Idx-String name -******* Idx-String type -******* if annotated: Annotations - -**** 3: polymorphic struct type template -***** followed by: -****** UInt32 number N1 of type parameters -****** N1 * Idx-String -****** UInt32 number N2 of members -****** N2 * tuple of: -******* kind byte: 0x01 bit is 1 if parameterized type -******* Idx-String name -******* Idx-String type -******* if annotated: Annotations - -**** 4: exception type (with base if flag is 1) -***** followed by: -****** if "with base": Idx-String -****** UInt32 number N1 of direct members -****** N1 * tuple of: -******* Idx-String name -******* Idx-String type -******* if annotated: Annotations - -**** 5: interface type -***** followed by: -****** UInt32 number N1 of direct mandatory bases -****** N1 * tuple of: -******* Idx-String -******* if annotated: Annotations -****** UInt32 number N2 of direct optional bases -****** N2 * tuple of: -******* Idx-String -******* if annotated: Annotations -****** UInt32 number N3 of direct attributes -****** N3 * tuple of: -******* kind byte: -******** 0x02 bit: 1 if read-only -******** 0x01 bit: 1 if bound -******* Idx-String name -******* Idx-String type -******* UInt32 number N4 of get exceptions -******* N4 * Idx-String -******* UInt32 number N5 of set exceptions -******* N5 * Idx-String -******* if annotated: Annotations -****** UInt32 number N6 of direct methods -****** N6 * tuple of: -******* Idx-String name -******* Idx-String return type -******* UInt32 number N7 of parameters -******* N7 * tuple of: -******** direction byte: 0 for in, 1 for out, 2 for in-out -******** Idx-String name -******** Idx-String type -******* UInt32 number N8 of exceptions -******* N8 * Idx-String -******* if annotated: Annotations - -**** 6: typedef -***** followed by: -****** Idx-String - -**** 7: constant group -***** followed by: -****** UInt32 number N1 of entries of Map -****** N1 * Entry - -**** 8: single-interface--based service (with default constructor if flag is 1) -***** followed by: -****** Idx-String -****** if not "with default constructor": -******* UInt32 number N1 of constructors -******* N1 * tuple of: -******** Idx-String -******** UInt32 number N2 of parameters -******** N2 * tuple of -********* kind byte: 0x04 bit is 1 if rest parameter -********* Idx-String name -********* Idx-String type -******** UInt32 number N3 of exceptions -******** N3 * Idx-String -******** if annotated: Annotations - -**** 9: accumulation-based service -***** followed by: -****** UInt32 number N1 of direct mandatory base services -****** N1 * tuple of: -******* Idx-String -******* if annotated: Annotations -****** UInt32 number N2 of direct optional base services -****** N2 * tuple of: -******* Idx-String -******* if annotated: Annotations -****** UInt32 number N3 of direct mandatory base interfaces -****** N3 * tuple of: -******* Idx-String -******* if annotated: Annotations -****** UInt32 number N4 of direct optional base interfaces -****** N4 * tuple of: -******* Idx-String -******* if annotated: Annotations -****** UInt32 number N5 of direct properties -****** N5 * tuple of: -******* UInt16 kind: -******** 0x0100 bit: 1 if optional -******** 0x0080 bit: 1 if removable -******** 0x0040 bit: 1 if maybedefault -******** 0x0020 bit: 1 if maybeambiguous -******** 0x0010 bit: 1 if readonly -******** 0x0008 bit: 1 if transient -******** 0x0004 bit: 1 if constrained -******** 0x0002 bit: 1 if bound -******** 0x0001 bit: 1 if maybevoid -******* Idx-String name -******* Idx-String type -******* if annotated: Annotations - -**** 10: interface-based singleton -***** followed by: -****** Idx-String - -**** 11: service-based singleton -***** followed by: -****** Idx-String - -*** if annotated, followed by: Annotations + * 0: module + * followed by: + * `UInt32` number `N1` of entries of Map + * `N1 * Entry` + + * otherwise: + * `0x80` bit: 1 if published + * `0x40` bit: 1 if annotated + * `0x20` bit: flag (may only be 1 for certain kinds, see below) + * remaining bits: + + * 1: enum type + * followed by: + * `UInt32` number N1 of members + * `N1 * tuple` of: + * `Idx-String` + * `UInt32` + * if annotated: Annotations + + * 2: plain struct type (with base if flag is 1) + * followed by: + * if "with base": `Idx-String` + * `UInt32` number `N1` of direct members + * `N1 * tuple` of: + * `Idx-String` name + * `Idx-String` type + * if annotated: Annotations + + * 3: polymorphic struct type template + * followed by: + * `UInt32` number `N1` of type parameters + * `N1 * Idx-String` + * `UInt32` number `N2` of members + * `N2 * tuple` of: + * kind byte: `0x01` bit is 1 if parameterized type + * `Idx-String` name + * `Idx-String` type + * if annotated: Annotations + + * 4: exception type (with base if flag is 1) + * followed by: + * if "with base": `Idx-String` + * `UInt32` number `N1` of direct members + * `N1 * tuple` of: + * `Idx-String` name + * `Idx-String` type + * if annotated: Annotations + + * 5: interface type + * followed by: + * `UInt32` number `N1` of direct mandatory bases + * `N1 * tuple` of: + * `Idx-String` + * if annotated: Annotations + * `UInt32` number `N2` of direct optional bases + * `N2 * tuple` of: + * `Idx-String` + * if annotated: Annotations + * `UInt32` number `N3` of direct attributes + * `N3 * tuple` of: + * kind byte: + * `0x02` bit: 1 if read-only + * `0x01` bit: 1 if bound + * `Idx-String` name + * `Idx-String` type + * `UInt32` number `N4` of get exceptions + * `N4 * Idx-String` + * `UInt32` number `N5` of set exceptions + * `N5 * Idx-String` + * if annotated: Annotations + * `UInt32` number `N6` of direct methods + * `N6 * tuple` of: + * `Idx-String` name + * `Idx-String` return type + * `UInt32` number `N7` of parameters + * `N7 * tuple` of: + * direction byte: 0 for in, 1 for out, 2 for in-out + * `Idx-String` name + * `Idx-String` type + * `UInt32` number `N8` of exceptions + * N8 * Idx-String + * if annotated: Annotations + + * 6: typedef + * followed by: + * `Idx-String` + + * 7: constant group + * followed by: + * `UInt32` number `N1` of entries of Map + * `N1 * Entry` + + * 8: single-interface--based service (with default constructor if flag is 1) + * followed by: + * `Idx-String` + * if not "with default constructor": + * `UInt32` number `N1` of constructors + * `N1 * tuple` of: + * `Idx-String` + * `UInt32` number `N2` of parameters + * `N2 * tuple` of + * kind byte: `0x04` bit is 1 if rest parameter + * `Idx-String` name + * `Idx-String` type + * `UInt32` number `N3` of exceptions + * `N3 * Idx-String` + * if annotated: Annotations + + * 9: accumulation-based service + * followed by: + * `UInt32` number `N1` of direct mandatory base services + * `N1 * tuple` of: + * `Idx-String` + * if annotated: Annotations + * `UInt32` number `N2` of direct optional base services + * `N2 * tuple` of: + * `Idx-String` + * if annotated: Annotations + * `UInt32` number `N3` of direct mandatory base interfaces + * `N3 * tuple` of: + * `Idx-String` + * if annotated: Annotations + * `UInt32` number `N4` of direct optional base interfaces + * `N4 * tuple` of: + * `Idx-String` + * if annotated: Annotations + * `UInt32` number `N5` of direct properties + * `N5 * tuple` of: + * `UInt16` kind: + * `0x0100` bit: 1 if optional + * `0x0080` bit: 1 if removable + * `0x0040` bit: 1 if maybedefault + * `0x0020` bit: 1 if maybeambiguous + * `0x0010` bit: 1 if readonly + * `0x0008` bit: 1 if transient + * `0x0004` bit: 1 if constrained + * `0x0002` bit: 1 if bound + * `0x0001` bit: 1 if maybevoid + * `Idx-String` name + * `Idx-String` type + * if annotated: Annotations + + * 10: interface-based singleton + * followed by: + * `Idx-String` + + * 11: service-based singleton + * followed by: + * `Idx-String` + + * if annotated, followed by: Annotations Layout of per-entry payload in a constant group Map: * kind byte: -** 0x80 bit: 1 if annotated -** remaining bits: + * `0x80` bit: 1 if annotated + * remaining bits: -*** 0: BOOLEAN -**** followed by value byte, 0 represents false, 1 represents true + * 0: `BOOLEAN` + * followed by value byte, 0 represents false, 1 represents true -*** 1: BYTE -**** followed by value byte, representing values with two's complement + * 1: `BYTE` + * followed by value byte, representing values with two's complement -*** 2: SHORT -**** followed by UInt16 value, representing values with two's complement + * 2: `SHORT` + * followed by `UInt16` value, representing values with two's complement -*** 3: UNSIGNED SHORT -**** followed by UInt16 value + * 3: `UNSIGNED SHORT` + * followed by `UInt16` value -*** 4: LONG -**** followed by UInt32 value, representing values with two's complement + * 4: `LONG` + * followed by `UInt32` value, representing values with two's complement -*** 5: UNSIGNED LONG -**** followed by UInt32 value + * 5: `UNSIGNED LONG` + * followed by `UInt32` value -*** 6: HYPER -**** followed by UInt64 value, representing values with two's complement + * 6: `HYPER` + * followed by `UInt64` value, representing values with two's complement -*** 7: UNSIGNED HYPER -**** followed by UInt64 value + * 7: `UNSIGNED HYPER` + * followed by `UInt64` value -*** 8: FLOAT -**** followed by 4-byte value, representing values in ISO 60599 binary32 format, + * 8: `FLOAT` + * followed by 4-byte value, representing values in ISO 60599 binary32 format, LSB first -*** 9: DOUBLE -**** followed by 8-byte value, representing values in ISO 60599 binary64 format, + * 9: `DOUBLE` + * followed by 8-byte value, representing values in ISO 60599 binary64 format, LSB first * if annotated, followed by: Annotations diff --git a/unoil/README.md b/unoil/README.md index 9ccd36d2501a..3ee4882d0a35 100644 --- a/unoil/README.md +++ b/unoil/README.md @@ -1 +1,3 @@ -As offuh but for Java UNO: Maps IDL into java classes definitions. +# Java UNO IDL Code Generator + +Maps IDL into java classes definitions. This is for `offapi`, while `ridljar` is for `udkapi`. diff --git a/unotools/README.md b/unotools/README.md index bac492a83105..73ce9f08977d 100644 --- a/unotools/README.md +++ b/unotools/README.md @@ -1 +1,3 @@ +# UNO C++ Helpers + Helpers for C++ use of UNO. diff --git a/unoxml/README.md b/unoxml/README.md index 6ca6382fb10c..ce5cf0e51d3c 100644 --- a/unoxml/README.md +++ b/unoxml/README.md @@ -1 +1,3 @@ -UNO wrappers for XML services. +# UNO Wrappers for XML Services + +Contains UNO wrappers for XML services including DOM, RDF and XPath. diff --git a/ure/README.md b/ure/README.md index 23b15bf863cb..62ab46110284 100644 --- a/ure/README.md +++ b/ure/README.md @@ -1,8 +1,6 @@ -Contains the UNO Runtime Environment (URE). +# UNO Runtime Environment (URE) Beginnings of standalone UNO distribution. - You may also want to read the README located at: -[git:ure/source/README] - +`git:ure/source/README` diff --git a/uui/README.md b/uui/README.md index 43a582a44bbc..6607ebecc506 100644 --- a/uui/README.md +++ b/uui/README.md @@ -1 +1,3 @@ -Contains an Interaction Handler for the [[ucb]] and other uses. Works via VCL. +# Interaction Handler for ucb and More + +Contains an Interaction Handler for the "ucb" and other uses. Works via VCL. diff --git a/vbahelper/README.md b/vbahelper/README.md index bf569d4cd915..39df5c7e4a59 100644 --- a/vbahelper/README.md +++ b/vbahelper/README.md @@ -1 +1,3 @@ -Static helper functions for the VBA filters
\ No newline at end of file +# Helper Functions for VBA Filters + +Static helper functions for the VBA filters 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. diff --git a/winaccessibility/README.md b/winaccessibility/README.md index 2f507beacc64..6abf34a37e16 100644 --- a/winaccessibility/README.md +++ b/winaccessibility/README.md @@ -1,61 +1,62 @@ -Windows Accessibility Bridge. +# Windows Accessibility Bridge This code provides a bridge between our internal Accessibility interfaces (implemented on all visible 'things' in the suite: eg. -windows, buttons, entry boxes etc.) - and the Windows MSAA / -IAccessible2 COM interfaces that are familiar to windows users and +windows, buttons, entry boxes etc.) - and the Windows `MSAA` / +`IAccessible2` COM interfaces that are familiar to windows users and Accessible Technologies (ATs) such as the NVDA screen reader. The code breaks into three bits: -source/service/ ++ `source/service/` + the UNO service providing the accessibility bridge. It essentially listens to events from the LibreOffice core and creates and synchronises COM peers for our internal accessibility objects when events arrive. -source/UAccCom/ - + COM implementations of the MSAA / IAccessible2 interfaces ++ `source/UAccCom/` + + COM implementations of the `MSAA` / `IAccessible2` interfaces to provide native peers for the accessibility code. -source/UAccCOMIDL/ ++ `source/UAccCOMIDL/` + COM Interface Definition Language (IDL) for UAccCom. Here is one way of visualising the code / control flow -VCL <-> UNO toolkit <-> UNO a11y <-> win a11y <-> COM / IAccessible2 -vcl/ <-> toolkit/ <-> accessibility/ <-> winaccessibility/ <-> UAccCom/ + VCL <-> UNO toolkit <-> UNO a11y <-> win a11y <-> COM / IAccessible2 -Threading + vcl/ <-> toolkit/ <-> accessibility/ <-> winaccessibility/ <-> UAccCom/ + +## Threading It's possible that the UNO components are called from threads other than the main thread, so they have to be synchronized. It would be nice to put the component into a UNO apartment (and the COM components into STA) but UNO would spawn a new thread for it so it's not possible. -The COM components also call into the same global AccObjectWinManager +The COM components also call into the same global `AccObjectWinManager` as the UNO components do so both have to be synchronized in the same way. -So we use the SolarMutex for all synchronization since anything else + +So we use the `SolarMutex` for all synchronization since anything else would be rather difficult to make work. Unfortunately there is a pre-existing problem in vcl with Win32 Window creation and destruction -on non-main threads where a synchronous SendMessage is used while -the SolarMutex is locked that can cause deadlocks if the main thread is -waiting on the SolarMutex itself at that time and thus not handing the -Win32 message; this is easy to trigger with JunitTests but hopefully +on non-main threads where a synchronous `SendMessage` is used while +the `SolarMutex` is locked that can cause deadlocks if the main thread is +waiting on the `SolarMutex` itself at that time and thus not handing the +Win32 message; this is easy to trigger with `JunitTests` but hopefully not by actual end users. -Debugging / playing with winaccessibility +## Debugging / Playing with winaccessibility If NVDA is running when soffice starts, IA2 should be automatically enabled and work as expected. In order to use 'accprobe' to debug it is necessary to override the check for whether an AT (like NVDA) is running; to do that use: -SAL_FORCE_IACCESSIBLE2=1 soffice.exe -writer + SAL_FORCE_IACCESSIBLE2=1 soffice.exe -writer Then you can use accprobe to introspect the accessibility hierarchy remotely, checkout: -http://accessibility.linuxfoundation.org/a11yweb/util/accprobe/ - -But often it's more useful to look at NVDA's text output window... +<http://accessibility.linuxfoundation.org/a11yweb/util/accprobe/> +But often it's more useful to look at NVDA's text output window. diff --git a/wizards/README.md b/wizards/README.md index 332c53507af0..cb2ec6d85834 100644 --- a/wizards/README.md +++ b/wizards/README.md @@ -1,4 +1,6 @@ +# Java Wizards + Java wizards for db setup, importing, tutorials, etc. -There are also partially converted python copies of each wizard, which -we are hoping to migrate to in order to remove the Java dependency here.
\ No newline at end of file +There are also partially converted Python copies of each wizard, which +we are hoping to migrate to in order to remove the Java dependency here. diff --git a/writerfilter/README.md b/writerfilter/README.md index 7a9c8cc57df4..0c027bf42fd4 100644 --- a/writerfilter/README.md +++ b/writerfilter/README.md @@ -1,20 +1,22 @@ +# Import Filters for LibreOffice Writer + The writerfilter module contains import filters for Writer, using its UNO API. -Import filter for docx and rtf. +Import filter for DOCX and RTF. -== Module contents == - * documentation: RNG schema for the OOXML tokenizer, etc. - * inc: module-global headers (can be included by any files under source) - * qa: cppunit tests - * source: the filters themselves - * util: UNO passive registration config +* Module contents + * `documentation`: RNG schema for the OOXML tokenizer, etc. + * `inc`: module-global headers (can be included by any files under source) + * `qa`: `cppunit` tests + * `source`: the filters themselves + * `util`: UNO passive registration config -== Source contents == - * dmapper: the domain mapper, hiding UNO from the tokenizers, used by DOCX and RTF import - * The incoming traffic of dmapper can be dumped into an XML file in /tmp in - dbgutil builds, start soffice with the `SW_DEBUG_WRITERFILTER=1` - environment variable if you want that. - * filter: the UNO filter service implementations, invoked by UNO and calling +* Source contents + * `dmapper`: the domain mapper, hiding UNO from the tokenizers, used by DOCX and RTF import + * The incoming traffic of `dmapper` can be dumped into an XML file in `/tmp` in + `dbgutil` builds, start soffice with the `SW_DEBUG_WRITERFILTER=1` + environment variable if you want that. + * `filter`: the UNO filter service implementations, invoked by UNO and calling the dmapper + one of the tokenizers - * ooxml: the docx tokenizer - * rtftok: the rtf tokenizer + * `ooxml`: the docx tokenizer + * `rtftok`: the rtf tokenizer diff --git a/writerperfect/README.md b/writerperfect/README.md index 9edcb4011ec0..af23e738bb25 100644 --- a/writerperfect/README.md +++ b/writerperfect/README.md @@ -1,4 +1,7 @@ -WordPerfect and other filters, wrappers for a set of similar libraries +# Import / Export Filters for WordPerfect and Other Formats + +Contains import / export filters for WordPerfect and other formats, wrappers +for a set of similar libraries. This collection of filters is here in this folder in addition to the WordPerfect filter that gave the module its (humorous) name "writerperfect" diff --git a/xmerge/README.md b/xmerge/README.md index d45f6c4e0411..aa7183dd44d8 100644 --- a/xmerge/README.md +++ b/xmerge/README.md @@ -1,6 +1,9 @@ +# Document Conversion and Merging + For converting documents among from and into formats and also for merging them. Uses Java and plug-in architecture. -See also: -[http://xml.openoffice.org/xmerge/] +## See also + +<https://www.openoffice.org/xml/xmerge/> diff --git a/xmlhelp/README.md b/xmlhelp/README.md index 3e54ddc51bb2..60a59fc808ca 100644 --- a/xmlhelp/README.md +++ b/xmlhelp/README.md @@ -1 +1,3 @@ -Help reader and viewer for online help.
\ No newline at end of file +# XML Help + +Help reader and viewer for online help. diff --git a/xmloff/README.md b/xmloff/README.md index 45b78ae202f6..3eb276c096ad 100644 --- a/xmloff/README.md +++ b/xmloff/README.md @@ -1,4 +1,4 @@ -## Contains ODF import and export filter logic. +# ODF Import and Export Filter Logic The main library "xo" contains the basic ODF import/export filter implementation for most applications. The document is accessed @@ -9,7 +9,7 @@ The filter consumes/produces via SAX UNO API interface (implemented in applications, for example [git:sw/source/filter/xml]. There is a central list of all element or attribute names in -[git:include/xmloff/xmltoken.hxx]. The main class of the import filter +`git:include/xmloff/xmltoken.hxx`. The main class of the import filter is SvXMLImport, and of the export filter SvXMLExport. The Import filter maintains a stack of contexts for each element being @@ -37,12 +37,11 @@ consumed by the ODF import filter. There is some stuff in the "dtd" directory which is most likely related to the OpenOffice.org XML format but is possibly outdated and obsolete. -### Add new XML tokens +## Add New XML Tokens When adding a new XML token, you need to add its entry in the following three files: -* [git:include/xmloff/xmltoken.hxx] -* [git:xmloff/source/core/xmltoken.cxx] -* [git:xmloff/source/token/tokens.txt] - +* `git:include/xmloff/xmltoken.hxx` +* `git:xmloff/source/core/xmltoken.cxx` +* `git:xmloff/source/token/tokens.txt` diff --git a/xmlreader/README.md b/xmlreader/README.md index 0c6bae91bd1d..8d76e2052330 100644 --- a/xmlreader/README.md +++ b/xmlreader/README.md @@ -1,6 +1,6 @@ -fast/small XML pull parser. +# Fast and Small XML Pull Parser -Implements a simple, fast pull parser, currently used by [[configmgr]] and -[[stoc]]'s simpleregistry code (used to register UNO components in +Implements a simple, fast pull parser, currently used by `configmgr` and +`stoc`'s simpleregistry code (used to register UNO components in services.rdb files). It supports a subset of XML features, but is fast and small. diff --git a/xmlscript/README.md b/xmlscript/README.md index 84cfec6e7fde..3f0b05aa82cf 100644 --- a/xmlscript/README.md +++ b/xmlscript/README.md @@ -1,6 +1,6 @@ -XML dialogs. +# XML Dialogs This code is used to (de)serialize basic dialogs to XML for storage inside documents. While the XML -appears- to have some hierarchical structure, that is only a fabrication, parsing and underlying toolkit -widget structure is sadly linear and flat.
\ No newline at end of file +widget structure is sadly linear and flat. diff --git a/xmlsecurity/README.md b/xmlsecurity/README.md index 52a479009403..796094901112 100644 --- a/xmlsecurity/README.md +++ b/xmlsecurity/README.md @@ -1,4 +1,4 @@ -Stuff for document signing. +# Stuff for Document Signing -This code provides dialogs, and infrastructure wrapping libxmlsec and gpgme that +This code provides dialogs, and infrastructure wrapping `libxmlsec` and `gpgme` that implements document signing. |