From c16158772d64cab8a4ed1f165cab57d307998e78 Mon Sep 17 00:00:00 2001 From: Hossein Date: Tue, 23 Mar 2021 14:20:32 +0430 Subject: Using .md extension/Markdown syntax for modules README Renaming all README files for all top level modules to README.md, applying no content change at this stage to be able to track history of the files. These files should be edited to use correct Markdown syntax later. Change-Id: I542fa3f3d32072156f16eaad2211a397cc212665 Reviewed-on: https://gerrit.libreoffice.org/c/core/+/112977 Tested-by: Jenkins Reviewed-by: Christian Lohmaier --- UnoControls/README | 1 - UnoControls/README.md | 1 + accessibility/README | 1 - accessibility/README.md | 1 + android/README | 326 --------------------------------------------- android/README.md | 326 +++++++++++++++++++++++++++++++++++++++++++++ animations/README | 1 - animations/README.md | 1 + apple_remote/README | 12 -- apple_remote/README.md | 12 ++ avmedia/README | 25 ---- avmedia/README.md | 25 ++++ basctl/README | 1 - basctl/README.md | 1 + basegfx/README | 1 - basegfx/README.md | 1 + basic/README | 8 -- basic/README.md | 8 ++ bean/README | 3 - bean/README.md | 3 + bin/README | 9 -- bin/README.md | 9 ++ binaryurp/README | 9 -- binaryurp/README.md | 9 ++ bridges/README | 4 - bridges/README.md | 4 + canvas/README | 46 ------- canvas/README.md | 46 +++++++ chart2/README | 9 -- chart2/README.md | 9 ++ cli_ure/README | 5 - cli_ure/README.md | 5 + codemaker/README | 17 --- codemaker/README.md | 17 +++ comphelper/README | 4 - comphelper/README.md | 4 + compilerplugins/README | 69 ---------- compilerplugins/README.md | 69 ++++++++++ config_host/README | 25 ---- config_host/README.md | 25 ++++ configmgr/README | 136 ------------------- configmgr/README.md | 136 +++++++++++++++++++ connectivity/README | 44 ------ connectivity/README.md | 44 ++++++ cppcanvas/README | 5 - cppcanvas/README.md | 5 + cppu/README | 4 - cppu/README.md | 4 + cppuhelper/README | 4 - cppuhelper/README.md | 4 + cpputools/README | 1 - cpputools/README.md | 1 + cui/README | 8 -- cui/README.md | 8 ++ dbaccess/README | 3 - dbaccess/README.md | 3 + desktop/README | 36 ----- desktop/README.md | 36 +++++ distro-configs/README | 32 ----- distro-configs/README.md | 32 +++++ drawinglayer/README | 85 ------------ drawinglayer/README.md | 85 ++++++++++++ editeng/README | 12 -- editeng/README.md | 12 ++ embeddedobj/README | 1 - embeddedobj/README.md | 1 + embedserv/README | 1 - embedserv/README.md | 1 + emfio/README | 1 - emfio/README.md | 1 + eventattacher/README | 1 - eventattacher/README.md | 1 + extensions/README | 45 ------- extensions/README.md | 45 +++++++ external/README | 1 - external/README.md | 1 + extras/README | 61 --------- extras/README.md | 61 +++++++++ filter/README | 25 ---- filter/README.md | 25 ++++ forms/README | 1 - forms/README.md | 1 + formula/README | 5 - formula/README.md | 5 + fpicker/README | 1 - fpicker/README.md | 1 + framework/README | 4 - framework/README.md | 4 + hwpfilter/README | 5 - hwpfilter/README.md | 5 + i18nlangtag/README | 141 -------------------- i18nlangtag/README.md | 141 ++++++++++++++++++++ i18npool/README | 19 --- i18npool/README.md | 19 +++ i18nutil/README | 4 - i18nutil/README.md | 4 + icon-themes/README | 66 --------- icon-themes/README.md | 66 +++++++++ idl/README | 7 - idl/README.md | 7 + idlc/README | 6 - idlc/README.md | 6 + instsetoo_native/README | 11 -- instsetoo_native/README.md | 11 ++ io/README | 3 - io/README.md | 3 + javaunohelper/README | 2 - javaunohelper/README.md | 2 + jurt/README | 2 - jurt/README.md | 2 + jvmaccess/README | 1 - jvmaccess/README.md | 1 + jvmfwk/README | 15 --- jvmfwk/README.md | 15 +++ l10ntools/README | 3 - l10ntools/README.md | 3 + librelogo/README | 1 - librelogo/README.md | 1 + libreofficekit/README | 109 --------------- libreofficekit/README.md | 109 +++++++++++++++ lingucomponent/README | 1 - lingucomponent/README.md | 1 + linguistic/README | 1 - linguistic/README.md | 1 + lotuswordpro/README | 31 ----- lotuswordpro/README.md | 31 +++++ m4/README | 1 - m4/README.md | 1 + nlpsolver/README | 4 - nlpsolver/README.md | 4 + o3tl/README | 30 ----- o3tl/README.md | 30 +++++ odk/README | 27 ---- odk/README.md | 27 ++++ offapi/README | 19 --- offapi/README.md | 19 +++ officecfg/README | 11 -- officecfg/README.md | 11 ++ onlineupdate/README | 25 ---- onlineupdate/README.md | 25 ++++ oovbaapi/README | 5 - oovbaapi/README.md | 5 + oox/README | 185 ------------------------- oox/README.md | 185 +++++++++++++++++++++++++ opencl/README | 7 - opencl/README.md | 7 + osx/README | 4 - osx/README.md | 4 + package/README | 1 - package/README.md | 1 + pch/README | 3 - pch/README.md | 3 + postprocess/README | 6 - postprocess/README.md | 6 + pyuno/README | 19 --- pyuno/README.md | 19 +++ qadevOOo/README | 3 - qadevOOo/README.md | 3 + readlicense_oo/README | 33 ----- readlicense_oo/README.md | 33 +++++ registry/README | 15 --- registry/README.md | 15 +++ remotebridges/README | 1 - remotebridges/README.md | 1 + reportbuilder/README | 7 - reportbuilder/README.md | 7 + reportdesign/README | 1 - reportdesign/README.md | 1 + ridljar/README | 1 - ridljar/README.md | 1 + sal/README | 9 -- sal/README.md | 9 ++ salhelper/README | 1 - salhelper/README.md | 1 + sax/README | 13 -- sax/README.md | 13 ++ sc/README | 84 ------------ sc/README.md | 84 ++++++++++++ scaddins/README | 8 -- scaddins/README.md | 8 ++ sccomp/README | 1 - sccomp/README.md | 1 + schema/README | 47 ------- schema/README.md | 47 +++++++ scp2/README | 6 - scp2/README.md | 6 + scripting/README | 68 ---------- scripting/README.md | 68 ++++++++++ sd/README | 43 ------ sd/README.md | 43 ++++++ sdext/README | 30 ----- sdext/README.md | 30 +++++ sfx2/README | 28 ---- sfx2/README.md | 28 ++++ shell/README | 1 - shell/README.md | 1 + slideshow/README | 43 ------ slideshow/README.md | 43 ++++++ smoketest/README | 18 --- smoketest/README.md | 18 +++ solenv/README | 34 ----- solenv/README.md | 34 +++++ sot/README | 1 - sot/README.md | 1 + starmath/README | 4 - starmath/README.md | 4 + stoc/README | 40 ------ stoc/README.md | 40 ++++++ store/README | 5 - store/README.md | 5 + svgio/README | 1 - svgio/README.md | 1 + svl/README | 50 ------- svl/README.md | 50 +++++++ svtools/README | 1 - svtools/README.md | 1 + svx/README | 101 -------------- svx/README.md | 101 ++++++++++++++ sw/README | 211 ----------------------------- sw/README.md | 211 +++++++++++++++++++++++++++++ swext/README | 1 - swext/README.md | 1 + sysui/README | 1 - sysui/README.md | 1 + test/README | 4 - test/README.md | 4 + testtools/README | 34 ----- testtools/README.md | 34 +++++ toolkit/README | 11 -- toolkit/README.md | 11 ++ tools/README | 9 -- tools/README.md | 9 ++ ucb/README | 7 - ucb/README.md | 7 + ucbhelper/README | 1 - ucbhelper/README.md | 1 + udkapi/README | 9 -- udkapi/README.md | 9 ++ uitest/README | 1 - uitest/README.md | 1 + unodevtools/README | 6 - unodevtools/README.md | 6 + unoidl/README | 283 --------------------------------------- unoidl/README.md | 283 +++++++++++++++++++++++++++++++++++++++ unoil/README | 1 - unoil/README.md | 1 + unotools/README | 1 - unotools/README.md | 1 + unoxml/README | 1 - unoxml/README.md | 1 + ure/README | 8 -- ure/README.md | 8 ++ uui/README | 1 - uui/README.md | 1 + vbahelper/README | 1 - vbahelper/README.md | 1 + vcl/README | 242 --------------------------------- vcl/README.md | 242 +++++++++++++++++++++++++++++++++ winaccessibility/README | 61 --------- winaccessibility/README.md | 61 +++++++++ wizards/README | 4 - wizards/README.md | 4 + writerfilter/README | 20 --- writerfilter/README.md | 20 +++ writerperfect/README | 6 - writerperfect/README.md | 6 + xmerge/README | 6 - xmerge/README.md | 6 + xmlhelp/README | 1 - xmlhelp/README.md | 1 + xmlreader/README | 6 - xmlreader/README.md | 6 + xmlscript/README | 6 - xmlscript/README.md | 6 + xmlsecurity/README | 4 - xmlsecurity/README.md | 4 + 276 files changed, 3513 insertions(+), 3513 deletions(-) delete mode 100644 UnoControls/README create mode 100644 UnoControls/README.md delete mode 100644 accessibility/README create mode 100644 accessibility/README.md delete mode 100644 android/README create mode 100644 android/README.md delete mode 100644 animations/README create mode 100644 animations/README.md delete mode 100644 apple_remote/README create mode 100644 apple_remote/README.md delete mode 100644 avmedia/README create mode 100644 avmedia/README.md delete mode 100644 basctl/README create mode 100644 basctl/README.md delete mode 100644 basegfx/README create mode 100644 basegfx/README.md delete mode 100644 basic/README create mode 100644 basic/README.md delete mode 100644 bean/README create mode 100644 bean/README.md delete mode 100644 bin/README create mode 100644 bin/README.md delete mode 100644 binaryurp/README create mode 100644 binaryurp/README.md delete mode 100644 bridges/README create mode 100644 bridges/README.md delete mode 100644 canvas/README create mode 100644 canvas/README.md delete mode 100644 chart2/README create mode 100644 chart2/README.md delete mode 100644 cli_ure/README create mode 100644 cli_ure/README.md delete mode 100644 codemaker/README create mode 100644 codemaker/README.md delete mode 100644 comphelper/README create mode 100644 comphelper/README.md delete mode 100644 compilerplugins/README create mode 100644 compilerplugins/README.md delete mode 100644 config_host/README create mode 100644 config_host/README.md delete mode 100644 configmgr/README create mode 100644 configmgr/README.md delete mode 100644 connectivity/README create mode 100644 connectivity/README.md delete mode 100644 cppcanvas/README create mode 100644 cppcanvas/README.md delete mode 100644 cppu/README create mode 100644 cppu/README.md delete mode 100644 cppuhelper/README create mode 100644 cppuhelper/README.md delete mode 100644 cpputools/README create mode 100644 cpputools/README.md delete mode 100644 cui/README create mode 100644 cui/README.md delete mode 100644 dbaccess/README create mode 100644 dbaccess/README.md delete mode 100644 desktop/README create mode 100644 desktop/README.md delete mode 100644 distro-configs/README create mode 100644 distro-configs/README.md delete mode 100644 drawinglayer/README create mode 100644 drawinglayer/README.md delete mode 100644 editeng/README create mode 100644 editeng/README.md delete mode 100644 embeddedobj/README create mode 100644 embeddedobj/README.md delete mode 100644 embedserv/README create mode 100644 embedserv/README.md delete mode 100644 emfio/README create mode 100644 emfio/README.md delete mode 100644 eventattacher/README create mode 100644 eventattacher/README.md delete mode 100644 extensions/README create mode 100644 extensions/README.md delete mode 100644 external/README create mode 100644 external/README.md delete mode 100644 extras/README create mode 100644 extras/README.md delete mode 100644 filter/README create mode 100644 filter/README.md delete mode 100644 forms/README create mode 100644 forms/README.md delete mode 100644 formula/README create mode 100644 formula/README.md delete mode 100644 fpicker/README create mode 100644 fpicker/README.md delete mode 100644 framework/README create mode 100644 framework/README.md delete mode 100644 hwpfilter/README create mode 100644 hwpfilter/README.md delete mode 100644 i18nlangtag/README create mode 100644 i18nlangtag/README.md delete mode 100644 i18npool/README create mode 100644 i18npool/README.md delete mode 100644 i18nutil/README create mode 100644 i18nutil/README.md delete mode 100644 icon-themes/README create mode 100644 icon-themes/README.md delete mode 100644 idl/README create mode 100644 idl/README.md delete mode 100644 idlc/README create mode 100644 idlc/README.md delete mode 100644 instsetoo_native/README create mode 100644 instsetoo_native/README.md delete mode 100644 io/README create mode 100644 io/README.md delete mode 100644 javaunohelper/README create mode 100644 javaunohelper/README.md delete mode 100644 jurt/README create mode 100644 jurt/README.md delete mode 100644 jvmaccess/README create mode 100644 jvmaccess/README.md delete mode 100644 jvmfwk/README create mode 100644 jvmfwk/README.md delete mode 100644 l10ntools/README create mode 100644 l10ntools/README.md delete mode 100644 librelogo/README create mode 100644 librelogo/README.md delete mode 100644 libreofficekit/README create mode 100644 libreofficekit/README.md delete mode 100644 lingucomponent/README create mode 100644 lingucomponent/README.md delete mode 100644 linguistic/README create mode 100644 linguistic/README.md delete mode 100644 lotuswordpro/README create mode 100644 lotuswordpro/README.md delete mode 100644 m4/README create mode 100644 m4/README.md delete mode 100644 nlpsolver/README create mode 100644 nlpsolver/README.md delete mode 100644 o3tl/README create mode 100644 o3tl/README.md delete mode 100644 odk/README create mode 100644 odk/README.md delete mode 100644 offapi/README create mode 100644 offapi/README.md delete mode 100644 officecfg/README create mode 100644 officecfg/README.md delete mode 100644 onlineupdate/README create mode 100644 onlineupdate/README.md delete mode 100644 oovbaapi/README create mode 100644 oovbaapi/README.md delete mode 100644 oox/README create mode 100644 oox/README.md delete mode 100644 opencl/README create mode 100644 opencl/README.md delete mode 100644 osx/README create mode 100644 osx/README.md delete mode 100644 package/README create mode 100644 package/README.md delete mode 100644 pch/README create mode 100644 pch/README.md delete mode 100644 postprocess/README create mode 100644 postprocess/README.md delete mode 100644 pyuno/README create mode 100644 pyuno/README.md delete mode 100644 qadevOOo/README create mode 100644 qadevOOo/README.md delete mode 100644 readlicense_oo/README create mode 100644 readlicense_oo/README.md delete mode 100644 registry/README create mode 100644 registry/README.md delete mode 100644 remotebridges/README create mode 100644 remotebridges/README.md delete mode 100644 reportbuilder/README create mode 100644 reportbuilder/README.md delete mode 100644 reportdesign/README create mode 100644 reportdesign/README.md delete mode 100644 ridljar/README create mode 100644 ridljar/README.md delete mode 100644 sal/README create mode 100644 sal/README.md delete mode 100644 salhelper/README create mode 100644 salhelper/README.md delete mode 100644 sax/README create mode 100644 sax/README.md delete mode 100644 sc/README create mode 100644 sc/README.md delete mode 100644 scaddins/README create mode 100644 scaddins/README.md delete mode 100644 sccomp/README create mode 100644 sccomp/README.md delete mode 100644 schema/README create mode 100644 schema/README.md delete mode 100644 scp2/README create mode 100644 scp2/README.md delete mode 100644 scripting/README create mode 100644 scripting/README.md delete mode 100644 sd/README create mode 100644 sd/README.md delete mode 100644 sdext/README create mode 100644 sdext/README.md delete mode 100644 sfx2/README create mode 100644 sfx2/README.md delete mode 100644 shell/README create mode 100644 shell/README.md delete mode 100644 slideshow/README create mode 100644 slideshow/README.md delete mode 100644 smoketest/README create mode 100644 smoketest/README.md delete mode 100644 solenv/README create mode 100644 solenv/README.md delete mode 100644 sot/README create mode 100644 sot/README.md delete mode 100644 starmath/README create mode 100644 starmath/README.md delete mode 100644 stoc/README create mode 100644 stoc/README.md delete mode 100644 store/README create mode 100644 store/README.md delete mode 100644 svgio/README create mode 100644 svgio/README.md delete mode 100644 svl/README create mode 100644 svl/README.md delete mode 100644 svtools/README create mode 100644 svtools/README.md delete mode 100644 svx/README create mode 100644 svx/README.md delete mode 100644 sw/README create mode 100644 sw/README.md delete mode 100644 swext/README create mode 100644 swext/README.md delete mode 100644 sysui/README create mode 100644 sysui/README.md delete mode 100644 test/README create mode 100644 test/README.md delete mode 100644 testtools/README create mode 100644 testtools/README.md delete mode 100644 toolkit/README create mode 100644 toolkit/README.md delete mode 100644 tools/README create mode 100644 tools/README.md delete mode 100644 ucb/README create mode 100644 ucb/README.md delete mode 100644 ucbhelper/README create mode 100644 ucbhelper/README.md delete mode 100644 udkapi/README create mode 100644 udkapi/README.md delete mode 100644 uitest/README create mode 100644 uitest/README.md delete mode 100644 unodevtools/README create mode 100644 unodevtools/README.md delete mode 100644 unoidl/README create mode 100644 unoidl/README.md delete mode 100644 unoil/README create mode 100644 unoil/README.md delete mode 100644 unotools/README create mode 100644 unotools/README.md delete mode 100644 unoxml/README create mode 100644 unoxml/README.md delete mode 100644 ure/README create mode 100644 ure/README.md delete mode 100644 uui/README create mode 100644 uui/README.md delete mode 100644 vbahelper/README create mode 100644 vbahelper/README.md delete mode 100644 vcl/README create mode 100644 vcl/README.md delete mode 100644 winaccessibility/README create mode 100644 winaccessibility/README.md delete mode 100644 wizards/README create mode 100644 wizards/README.md delete mode 100644 writerfilter/README create mode 100644 writerfilter/README.md delete mode 100644 writerperfect/README create mode 100644 writerperfect/README.md delete mode 100644 xmerge/README create mode 100644 xmerge/README.md delete mode 100644 xmlhelp/README create mode 100644 xmlhelp/README.md delete mode 100644 xmlreader/README create mode 100644 xmlreader/README.md delete mode 100644 xmlscript/README create mode 100644 xmlscript/README.md delete mode 100644 xmlsecurity/README create mode 100644 xmlsecurity/README.md diff --git a/UnoControls/README b/UnoControls/README deleted file mode 100644 index 72348dc3715f..000000000000 --- a/UnoControls/README +++ /dev/null @@ -1 +0,0 @@ -Separate process and thread for progress bars, etc. diff --git a/UnoControls/README.md b/UnoControls/README.md new file mode 100644 index 000000000000..72348dc3715f --- /dev/null +++ b/UnoControls/README.md @@ -0,0 +1 @@ +Separate process and thread for progress bars, etc. diff --git a/accessibility/README b/accessibility/README deleted file mode 100644 index 9309e2725e01..000000000000 --- a/accessibility/README +++ /dev/null @@ -1 +0,0 @@ -Cares for accessibility. diff --git a/accessibility/README.md b/accessibility/README.md new file mode 100644 index 000000000000..9309e2725e01 --- /dev/null +++ b/accessibility/README.md @@ -0,0 +1 @@ +Cares for accessibility. diff --git a/android/README b/android/README deleted file mode 100644 index cfce3ddaa942..000000000000 --- a/android/README +++ /dev/null @@ -1,326 +0,0 @@ -LibreOffice Android -******************* - -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 -classes. - -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. - -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 - 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 - events as necessary. - -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) -triggered from UI. - -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). - -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 - by view rectangle and zoom. - -Layers - document view is rendered using many layers. Such layers are: document - background, scroll handles, and also the document tiles. - -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 - using OpenGL ES 2. - -- GLController (org.mozilla.gecko.gfx.GLController) - holder of the OpenGL context. - -- RenderControllerThread (org.mozilla.gecko.gfx.RenderControllerThread) executes the - rendering requests through LayerRenderer. - -- LayerRenderer (org.mozilla.gecko.gfx.LayerRenderer) renders all the layers. - -- 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 - (see "Touch events"). - -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). -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). - -TiledRendering --------------- - -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 -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 -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 -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), -which just renders the tiles at a fixed zoom level. This is then used as a background -low resolution layer. - -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 -via callback, and rechecks all tiles if they need to be invalidated. For more details see -LOKitThread#tileInvalidation). - -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 - -In most cases when an input event happens and is send to the LO core, then a message from -LO core follows. For example: when the user writes to the keyboard, key event is sent and -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), -however there are other parts too - depending on the need. - -InvalidationHandler (org.libreoffice.InvalidationHandler) is the class that is responsible -to process messages from LibreOffice core and to track the state. - -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 -the document, where selections and the cursor is drawn. - - -Icons -***** - -App uses material design icons available at [1]. - - -[1] - https://www.google.com/design/icons/ - -Emulator and debugging notes -**************************** - -For instructions on how to build for Android, see README.cross. - -* Getting something running - -Attach your device, so 'adb devices' shows it. Then run: - - cd android/source - make install - adb logcat - -and if all goes well, you should have some nice debug output to enjoy when you -start the app. - -* 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. -Instead start it from the console: - - LD_LIBRARY_PATH=$(pwd)/lib emulator-arm -avd -partition-size 500 - -where is the literal name of the AVD that you entered. - -[ 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. - -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: - - adb shell stop; adb shell start - -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 -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 - -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 - - - 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/ - - file obj/local//liblo-native-code.so - - target remote : - -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: - - (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) - -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/ 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 -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 - -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: - - adb jdwp - -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: - - adb forward tcp:7777 jdwp:31739 - -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 - -Android library only include essential services that are compiled for -LibreOffice in order to reduce the size of the apk. When developing, -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 -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, -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 - -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 - -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 -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 -bootstrapper loads that shared object with dlopen. - -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 -heavy lifting. diff --git a/android/README.md b/android/README.md new file mode 100644 index 000000000000..cfce3ddaa942 --- /dev/null +++ b/android/README.md @@ -0,0 +1,326 @@ +LibreOffice Android +******************* + +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 +classes. + +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. + +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 + 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 + events as necessary. + +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) +triggered from UI. + +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). + +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 + by view rectangle and zoom. + +Layers - document view is rendered using many layers. Such layers are: document + background, scroll handles, and also the document tiles. + +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 + using OpenGL ES 2. + +- GLController (org.mozilla.gecko.gfx.GLController) - holder of the OpenGL context. + +- RenderControllerThread (org.mozilla.gecko.gfx.RenderControllerThread) executes the + rendering requests through LayerRenderer. + +- LayerRenderer (org.mozilla.gecko.gfx.LayerRenderer) renders all the layers. + +- 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 + (see "Touch events"). + +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). +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). + +TiledRendering +-------------- + +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 +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 +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 +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), +which just renders the tiles at a fixed zoom level. This is then used as a background +low resolution layer. + +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 +via callback, and rechecks all tiles if they need to be invalidated. For more details see +LOKitThread#tileInvalidation). + +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 + +In most cases when an input event happens and is send to the LO core, then a message from +LO core follows. For example: when the user writes to the keyboard, key event is sent and +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), +however there are other parts too - depending on the need. + +InvalidationHandler (org.libreoffice.InvalidationHandler) is the class that is responsible +to process messages from LibreOffice core and to track the state. + +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 +the document, where selections and the cursor is drawn. + + +Icons +***** + +App uses material design icons available at [1]. + + +[1] - https://www.google.com/design/icons/ + +Emulator and debugging notes +**************************** + +For instructions on how to build for Android, see README.cross. + +* Getting something running + +Attach your device, so 'adb devices' shows it. Then run: + + cd android/source + make install + adb logcat + +and if all goes well, you should have some nice debug output to enjoy when you +start the app. + +* 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. +Instead start it from the console: + + LD_LIBRARY_PATH=$(pwd)/lib emulator-arm -avd -partition-size 500 + +where is the literal name of the AVD that you entered. + +[ 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. + +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: + + adb shell stop; adb shell start + +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 +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 + +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 + + - 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/ + - file obj/local//liblo-native-code.so + - target remote : + +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: + + (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) + +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/ 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 +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 + +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: + + adb jdwp + +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: + + adb forward tcp:7777 jdwp:31739 + +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 + +Android library only include essential services that are compiled for +LibreOffice in order to reduce the size of the apk. When developing, +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 +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, +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 + +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 + +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 +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 +bootstrapper loads that shared object with dlopen. + +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 +heavy lifting. diff --git a/animations/README b/animations/README deleted file mode 100644 index 00769956f0b2..000000000000 --- a/animations/README +++ /dev/null @@ -1 +0,0 @@ -Contains containers for the css::animation UNO API, used in [[slideshow]] and [[sd]]. diff --git a/animations/README.md b/animations/README.md new file mode 100644 index 000000000000..00769956f0b2 --- /dev/null +++ b/animations/README.md @@ -0,0 +1 @@ +Contains containers for the css::animation UNO API, used in [[slideshow]] and [[sd]]. diff --git a/apple_remote/README b/apple_remote/README deleted file mode 100644 index cf099f284750..000000000000 --- a/apple_remote/README +++ /dev/null @@ -1,12 +0,0 @@ -Library 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 -OOo wiki: -http://wiki.openoffice.org/wiki/Mac_OS_X_Porting_-_Apple_Remote_implementation diff --git a/apple_remote/README.md b/apple_remote/README.md new file mode 100644 index 000000000000..cf099f284750 --- /dev/null +++ b/apple_remote/README.md @@ -0,0 +1,12 @@ +Library 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 +OOo wiki: +http://wiki.openoffice.org/wiki/Mac_OS_X_Porting_-_Apple_Remote_implementation diff --git a/avmedia/README b/avmedia/README deleted file mode 100644 index 32155b2ac1cf..000000000000 --- a/avmedia/README +++ /dev/null @@ -1,25 +0,0 @@ -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 -of the graphical media playback control that appears in the toolbar / -mediaobject bar when media is selected under the .uno:AVMediaToolBox -item. - -== avmedia/gstreamer == - -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. - -The implementation is pretty straightforward, sometimes it has -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 diff --git a/avmedia/README.md b/avmedia/README.md new file mode 100644 index 000000000000..32155b2ac1cf --- /dev/null +++ b/avmedia/README.md @@ -0,0 +1,25 @@ +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 +of the graphical media playback control that appears in the toolbar / +mediaobject bar when media is selected under the .uno:AVMediaToolBox +item. + +== avmedia/gstreamer == + +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. + +The implementation is pretty straightforward, sometimes it has +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 diff --git a/basctl/README b/basctl/README deleted file mode 100644 index 44cdd8f6c46b..000000000000 --- a/basctl/README +++ /dev/null @@ -1 +0,0 @@ -Controls and dialogs for Basic. Contains the Basic IDE. diff --git a/basctl/README.md b/basctl/README.md new file mode 100644 index 000000000000..44cdd8f6c46b --- /dev/null +++ b/basctl/README.md @@ -0,0 +1 @@ +Controls and dialogs for Basic. Contains the Basic IDE. diff --git a/basegfx/README b/basegfx/README deleted file mode 100644 index 99f0feb7ae30..000000000000 --- a/basegfx/README +++ /dev/null @@ -1 +0,0 @@ -Algorithms and data types for graphics (e.g. polygons, vectors, matrices and the like - see that used in [[canvas]]). diff --git a/basegfx/README.md b/basegfx/README.md new file mode 100644 index 000000000000..99f0feb7ae30 --- /dev/null +++ b/basegfx/README.md @@ -0,0 +1 @@ +Algorithms and data types for graphics (e.g. polygons, vectors, matrices and the like - see that used in [[canvas]]). diff --git a/basic/README b/basic/README deleted file mode 100644 index c7e6654c1057..000000000000 --- a/basic/README +++ /dev/null @@ -1,8 +0,0 @@ -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] diff --git a/basic/README.md b/basic/README.md new file mode 100644 index 000000000000..c7e6654c1057 --- /dev/null +++ b/basic/README.md @@ -0,0 +1,8 @@ +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] diff --git a/bean/README b/bean/README deleted file mode 100644 index 74fe28461ed6..000000000000 --- a/bean/README +++ /dev/null @@ -1,3 +0,0 @@ -To use LibreOffice from Java applications. - -LibreOffice's API is completely exposed so that all office components can be fully controlled. diff --git a/bean/README.md b/bean/README.md new file mode 100644 index 000000000000..74fe28461ed6 --- /dev/null +++ b/bean/README.md @@ -0,0 +1,3 @@ +To use LibreOffice from Java applications. + +LibreOffice's API is completely exposed so that all office components can be fully controlled. diff --git a/bin/README b/bin/README deleted file mode 100644 index d5d0829ce1d3..000000000000 --- a/bin/README +++ /dev/null @@ -1,9 +0,0 @@ -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 - -which will try to detect and extract all the German comments in a -given source code hierarchy / directory. diff --git a/bin/README.md b/bin/README.md new file mode 100644 index 000000000000..d5d0829ce1d3 --- /dev/null +++ b/bin/README.md @@ -0,0 +1,9 @@ +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 + +which will try to detect and extract all the German comments in a +given source code hierarchy / directory. diff --git a/binaryurp/README b/binaryurp/README deleted file mode 100644 index 1f1e088944f6..000000000000 --- a/binaryurp/README +++ /dev/null @@ -1,9 +0,0 @@ -UNO Remote Protocol (URP). A binary protocol. - -UNO provides a 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/binaryurp/README.md b/binaryurp/README.md new file mode 100644 index 000000000000..1f1e088944f6 --- /dev/null +++ b/binaryurp/README.md @@ -0,0 +1,9 @@ +UNO Remote Protocol (URP). A binary protocol. + +UNO provides a 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 b/bridges/README deleted file mode 100644 index 7c0eee30bbba..000000000000 --- a/bridges/README +++ /dev/null @@ -1,4 +0,0 @@ -Bridges from various C++ ABIs, Java JNI, MS .Net to UNO and back. - -Also implementation of the UNO Remote Protocol. And in ooo-build a bridge from Mono to UNO and back. - diff --git a/bridges/README.md b/bridges/README.md new file mode 100644 index 000000000000..7c0eee30bbba --- /dev/null +++ b/bridges/README.md @@ -0,0 +1,4 @@ +Bridges from various C++ ABIs, Java JNI, MS .Net to UNO and back. + +Also implementation of the UNO Remote Protocol. And in ooo-build a bridge from Mono to UNO and back. + diff --git a/canvas/README b/canvas/README deleted file mode 100644 index b68da4c3bf5c..000000000000 --- a/canvas/README +++ /dev/null @@ -1,46 +0,0 @@ -UNO-based graphics backend, lesser impedance to modern graphics APIs -than vcl. - -== The Canvas Framework == - -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 -not exclusively by the canvas, Armin's drawinglayer module also make -use of it), which resides in basegfx. - -The UNO API used by the canvas is primarily under -css::rendering, with css::rendering::XCanvas -being the central interface. - -== The slideshow engine == - -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 -alpha-blending (currently not on all platforms). - -== Cairo canvas == - -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. - -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 -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 -can save some roundtrips when exchanging data with vcl. diff --git a/canvas/README.md b/canvas/README.md new file mode 100644 index 000000000000..b68da4c3bf5c --- /dev/null +++ b/canvas/README.md @@ -0,0 +1,46 @@ +UNO-based graphics backend, lesser impedance to modern graphics APIs +than vcl. + +== The Canvas Framework == + +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 +not exclusively by the canvas, Armin's drawinglayer module also make +use of it), which resides in basegfx. + +The UNO API used by the canvas is primarily under +css::rendering, with css::rendering::XCanvas +being the central interface. + +== The slideshow engine == + +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 +alpha-blending (currently not on all platforms). + +== Cairo canvas == + +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. + +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 +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 +can save some roundtrips when exchanging data with vcl. diff --git a/chart2/README b/chart2/README deleted file mode 100644 index 56eb0ed08cd8..000000000000 --- a/chart2/README +++ /dev/null @@ -1,9 +0,0 @@ -Chart implementation for LibreOffice Calc. - -The chart2 denotes a second generation re-write done to rid us of the -foul and twisted legacy chart code. - -== Debugging == - -=== CTRL + F12 === -This creates a layout dump based on the XShapeDumper based on SAL_WARN("chart2", ... diff --git a/chart2/README.md b/chart2/README.md new file mode 100644 index 000000000000..56eb0ed08cd8 --- /dev/null +++ b/chart2/README.md @@ -0,0 +1,9 @@ +Chart implementation for LibreOffice Calc. + +The chart2 denotes a second generation re-write done to rid us of the +foul and twisted legacy chart code. + +== Debugging == + +=== CTRL + F12 === +This creates a layout dump based on the XShapeDumper based on SAL_WARN("chart2", ... diff --git a/cli_ure/README b/cli_ure/README deleted file mode 100644 index 8f173dffe8ab..000000000000 --- a/cli_ure/README +++ /dev/null @@ -1,5 +0,0 @@ -Common Lang Infrastructure Uno Runtime Environment - support assemblies and tools for the MS .Net (and Mono) UNO binding. - -See also: -[git:cli_ure/source/readme.txt] - diff --git a/cli_ure/README.md b/cli_ure/README.md new file mode 100644 index 000000000000..8f173dffe8ab --- /dev/null +++ b/cli_ure/README.md @@ -0,0 +1,5 @@ +Common Lang Infrastructure Uno Runtime Environment - support assemblies and tools for the MS .Net (and Mono) UNO binding. + +See also: +[git:cli_ure/source/readme.txt] + diff --git a/codemaker/README b/codemaker/README deleted file mode 100644 index 436086cec5e5..000000000000 --- a/codemaker/README +++ /dev/null @@ -1,17 +0,0 @@ -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. - - -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; - -...a recipe for confusion. diff --git a/codemaker/README.md b/codemaker/README.md new file mode 100644 index 000000000000..436086cec5e5 --- /dev/null +++ b/codemaker/README.md @@ -0,0 +1,17 @@ +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. + + +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; + +...a recipe for confusion. diff --git a/comphelper/README b/comphelper/README deleted file mode 100644 index e27793533e9a..000000000000 --- a/comphelper/README +++ /dev/null @@ -1,4 +0,0 @@ -Helper functionality for implementing UNO components - -...anything not generic/mature enough to end up in URE's stable interface at -cppuhelper etc. diff --git a/comphelper/README.md b/comphelper/README.md new file mode 100644 index 000000000000..e27793533e9a --- /dev/null +++ b/comphelper/README.md @@ -0,0 +1,4 @@ +Helper functionality for implementing UNO components + +...anything not generic/mature enough to end up in URE's stable interface at +cppuhelper etc. diff --git a/compilerplugins/README b/compilerplugins/README deleted file mode 100644 index c48341e0f0d2..000000000000 --- a/compilerplugins/README +++ /dev/null @@ -1,69 +0,0 @@ -Compiler plugins. - - -== 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). - - -== Usage == - -Compiler plugins are enabled automatically by --enable-dbgutil if Clang headers -are found or explicitly using --enable-compiler-plugins. - - -== 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 === - -Used during normal compilation to perform additional checks. -All warnings and errors are marked '[loplugin]' in the message. - - -=== Rewriters === - -Rewriters analyse and possibly modify given source files. -Usage: make COMPILER_PLUGIN_TOOL= -Additional optional make arguments: -- 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= - 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 - - - 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=" 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 -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 - -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 -in rewriting mode (during which no object files are generate). - - -== Code documentation / howtos == - -http://wiki.documentfoundation.org/Clang_plugins - diff --git a/compilerplugins/README.md b/compilerplugins/README.md new file mode 100644 index 000000000000..c48341e0f0d2 --- /dev/null +++ b/compilerplugins/README.md @@ -0,0 +1,69 @@ +Compiler plugins. + + +== 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). + + +== Usage == + +Compiler plugins are enabled automatically by --enable-dbgutil if Clang headers +are found or explicitly using --enable-compiler-plugins. + + +== 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 === + +Used during normal compilation to perform additional checks. +All warnings and errors are marked '[loplugin]' in the message. + + +=== Rewriters === + +Rewriters analyse and possibly modify given source files. +Usage: make COMPILER_PLUGIN_TOOL= +Additional optional make arguments: +- 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= - 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 + - - 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=" 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 +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 + +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 +in rewriting mode (during which no object files are generate). + + +== Code documentation / howtos == + +http://wiki.documentfoundation.org/Clang_plugins + diff --git a/config_host/README b/config_host/README deleted file mode 100644 index 5dd2d5263481..000000000000 --- a/config_host/README +++ /dev/null @@ -1,25 +0,0 @@ -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, -not to Makefiles. - - - -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 - - 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 - - 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 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/config_host/README.md b/config_host/README.md new file mode 100644 index 000000000000..5dd2d5263481 --- /dev/null +++ b/config_host/README.md @@ -0,0 +1,25 @@ +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, +not to Makefiles. + + + +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 + - 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 + - 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 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 b/configmgr/README deleted file mode 100644 index 36a1340ed82a..000000000000 --- a/configmgr/README +++ /dev/null @@ -1,136 +0,0 @@ -UNO services to access the configuration database - -== Functional Overview == - -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 == - -configurationprovider.cxx -configurationregistry.cxx -defaultprovider.cxx -services.cxx - UNO service implementations. - -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). - -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. - -modifications.cxx -writemodfile.cxx - Modification management. - -broadcaster.cxx - Notification management. - -additions.hxx -update.cxx - Extension manager interface. - -data.cxx -lock.cxx -nodemap.cxx -partial.cxx -path.hxx -type.cxx - Utilities. - - -== Some Implementation Notes == - -=== 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. - -- 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 -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 -for set members, and ignores it everywhere else. - -- 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 -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 -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 -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 -removed again---whether or not that is a good idea). - - -=== XcuParser Modification Recording === - -- 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 -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 -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 - diff --git a/configmgr/README.md b/configmgr/README.md new file mode 100644 index 000000000000..36a1340ed82a --- /dev/null +++ b/configmgr/README.md @@ -0,0 +1,136 @@ +UNO services to access the configuration database + +== Functional Overview == + +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 == + +configurationprovider.cxx +configurationregistry.cxx +defaultprovider.cxx +services.cxx + UNO service implementations. + +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). + +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. + +modifications.cxx +writemodfile.cxx + Modification management. + +broadcaster.cxx + Notification management. + +additions.hxx +update.cxx + Extension manager interface. + +data.cxx +lock.cxx +nodemap.cxx +partial.cxx +path.hxx +type.cxx + Utilities. + + +== Some Implementation Notes == + +=== 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. + +- 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 +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 +for set members, and ignores it everywhere else. + +- 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 +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 +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 +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 +removed again---whether or not that is a good idea). + + +=== XcuParser Modification Recording === + +- 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 +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 +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 + diff --git a/connectivity/README b/connectivity/README deleted file mode 100644 index 40525a522227..000000000000 --- a/connectivity/README +++ /dev/null @@ -1,44 +0,0 @@ -Contains database pieces, drivers, etc. - -[[dbaccess]] builds UI on top of this. - -=== 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 - -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 - -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 - -=== 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. - -- This test does not run automatically. It can be triggered with setting - 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 - -- 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 - diff --git a/connectivity/README.md b/connectivity/README.md new file mode 100644 index 000000000000..40525a522227 --- /dev/null +++ b/connectivity/README.md @@ -0,0 +1,44 @@ +Contains database pieces, drivers, etc. + +[[dbaccess]] builds UI on top of this. + +=== 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 + +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 + +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 + +=== 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. + +- This test does not run automatically. It can be triggered with setting + 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 + +- 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 + diff --git a/cppcanvas/README b/cppcanvas/README deleted file mode 100644 index 1e9083101434..000000000000 --- a/cppcanvas/README +++ /dev/null @@ -1,5 +0,0 @@ -Helper C++ classes for [[canvas]], plus a GDIMetaFile-to-XCanvas converter. - -== EMF+ == - -For cppcanvas/source/mtfrenderer, see the README in vcl (the EMF+ part). diff --git a/cppcanvas/README.md b/cppcanvas/README.md new file mode 100644 index 000000000000..1e9083101434 --- /dev/null +++ b/cppcanvas/README.md @@ -0,0 +1,5 @@ +Helper C++ classes for [[canvas]], plus a GDIMetaFile-to-XCanvas converter. + +== EMF+ == + +For cppcanvas/source/mtfrenderer, see the README in vcl (the EMF+ part). diff --git a/cppu/README b/cppu/README deleted file mode 100644 index 066170cd7840..000000000000 --- a/cppu/README +++ /dev/null @@ -1,4 +0,0 @@ -Type definitions/implementations for the core of UNO. The exported API is in C. - -See also: -[http://wiki.openoffice.org/wiki/Uno/Binary/Modules/CPPU] diff --git a/cppu/README.md b/cppu/README.md new file mode 100644 index 000000000000..066170cd7840 --- /dev/null +++ b/cppu/README.md @@ -0,0 +1,4 @@ +Type definitions/implementations for the core of UNO. The exported API is in C. + +See also: +[http://wiki.openoffice.org/wiki/Uno/Binary/Modules/CPPU] diff --git a/cppuhelper/README b/cppuhelper/README deleted file mode 100644 index 4ea500109762..000000000000 --- a/cppuhelper/README +++ /dev/null @@ -1,4 +0,0 @@ -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/cppuhelper/README.md b/cppuhelper/README.md new file mode 100644 index 000000000000..4ea500109762 --- /dev/null +++ b/cppuhelper/README.md @@ -0,0 +1,4 @@ +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 b/cpputools/README deleted file mode 100644 index 9652827ca123..000000000000 --- a/cpputools/README +++ /dev/null @@ -1 +0,0 @@ -Old way of doing component registration. Nowadays replaced by another stand-alone UI and tools called UNO package. diff --git a/cpputools/README.md b/cpputools/README.md new file mode 100644 index 000000000000..9652827ca123 --- /dev/null +++ b/cpputools/README.md @@ -0,0 +1 @@ +Old way of doing component registration. Nowadays replaced by another stand-alone UI and tools called UNO package. diff --git a/cui/README b/cui/README deleted file mode 100644 index 9afcf8873e2a..000000000000 --- a/cui/README +++ /dev/null @@ -1,8 +0,0 @@ -Common User Interface - -It was moved out from svx in DEV300m68: - -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/cui/README.md b/cui/README.md new file mode 100644 index 000000000000..9afcf8873e2a --- /dev/null +++ b/cui/README.md @@ -0,0 +1,8 @@ +Common User Interface + +It was moved out from svx in DEV300m68: + +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 b/dbaccess/README deleted file mode 100644 index 555835a00ff0..000000000000 --- a/dbaccess/README +++ /dev/null @@ -1,3 +0,0 @@ -Database access tools, for "base" database application - -Builds on top of drivers in [[connectivity]]. diff --git a/dbaccess/README.md b/dbaccess/README.md new file mode 100644 index 000000000000..555835a00ff0 --- /dev/null +++ b/dbaccess/README.md @@ -0,0 +1,3 @@ +Database access tools, for "base" database application + +Builds on top of drivers in [[connectivity]]. diff --git a/desktop/README b/desktop/README deleted file mode 100644 index a49f0051ae1f..000000000000 --- a/desktop/README +++ /dev/null @@ -1,36 +0,0 @@ -What used to be the desktop in StarOffice 5 - now the binary. - - -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 -======= - -In the "program" directory ("program/" on Linux and Windows, "Contents/MacOS/" -on macOS). - -unoinfo -======= - -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 -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 -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. - -If the marker character is '0' (on Linux and macOS), the pathnames are -encoded as bytes, and any two pathnames in the sequence are separated from each -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. diff --git a/desktop/README.md b/desktop/README.md new file mode 100644 index 000000000000..a49f0051ae1f --- /dev/null +++ b/desktop/README.md @@ -0,0 +1,36 @@ +What used to be the desktop in StarOffice 5 - now the binary. + + +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 +======= + +In the "program" directory ("program/" on Linux and Windows, "Contents/MacOS/" +on macOS). + +unoinfo +======= + +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 +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 +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. + +If the marker character is '0' (on Linux and macOS), the pathnames are +encoded as bytes, and any two pathnames in the sequence are separated from each +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. diff --git a/distro-configs/README b/distro-configs/README deleted file mode 100644 index 66a6e324d48a..000000000000 --- a/distro-configs/README +++ /dev/null @@ -1,32 +0,0 @@ -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 -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.) - -(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: - -./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 -easiest to use the corresponding distro-configs file. This is a bug -and needs to be fixed; also configuring for Android should ideally use -sane (or the only possible) defaults and work fine without any -parameters at all. diff --git a/distro-configs/README.md b/distro-configs/README.md new file mode 100644 index 000000000000..66a6e324d48a --- /dev/null +++ b/distro-configs/README.md @@ -0,0 +1,32 @@ +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 +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.) + +(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: + +./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 +easiest to use the corresponding distro-configs file. This is a bug +and needs to be fixed; also configuring for Android should ideally use +sane (or the only possible) defaults and work fine without any +parameters at all. diff --git a/drawinglayer/README b/drawinglayer/README deleted file mode 100644 index b530ba6fedac..000000000000 --- a/drawinglayer/README +++ /dev/null @@ -1,85 +0,0 @@ -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. -A stripped down version with extended comments: - - // Create a hatch primitive (here a rectangle that will be filled with - // the appropriate hatching, but has no border). - // This will not draw it yet; it's so far only constructed to add it to a - // display list later. - const drawinglayer::primitive2d::Primitive2DReference aHatchPrimitive( - new drawinglayer::primitive2d::PolyPolygonHatchPrimitive2D(...)); - - // Create a rectangle around the hatch, to give it a border. - const drawinglayer::primitive2d::Primitive2DReference aBlackRectanglePrimitive( - new drawinglayer::primitive2d::PolygonHairlinePrimitive2D(...)); - - // Here we want to render to a virtual device (to later obtain the bitmap - // out of that), so prepare it. - VirtualDevice aVirtualDevice; - - // Create processor and draw primitives, to get it ready for rendering. - std::unique_ptr pProcessor2D( - drawinglayer::processor2d::createPixelProcessor2DFromOutputDevice(...)); - - if (pProcessor2D) - { - // Fill-in the display list. - drawinglayer::primitive2d::Primitive2DSequence aSequence(2); - - aSequence[0] = aHatchPrimitive; - aSequence[1] = aBlackRectanglePrimitive; - - // Render it to the virtual device. - pProcessor2D->process(aSequence); - pProcessor2D.reset(); - } - - // Obtain the bitmap that was rendered from the virtual device, to re-use - // it in the widget. - aRetval = aVirtualDevice.GetBitmap(Point(0, 0), aVirtualDevice.GetOutputSizePixel()); - -== 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 -primitives are 'Basic primitives', that are primitives that cannot be -decomposed. The rest of the primitives can be decomposed to the basic -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. - -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 -printing), etc. - -== How to Implement a new Primitive ("something new to draw") == - -* Create an ancestor of BasePrimitive2D - (or of its ancestor if it fits the purpose better) - - * Assign it an ID [in drawinglayer_primitivetypes2d.hxx] - - * Implement its decomposition - [virtual Primitive2DSequence create2DDecomposition(...)] - -* Extend the (various) processor(s) - If you need more than relying on just the decomposition - -== Where is DrawingLayer used == - -* SdrObject(s) (rectangles, Circles, predefined shapes etc.) - -* Selections - -* Various smaller cases to 'just draw something' - - * Draw to a virtual device, and use the resulting bitmap (like the example - above) - -* Custom widgets (like the Header / Footer indicator button) diff --git a/drawinglayer/README.md b/drawinglayer/README.md new file mode 100644 index 000000000000..b530ba6fedac --- /dev/null +++ b/drawinglayer/README.md @@ -0,0 +1,85 @@ +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. +A stripped down version with extended comments: + + // Create a hatch primitive (here a rectangle that will be filled with + // the appropriate hatching, but has no border). + // This will not draw it yet; it's so far only constructed to add it to a + // display list later. + const drawinglayer::primitive2d::Primitive2DReference aHatchPrimitive( + new drawinglayer::primitive2d::PolyPolygonHatchPrimitive2D(...)); + + // Create a rectangle around the hatch, to give it a border. + const drawinglayer::primitive2d::Primitive2DReference aBlackRectanglePrimitive( + new drawinglayer::primitive2d::PolygonHairlinePrimitive2D(...)); + + // Here we want to render to a virtual device (to later obtain the bitmap + // out of that), so prepare it. + VirtualDevice aVirtualDevice; + + // Create processor and draw primitives, to get it ready for rendering. + std::unique_ptr pProcessor2D( + drawinglayer::processor2d::createPixelProcessor2DFromOutputDevice(...)); + + if (pProcessor2D) + { + // Fill-in the display list. + drawinglayer::primitive2d::Primitive2DSequence aSequence(2); + + aSequence[0] = aHatchPrimitive; + aSequence[1] = aBlackRectanglePrimitive; + + // Render it to the virtual device. + pProcessor2D->process(aSequence); + pProcessor2D.reset(); + } + + // Obtain the bitmap that was rendered from the virtual device, to re-use + // it in the widget. + aRetval = aVirtualDevice.GetBitmap(Point(0, 0), aVirtualDevice.GetOutputSizePixel()); + +== 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 +primitives are 'Basic primitives', that are primitives that cannot be +decomposed. The rest of the primitives can be decomposed to the basic +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. + +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 +printing), etc. + +== How to Implement a new Primitive ("something new to draw") == + +* Create an ancestor of BasePrimitive2D + (or of its ancestor if it fits the purpose better) + + * Assign it an ID [in drawinglayer_primitivetypes2d.hxx] + + * Implement its decomposition + [virtual Primitive2DSequence create2DDecomposition(...)] + +* Extend the (various) processor(s) + If you need more than relying on just the decomposition + +== Where is DrawingLayer used == + +* SdrObject(s) (rectangles, Circles, predefined shapes etc.) + +* Selections + +* Various smaller cases to 'just draw something' + + * Draw to a virtual device, and use the resulting bitmap (like the example + above) + +* Custom widgets (like the Header / Footer indicator button) diff --git a/editeng/README b/editeng/README deleted file mode 100644 index 6eab9abaee4f..000000000000 --- a/editeng/README +++ /dev/null @@ -1,12 +0,0 @@ -Edit engine. - -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] - -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 - "editenginedump.log" on draw -Ctrl+Alt+F12 - dumps the current edit engine state to "editenginedump.log" diff --git a/editeng/README.md b/editeng/README.md new file mode 100644 index 000000000000..6eab9abaee4f --- /dev/null +++ b/editeng/README.md @@ -0,0 +1,12 @@ +Edit engine. + +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] + +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 + "editenginedump.log" on draw +Ctrl+Alt+F12 - dumps the current edit engine state to "editenginedump.log" diff --git a/embeddedobj/README b/embeddedobj/README deleted file mode 100644 index 3fe564abd6b3..000000000000 --- a/embeddedobj/README +++ /dev/null @@ -1 +0,0 @@ -Code for embedding objects into LibreOffice (reverse of embedserv module). diff --git a/embeddedobj/README.md b/embeddedobj/README.md new file mode 100644 index 000000000000..3fe564abd6b3 --- /dev/null +++ b/embeddedobj/README.md @@ -0,0 +1 @@ +Code for embedding objects into LibreOffice (reverse of embedserv module). diff --git a/embedserv/README b/embedserv/README deleted file mode 100644 index fdc64c389ce8..000000000000 --- a/embedserv/README +++ /dev/null @@ -1 +0,0 @@ -To embed LibreOffice via OLE2. diff --git a/embedserv/README.md b/embedserv/README.md new file mode 100644 index 000000000000..fdc64c389ce8 --- /dev/null +++ b/embedserv/README.md @@ -0,0 +1 @@ +To embed LibreOffice via OLE2. diff --git a/emfio/README b/emfio/README deleted file mode 100644 index 0b071d95c1e8..000000000000 --- a/emfio/README +++ /dev/null @@ -1 +0,0 @@ -It contains emfio/source/reader which is used for "Insert->Picture->From File". diff --git a/emfio/README.md b/emfio/README.md new file mode 100644 index 000000000000..0b071d95c1e8 --- /dev/null +++ b/emfio/README.md @@ -0,0 +1 @@ +It contains emfio/source/reader which is used for "Insert->Picture->From File". diff --git a/eventattacher/README b/eventattacher/README deleted file mode 100644 index ecfdcf75ace5..000000000000 --- a/eventattacher/README +++ /dev/null @@ -1 +0,0 @@ -How [[basic]] handles events diff --git a/eventattacher/README.md b/eventattacher/README.md new file mode 100644 index 000000000000..ecfdcf75ace5 --- /dev/null +++ b/eventattacher/README.md @@ -0,0 +1 @@ +How [[basic]] handles events diff --git a/extensions/README b/extensions/README deleted file mode 100644 index 38df77e37fba..000000000000 --- a/extensions/README +++ /dev/null @@ -1,45 +0,0 @@ -This module contains a grab-bag of unrelated misc. libraries, *none* of which is an extension. - -== 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). - -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 == - -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 - -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. - -See extensions/source/ole/ - -== ActiveX control == - -This allows embedding LO into a Win32 application as an ActiveX control. -See extensions/source/activex/ - -== Spotlight provider == - -On macOS, this allows indexing ODF documents with Spotlight. -See extensions/source/macosx/spotlight/ - -== Scanner support == - -You can scan from LibreOffice, using platform specific backends like TWAIN/SANE. -See extensions/source/scanner/ - diff --git a/extensions/README.md b/extensions/README.md new file mode 100644 index 000000000000..38df77e37fba --- /dev/null +++ b/extensions/README.md @@ -0,0 +1,45 @@ +This module contains a grab-bag of unrelated misc. libraries, *none* of which is an extension. + +== 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). + +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 == + +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 + +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. + +See extensions/source/ole/ + +== ActiveX control == + +This allows embedding LO into a Win32 application as an ActiveX control. +See extensions/source/activex/ + +== Spotlight provider == + +On macOS, this allows indexing ODF documents with Spotlight. +See extensions/source/macosx/spotlight/ + +== Scanner support == + +You can scan from LibreOffice, using platform specific backends like TWAIN/SANE. +See extensions/source/scanner/ + diff --git a/external/README b/external/README deleted file mode 100644 index 1f245df45bd1..000000000000 --- a/external/README +++ /dev/null @@ -1 +0,0 @@ -External projects bundled with LibreOffice. diff --git a/external/README.md b/external/README.md new file mode 100644 index 000000000000..1f245df45bd1 --- /dev/null +++ b/external/README.md @@ -0,0 +1 @@ +External projects bundled with LibreOffice. diff --git a/extras/README b/extras/README deleted file mode 100644 index 8644d990d5d9..000000000000 --- a/extras/README +++ /dev/null @@ -1,61 +0,0 @@ -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 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 Impress template - + clean-up template file as indicated on wiki https://wiki.documentfoundation.org/Documentation/HowTo/Impress/Make_template_language_independent - + add Foo 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 - + unzip Foo.ott in extras/source/templates//Foo (no space allowed in any file names) - + add Foo.ott in Package_.mk - + in CustomTarget_.mk: - + add Foo / in extras_TEMPLATES_ - + add files names contained in Foo.otp (except mimetype) in extras__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 - + optionally, replace extension ott (4 places) diff --git a/extras/README.md b/extras/README.md new file mode 100644 index 000000000000..8644d990d5d9 --- /dev/null +++ b/extras/README.md @@ -0,0 +1,61 @@ +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 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 Impress template + + clean-up template file as indicated on wiki https://wiki.documentfoundation.org/Documentation/HowTo/Impress/Make_template_language_independent + + add Foo 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 + + unzip Foo.ott in extras/source/templates//Foo (no space allowed in any file names) + + add Foo.ott in Package_.mk + + in CustomTarget_.mk: + + add Foo / in extras_TEMPLATES_ + + add files names contained in Foo.otp (except mimetype) in extras__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 + + optionally, replace extension ott (4 places) diff --git a/filter/README b/filter/README deleted file mode 100644 index 78d469a6859f..000000000000 --- a/filter/README +++ /dev/null @@ -1,25 +0,0 @@ -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 -graphic format import or export filters. But they don't have uniform -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. - -==================== -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/. - -Each file type e.g. text file should be represented by exactly one -type definition. This type can then be referenced by several different -filters, e.g. calc text, writer text. diff --git a/filter/README.md b/filter/README.md new file mode 100644 index 000000000000..78d469a6859f --- /dev/null +++ b/filter/README.md @@ -0,0 +1,25 @@ +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 +graphic format import or export filters. But they don't have uniform +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. + +==================== +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/. + +Each file type e.g. text file should be represented by exactly one +type definition. This type can then be referenced by several different +filters, e.g. calc text, writer text. diff --git a/forms/README b/forms/README deleted file mode 100644 index 248da82fe493..000000000000 --- a/forms/README +++ /dev/null @@ -1 +0,0 @@ -Embedded forms control and pieces (design forms in documents, fields and database driven). diff --git a/forms/README.md b/forms/README.md new file mode 100644 index 000000000000..248da82fe493 --- /dev/null +++ b/forms/README.md @@ -0,0 +1 @@ +Embedded forms control and pieces (design forms in documents, fields and database driven). diff --git a/formula/README b/formula/README deleted file mode 100644 index ab2c28a08c42..000000000000 --- a/formula/README +++ /dev/null @@ -1,5 +0,0 @@ -Contains parts of the formula parser used outside 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. diff --git a/formula/README.md b/formula/README.md new file mode 100644 index 000000000000..ab2c28a08c42 --- /dev/null +++ b/formula/README.md @@ -0,0 +1,5 @@ +Contains parts of the formula parser used outside 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. diff --git a/fpicker/README b/fpicker/README deleted file mode 100644 index ea21095c1601..000000000000 --- a/fpicker/README +++ /dev/null @@ -1 +0,0 @@ -Native file pickers for macOS and Windows (file open dialog). diff --git a/fpicker/README.md b/fpicker/README.md new file mode 100644 index 000000000000..ea21095c1601 --- /dev/null +++ b/fpicker/README.md @@ -0,0 +1 @@ +Native file pickers for macOS and Windows (file open dialog). diff --git a/framework/README b/framework/README deleted file mode 100644 index 2efd636a8022..000000000000 --- a/framework/README +++ /dev/null @@ -1,4 +0,0 @@ -Toolbars, menus, UNO stuff, including accelerators and interaction, etc. - -See also: -http://wiki.openoffice.org/wiki/Framework diff --git a/framework/README.md b/framework/README.md new file mode 100644 index 000000000000..2efd636a8022 --- /dev/null +++ b/framework/README.md @@ -0,0 +1,4 @@ +Toolbars, menus, UNO stuff, including accelerators and interaction, etc. + +See also: +http://wiki.openoffice.org/wiki/Framework diff --git a/hwpfilter/README b/hwpfilter/README deleted file mode 100644 index 293e6a1bdff7..000000000000 --- a/hwpfilter/README +++ /dev/null @@ -1,5 +0,0 @@ -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. diff --git a/hwpfilter/README.md b/hwpfilter/README.md new file mode 100644 index 000000000000..293e6a1bdff7 --- /dev/null +++ b/hwpfilter/README.md @@ -0,0 +1,5 @@ +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. diff --git a/i18nlangtag/README b/i18nlangtag/README deleted file mode 100644 index dcdb7be23144..000000000000 --- a/i18nlangtag/README +++ /dev/null @@ -1,141 +0,0 @@ -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 - -* 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'): - -* 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 - -* 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/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 - -* 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 element -*** change to 'qlt' -*** after the element add a element with the new full BCP 47 tag, for example 'sr-Latn-RS' -**** note that has no or 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/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 elements to something corresponding, for example to -** in the "Locales" properties change the element, for example sh-RS to sr-Latn-RS - -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 - -** 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/i18nlangtag/README.md b/i18nlangtag/README.md new file mode 100644 index 000000000000..dcdb7be23144 --- /dev/null +++ b/i18nlangtag/README.md @@ -0,0 +1,141 @@ +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 + +* 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'): + +* 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 + +* 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/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 + +* 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 element +*** change to 'qlt' +*** after the element add a element with the new full BCP 47 tag, for example 'sr-Latn-RS' +**** note that has no or 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/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 elements to something corresponding, for example to +** in the "Locales" properties change the element, for example sh-RS to sr-Latn-RS + +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 + +** 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 b/i18npool/README deleted file mode 100644 index 9e1a04f3f329..000000000000 --- a/i18npool/README +++ /dev/null @@ -1,19 +0,0 @@ -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...) - -Specifically for locale data documentation please see i18npool/source/localedata/data/locale.dtd - -See also [http://wiki.documentfoundation.org/Category:I18n] - -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: - - static bool beenhere = false; - if (!beenhere) { - beenhere = true; - uno::Reference< uno::XComponentContext > xComponentContext(::cppu::defaultBootstrap_InitialComponentContext()); - uno::Reference< lang::XMultiComponentFactory > xMultiComponentFactoryClient( xComponentContext->getServiceManager() ); - uno::Reference< uno::XInterface > xInterface = - xMultiComponentFactoryClient->createInstanceWithContext( "com.sun.star.i18n.BreakIterator_ja", xComponentContext ); - } diff --git a/i18npool/README.md b/i18npool/README.md new file mode 100644 index 000000000000..9e1a04f3f329 --- /dev/null +++ b/i18npool/README.md @@ -0,0 +1,19 @@ +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...) + +Specifically for locale data documentation please see i18npool/source/localedata/data/locale.dtd + +See also [http://wiki.documentfoundation.org/Category:I18n] + +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: + + static bool beenhere = false; + if (!beenhere) { + beenhere = true; + uno::Reference< uno::XComponentContext > xComponentContext(::cppu::defaultBootstrap_InitialComponentContext()); + uno::Reference< lang::XMultiComponentFactory > xMultiComponentFactoryClient( xComponentContext->getServiceManager() ); + uno::Reference< uno::XInterface > xInterface = + xMultiComponentFactoryClient->createInstanceWithContext( "com.sun.star.i18n.BreakIterator_ja", xComponentContext ); + } diff --git a/i18nutil/README b/i18nutil/README deleted file mode 100644 index 2f93fe54cedf..000000000000 --- a/i18nutil/README +++ /dev/null @@ -1,4 +0,0 @@ -i18nutil is internationalization related utilities - -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/i18nutil/README.md b/i18nutil/README.md new file mode 100644 index 000000000000..2f93fe54cedf --- /dev/null +++ b/i18nutil/README.md @@ -0,0 +1,4 @@ +i18nutil is internationalization related utilities + +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 b/icon-themes/README deleted file mode 100644 index 79ca0ed54b87..000000000000 --- a/icon-themes/README +++ /dev/null @@ -1,66 +0,0 @@ -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 / -packed for efficiency reasons based on our UI configuration by the -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: - - -breeze -colibre - -How to add a new image 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 '-'. - 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 - -- 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: ----------------------------------------- - -- Assume you defined a dispatch command in officecfg like the following: - - in officecfg/registry/data/org/openoffice/Office/UI/CalcCommands.xcu - - - - ~Open... - - - 1 - - - - 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 - for the large size and one for the smaller size. The name of each image - must be lc_.png and sc_.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 - images to the colibre theme for them to show up in any themes at all. - -How to call optipng to optimize size: ---------------------------- - -8 bit palettes are on the slow path for quartz/svp/gtk3 so avoid using palettes with... - -$ optipng -nc diff --git a/icon-themes/README.md b/icon-themes/README.md new file mode 100644 index 000000000000..79ca0ed54b87 --- /dev/null +++ b/icon-themes/README.md @@ -0,0 +1,66 @@ +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 / +packed for efficiency reasons based on our UI configuration by the +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: + + +breeze +colibre + +How to add a new image 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 '-'. + 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 + +- 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: +---------------------------------------- + +- Assume you defined a dispatch command in officecfg like the following: + + in officecfg/registry/data/org/openoffice/Office/UI/CalcCommands.xcu + + + + ~Open... + + + 1 + + + + 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 + for the large size and one for the smaller size. The name of each image + must be lc_.png and sc_.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 + images to the colibre theme for them to show up in any themes at all. + +How to call optipng to optimize size: +--------------------------- + +8 bit palettes are on the slow path for quartz/svp/gtk3 so avoid using palettes with... + +$ optipng -nc diff --git a/idl/README b/idl/README deleted file mode 100644 index b494f10abac5..000000000000 --- a/idl/README +++ /dev/null @@ -1,7 +0,0 @@ -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: - -https://wiki.openoffice.org/wiki/Framework/Article/Implementation_of_the_Dispatch_API_In_SFX2 diff --git a/idl/README.md b/idl/README.md new file mode 100644 index 000000000000..b494f10abac5 --- /dev/null +++ b/idl/README.md @@ -0,0 +1,7 @@ +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: + +https://wiki.openoffice.org/wiki/Framework/Article/Implementation_of_the_Dispatch_API_In_SFX2 diff --git a/idlc/README b/idlc/README deleted file mode 100644 index 90f015c7794a..000000000000 --- a/idlc/README +++ /dev/null @@ -1,6 +0,0 @@ -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/idlc/README.md b/idlc/README.md new file mode 100644 index 000000000000..90f015c7794a --- /dev/null +++ b/idlc/README.md @@ -0,0 +1,6 @@ +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 b/instsetoo_native/README deleted file mode 100644 index 3597a528cd7e..000000000000 --- a/instsetoo_native/README +++ /dev/null @@ -1,11 +0,0 @@ -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: - -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). diff --git a/instsetoo_native/README.md b/instsetoo_native/README.md new file mode 100644 index 000000000000..3597a528cd7e --- /dev/null +++ b/instsetoo_native/README.md @@ -0,0 +1,11 @@ +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: + +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). diff --git a/io/README b/io/README deleted file mode 100644 index 229153f04c1c..000000000000 --- a/io/README +++ /dev/null @@ -1,3 +0,0 @@ -Simple IO wrapper UNO components - - diff --git a/io/README.md b/io/README.md new file mode 100644 index 000000000000..229153f04c1c --- /dev/null +++ b/io/README.md @@ -0,0 +1,3 @@ +Simple IO wrapper UNO components + + diff --git a/javaunohelper/README b/javaunohelper/README deleted file mode 100644 index 9896ef15c629..000000000000 --- a/javaunohelper/README +++ /dev/null @@ -1,2 +0,0 @@ -Makes it easier to use UNO with Java. - diff --git a/javaunohelper/README.md b/javaunohelper/README.md new file mode 100644 index 000000000000..9896ef15c629 --- /dev/null +++ b/javaunohelper/README.md @@ -0,0 +1,2 @@ +Makes it easier to use UNO with Java. + diff --git a/jurt/README b/jurt/README deleted file mode 100644 index a2281d24bdca..000000000000 --- a/jurt/README +++ /dev/null @@ -1,2 +0,0 @@ -JURT means Java Uno Runtime and implements most of Java UNO. - diff --git a/jurt/README.md b/jurt/README.md new file mode 100644 index 000000000000..a2281d24bdca --- /dev/null +++ b/jurt/README.md @@ -0,0 +1,2 @@ +JURT means Java Uno Runtime and implements most of Java UNO. + diff --git a/jvmaccess/README b/jvmaccess/README deleted file mode 100644 index 54af22469516..000000000000 --- a/jvmaccess/README +++ /dev/null @@ -1 +0,0 @@ -Wrappers so you can use all the Java Runtime Environments with their slightly incompatible APIs with more ease. diff --git a/jvmaccess/README.md b/jvmaccess/README.md new file mode 100644 index 000000000000..54af22469516 --- /dev/null +++ b/jvmaccess/README.md @@ -0,0 +1 @@ +Wrappers so you can use all the Java Runtime Environments with their slightly incompatible APIs with more ease. diff --git a/jvmfwk/README b/jvmfwk/README deleted file mode 100644 index 7cb338e14f32..000000000000 --- a/jvmfwk/README +++ /dev/null @@ -1,15 +0,0 @@ -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 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 "javavendors_*.xml should not have -been updated...": "Changing 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 -still be supported." diff --git a/jvmfwk/README.md b/jvmfwk/README.md new file mode 100644 index 000000000000..7cb338e14f32 --- /dev/null +++ b/jvmfwk/README.md @@ -0,0 +1,15 @@ +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 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 "javavendors_*.xml should not have +been updated...": "Changing 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 +still be supported." diff --git a/l10ntools/README b/l10ntools/README deleted file mode 100644 index c3cf50b13eca..000000000000 --- a/l10ntools/README +++ /dev/null @@ -1,3 +0,0 @@ -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/l10ntools/README.md b/l10ntools/README.md new file mode 100644 index 000000000000..c3cf50b13eca --- /dev/null +++ b/l10ntools/README.md @@ -0,0 +1,3 @@ +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 b/librelogo/README deleted file mode 100644 index af75698f5f2d..000000000000 --- a/librelogo/README +++ /dev/null @@ -1 +0,0 @@ -LibreLogo is a Logo-like programming language with interactive vectorgraphics for education and DTP diff --git a/librelogo/README.md b/librelogo/README.md new file mode 100644 index 000000000000..af75698f5f2d --- /dev/null +++ b/librelogo/README.md @@ -0,0 +1 @@ +LibreLogo is a Logo-like programming language with interactive vectorgraphics for education and DTP diff --git a/libreofficekit/README b/libreofficekit/README deleted file mode 100644 index d346770e0e1d..000000000000 --- a/libreofficekit/README +++ /dev/null @@ -1,109 +0,0 @@ -LibreOfficeKit -************** - -LibreOfficeKit can be used for accessing LibreOffice functionality -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 ------------------------------------ - -LOK functionality can be accessed by including LibreOfficeKit.h[xx] in your -program. - -LOK initialisation (lok_init) requires the inclusion of LibreOfficeKitInit.h in -your program. If you use the C++ LibreOfficeKit.hxx header, it already includes -LibreOfficeKitInit.h for you. - -(LibreOfficeKit.hxx is a simple and fully inlined C++ wrapper for the same -functionality as in LibreOfficeKit.h.) - -An example program can be seen on: -https://gitlab.com/ojwb/lloconv - -Tiled Rendering ---------------- - -To use LOK Tiled Rendering you will need the following before the LOK includes: -#define LOK_USE_UNSTABLE_API - -(This must be define before ANY LOK header, i.e. including the Init header.) - -Currently only bitmap-buffer rendering is supported, with a 32-bit BGRA -colorspace (further alternatives could feasibly be implemented as needed). -Scanlines are ordered top-down (whereas LibreOffice will internally default -to bottom-up). - -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 -client and LibreOffice is a two-way channel. The client can initiate an action -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 - (soft-)keyboard. -- 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 -methods and their documentation. - -The other way around (LibreOffice -> LOK client) is implemented using a -callback. A LOK client can register a callback using the registerCallback() -method. Whenever editing requires some action on the client side, a callback -event is emitted. The callback types are described using the -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 - intersect with the provided rectangle -- 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 - by the client as the set of rectangles describing the selection overlay - changed - -There are currently two known LOK clients supporting tiled editing: - -- gtktiledviewer (see below), which allows testing the LOK core implementation - on (desktop) Linux -- (LibreOffice on) Android - -Core has next to no idea what is the LOK client, so for effective development, -it's recommended that the core part is developed against gtktiledviewer, and -once a feature works there, then implement the Android part, with its slower -development iteration (slow uploading to the device, the need to link all -object files into a single .so, etc). - -* Debugging with gdb and gtktiledviewer - -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 - - G_MESSAGES_DEBUG=all bin/run gtktiledviewer --lo-path=$PWD/instdir/program ../test.odt - -To debug with gdb: - - export LO_TRACE='gdb --tui --args' - -before bin/run, this will run gtktiledviewer in the debugger instead. - -LibreOfficeKitGtk -***************** - -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' -environment variable to display those messages. diff --git a/libreofficekit/README.md b/libreofficekit/README.md new file mode 100644 index 000000000000..d346770e0e1d --- /dev/null +++ b/libreofficekit/README.md @@ -0,0 +1,109 @@ +LibreOfficeKit +************** + +LibreOfficeKit can be used for accessing LibreOffice functionality +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 +----------------------------------- + +LOK functionality can be accessed by including LibreOfficeKit.h[xx] in your +program. + +LOK initialisation (lok_init) requires the inclusion of LibreOfficeKitInit.h in +your program. If you use the C++ LibreOfficeKit.hxx header, it already includes +LibreOfficeKitInit.h for you. + +(LibreOfficeKit.hxx is a simple and fully inlined C++ wrapper for the same +functionality as in LibreOfficeKit.h.) + +An example program can be seen on: +https://gitlab.com/ojwb/lloconv + +Tiled Rendering +--------------- + +To use LOK Tiled Rendering you will need the following before the LOK includes: +#define LOK_USE_UNSTABLE_API + +(This must be define before ANY LOK header, i.e. including the Init header.) + +Currently only bitmap-buffer rendering is supported, with a 32-bit BGRA +colorspace (further alternatives could feasibly be implemented as needed). +Scanlines are ordered top-down (whereas LibreOffice will internally default +to bottom-up). + +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 +client and LibreOffice is a two-way channel. The client can initiate an action +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 + (soft-)keyboard. +- 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 +methods and their documentation. + +The other way around (LibreOffice -> LOK client) is implemented using a +callback. A LOK client can register a callback using the registerCallback() +method. Whenever editing requires some action on the client side, a callback +event is emitted. The callback types are described using the +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 + intersect with the provided rectangle +- 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 + by the client as the set of rectangles describing the selection overlay + changed + +There are currently two known LOK clients supporting tiled editing: + +- gtktiledviewer (see below), which allows testing the LOK core implementation + on (desktop) Linux +- (LibreOffice on) Android + +Core has next to no idea what is the LOK client, so for effective development, +it's recommended that the core part is developed against gtktiledviewer, and +once a feature works there, then implement the Android part, with its slower +development iteration (slow uploading to the device, the need to link all +object files into a single .so, etc). + +* Debugging with gdb and gtktiledviewer + +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 + + G_MESSAGES_DEBUG=all bin/run gtktiledviewer --lo-path=$PWD/instdir/program ../test.odt + +To debug with gdb: + + export LO_TRACE='gdb --tui --args' + +before bin/run, this will run gtktiledviewer in the debugger instead. + +LibreOfficeKitGtk +***************** + +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' +environment variable to display those messages. diff --git a/lingucomponent/README b/lingucomponent/README deleted file mode 100644 index b2e6717a7fec..000000000000 --- a/lingucomponent/README +++ /dev/null @@ -1 +0,0 @@ -Spellcheck, hyphenator, thesaurus, etc. diff --git a/lingucomponent/README.md b/lingucomponent/README.md new file mode 100644 index 000000000000..b2e6717a7fec --- /dev/null +++ b/lingucomponent/README.md @@ -0,0 +1 @@ +Spellcheck, hyphenator, thesaurus, etc. diff --git a/linguistic/README b/linguistic/README deleted file mode 100644 index 39f447ce1121..000000000000 --- a/linguistic/README +++ /dev/null @@ -1 +0,0 @@ -Handles registered modules for spellchecker, hyphenator and thesaurus. diff --git a/linguistic/README.md b/linguistic/README.md new file mode 100644 index 000000000000..39f447ce1121 --- /dev/null +++ b/linguistic/README.md @@ -0,0 +1 @@ +Handles registered modules for spellchecker, hyphenator and thesaurus. diff --git a/lotuswordpro/README b/lotuswordpro/README deleted file mode 100644 index a1e3c20e0167..000000000000 --- a/lotuswordpro/README +++ /dev/null @@ -1,31 +0,0 @@ -Import filter for file format of Lotus Word Pro. - -== 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 -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. - -== 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 - -=== 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/lotuswordpro/README.md b/lotuswordpro/README.md new file mode 100644 index 000000000000..a1e3c20e0167 --- /dev/null +++ b/lotuswordpro/README.md @@ -0,0 +1,31 @@ +Import filter for file format of Lotus Word Pro. + +== 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 +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. + +== 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 + +=== 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 b/m4/README deleted file mode 100644 index 33ac576e2685..000000000000 --- a/m4/README +++ /dev/null @@ -1 +0,0 @@ -m4 - Macros to locate and utilise pkg-config. diff --git a/m4/README.md b/m4/README.md new file mode 100644 index 000000000000..33ac576e2685 --- /dev/null +++ b/m4/README.md @@ -0,0 +1 @@ +m4 - Macros to locate and utilise pkg-config. diff --git a/nlpsolver/README b/nlpsolver/README deleted file mode 100644 index 4142e4344a0d..000000000000 --- a/nlpsolver/README +++ /dev/null @@ -1,4 +0,0 @@ -This extension integrates into 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. \ No newline at end of file diff --git a/nlpsolver/README.md b/nlpsolver/README.md new file mode 100644 index 000000000000..4142e4344a0d --- /dev/null +++ b/nlpsolver/README.md @@ -0,0 +1,4 @@ +This extension integrates into 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. \ No newline at end of file diff --git a/o3tl/README b/o3tl/README deleted file mode 100644 index 7900e70171d0..000000000000 --- a/o3tl/README +++ /dev/null @@ -1,30 +0,0 @@ -Very basic template functionality, a bit like boost or stl, but specific to LibO - -o3tl stands for "OOo [o3, get it?] template library" - -From [http://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 -to boost, but isn't as of now)." - -== 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] -Represents a range of integer or iterator values. - -[git:o3tl/inc/o3tl/vector_pool.hxx] -Simple vector-based memory pool allocator. - -[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). diff --git a/o3tl/README.md b/o3tl/README.md new file mode 100644 index 000000000000..7900e70171d0 --- /dev/null +++ b/o3tl/README.md @@ -0,0 +1,30 @@ +Very basic template functionality, a bit like boost or stl, but specific to LibO + +o3tl stands for "OOo [o3, get it?] template library" + +From [http://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 +to boost, but isn't as of now)." + +== 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] +Represents a range of integer or iterator values. + +[git:o3tl/inc/o3tl/vector_pool.hxx] +Simple vector-based memory pool allocator. + +[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). diff --git a/odk/README b/odk/README deleted file mode 100644 index 4370e63e594f..000000000000 --- a/odk/README +++ /dev/null @@ -1,27 +0,0 @@ -Office development kit - 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/) - -* See 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. - -* 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 - - 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.) diff --git a/odk/README.md b/odk/README.md new file mode 100644 index 000000000000..4370e63e594f --- /dev/null +++ b/odk/README.md @@ -0,0 +1,27 @@ +Office development kit - 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/) + +* See 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. + +* 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 + + 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.) diff --git a/offapi/README b/offapi/README deleted file mode 100644 index 80c60484d1c7..000000000000 --- a/offapi/README +++ /dev/null @@ -1,19 +0,0 @@ -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), -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. diff --git a/offapi/README.md b/offapi/README.md new file mode 100644 index 000000000000..80c60484d1c7 --- /dev/null +++ b/offapi/README.md @@ -0,0 +1,19 @@ +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), +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. diff --git a/officecfg/README b/officecfg/README deleted file mode 100644 index f8861307d0db..000000000000 --- a/officecfg/README +++ /dev/null @@ -1,11 +0,0 @@ -The schema and default settings for the OpenOffice.org configuration database. - -If you change a file in this module, then a make postprocess is needed after make officecfg. - -See also: -[[configmgr]] - -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/officecfg/README.md b/officecfg/README.md new file mode 100644 index 000000000000..f8861307d0db --- /dev/null +++ b/officecfg/README.md @@ -0,0 +1,11 @@ +The schema and default settings for the OpenOffice.org configuration database. + +If you change a file in this module, then a make postprocess is needed after make officecfg. + +See also: +[[configmgr]] + +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 b/onlineupdate/README deleted file mode 100644 index 485a718499b3..000000000000 --- a/onlineupdate/README +++ /dev/null @@ -1,25 +0,0 @@ -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 - -The source/service directory contains the code for the silent windows updater that avoids the repeated administrator check for an update. - -== 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. - -On Windows we use the system to provide us with a crypto library whereas on Linux we use NSS. - -== 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. - -=== 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 "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/onlineupdate/README.md b/onlineupdate/README.md new file mode 100644 index 000000000000..485a718499b3 --- /dev/null +++ b/onlineupdate/README.md @@ -0,0 +1,25 @@ +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 + +The source/service directory contains the code for the silent windows updater that avoids the repeated administrator check for an update. + +== 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. + +On Windows we use the system to provide us with a crypto library whereas on Linux we use NSS. + +== 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. + +=== 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 "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 b/oovbaapi/README deleted file mode 100644 index e869b5e45741..000000000000 --- a/oovbaapi/README +++ /dev/null @@ -1,5 +0,0 @@ -Module for OpenOffice - VisualBasic interoperability. - -See also: -[http://wiki.openoffice.org/wiki/VBA] -[http://wiki.openoffice.org/wiki/Oovbaapi] diff --git a/oovbaapi/README.md b/oovbaapi/README.md new file mode 100644 index 000000000000..e869b5e45741 --- /dev/null +++ b/oovbaapi/README.md @@ -0,0 +1,5 @@ +Module for OpenOffice - VisualBasic interoperability. + +See also: +[http://wiki.openoffice.org/wiki/VBA] +[http://wiki.openoffice.org/wiki/Oovbaapi] diff --git a/oox/README b/oox/README deleted file mode 100644 index 6c459f58c92a..000000000000 --- a/oox/README +++ /dev/null @@ -1,185 +0,0 @@ -Support for Office Open XML, the office XML-format designed by Microsoft. - - -== 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 -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 -how custom shape properties are converted. - -Preset shapes are custom shapes whose guides and handles -have been defined in OOXML specification. By specifying -preset type and the adjustment values, the reset can -be taken from the shape definition. - -example of drawingml preset: - - - - - -example of drawingml custom shape (equal to star5 preset): - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -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 -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 -backward compatibility, before we can extend the ODF. that's why you -will see 2 of them in cases where some of the new commands was -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 -files for single presets and also for all presets -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. - -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. - -The generated pptx files -can be used when debugging bugs in custom shapes import/export. also -the cshape-all.pptx can be used to test the round trips. there's small -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 - -== Export == -Here is how LO's enhanced custom shapes are exported: -* 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 - are provided so that default values are taken, or the exact set - of handles have to be provided. In some cases we are converting - from the preset with less handles to the one with more handles - 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. - -Check Andras Timar's presentation[1] and ShapeExport::WriteCustomShape() -for further detail. - -FUTURE WORK: 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 -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 diff --git a/oox/README.md b/oox/README.md new file mode 100644 index 000000000000..6c459f58c92a --- /dev/null +++ b/oox/README.md @@ -0,0 +1,185 @@ +Support for Office Open XML, the office XML-format designed by Microsoft. + + +== 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 +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 +how custom shape properties are converted. + +Preset shapes are custom shapes whose guides and handles +have been defined in OOXML specification. By specifying +preset type and the adjustment values, the reset can +be taken from the shape definition. + +example of drawingml preset: + + + + + +example of drawingml custom shape (equal to star5 preset): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +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 +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 +backward compatibility, before we can extend the ODF. that's why you +will see 2 of them in cases where some of the new commands was +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 +files for single presets and also for all presets +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. + +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. + +The generated pptx files +can be used when debugging bugs in custom shapes import/export. also +the cshape-all.pptx can be used to test the round trips. there's small +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 + +== Export == +Here is how LO's enhanced custom shapes are exported: +* 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 + are provided so that default values are taken, or the exact set + of handles have to be provided. In some cases we are converting + from the preset with less handles to the one with more handles + 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. + +Check Andras Timar's presentation[1] and ShapeExport::WriteCustomShape() +for further detail. + +FUTURE WORK: 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 +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 diff --git a/opencl/README b/opencl/README deleted file mode 100644 index c5699e797a50..000000000000 --- a/opencl/README +++ /dev/null @@ -1,7 +0,0 @@ -OpenCL-related code that is not specific to any particular -functionality OpenCL is used for. (Like formula group calculation in -Calc.) - -Not compiled on platforms where OpenCL is not available (iOS and -Android). On other platforms OpenCL is optional at run-time, but not -at build time. diff --git a/opencl/README.md b/opencl/README.md new file mode 100644 index 000000000000..c5699e797a50 --- /dev/null +++ b/opencl/README.md @@ -0,0 +1,7 @@ +OpenCL-related code that is not specific to any particular +functionality OpenCL is used for. (Like formula group calculation in +Calc.) + +Not compiled on platforms where OpenCL is not available (iOS and +Android). On other platforms OpenCL is optional at run-time, but not +at build time. diff --git a/osx/README b/osx/README deleted file mode 100644 index 260a7ed48276..000000000000 --- a/osx/README +++ /dev/null @@ -1,4 +0,0 @@ -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 diff --git a/osx/README.md b/osx/README.md new file mode 100644 index 000000000000..260a7ed48276 --- /dev/null +++ b/osx/README.md @@ -0,0 +1,4 @@ +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 diff --git a/package/README b/package/README deleted file mode 100644 index c9055dfee91a..000000000000 --- a/package/README +++ /dev/null @@ -1 +0,0 @@ -Reading and writing ZIPs. diff --git a/package/README.md b/package/README.md new file mode 100644 index 000000000000..c9055dfee91a --- /dev/null +++ b/package/README.md @@ -0,0 +1 @@ +Reading and writing ZIPs. diff --git a/pch/README b/pch/README deleted file mode 100644 index b6c8ca9dd932..000000000000 --- a/pch/README +++ /dev/null @@ -1,3 +0,0 @@ -The purpose of this directory is to generate global precompiled headers -that can be used by any other gbuild library/executable. -The libraries themselves are not used. diff --git a/pch/README.md b/pch/README.md new file mode 100644 index 000000000000..b6c8ca9dd932 --- /dev/null +++ b/pch/README.md @@ -0,0 +1,3 @@ +The purpose of this directory is to generate global precompiled headers +that can be used by any other gbuild library/executable. +The libraries themselves are not used. diff --git a/postprocess/README b/postprocess/README deleted file mode 100644 index a29596729bd0..000000000000 --- a/postprocess/README +++ /dev/null @@ -1,6 +0,0 @@ -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 -of all the other de-coupled modules. See the first line of -[[postprocess/prj/build.lst]] for that. diff --git a/postprocess/README.md b/postprocess/README.md new file mode 100644 index 000000000000..a29596729bd0 --- /dev/null +++ b/postprocess/README.md @@ -0,0 +1,6 @@ +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 +of all the other de-coupled modules. See the first line of +[[postprocess/prj/build.lst]] for that. diff --git a/pyuno/README b/pyuno/README deleted file mode 100644 index 4d88391229f1..000000000000 --- a/pyuno/README +++ /dev/null @@ -1,19 +0,0 @@ -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 - -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. - -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/pyuno/README.md b/pyuno/README.md new file mode 100644 index 000000000000..4d88391229f1 --- /dev/null +++ b/pyuno/README.md @@ -0,0 +1,19 @@ +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 + +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. + +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 b/qadevOOo/README deleted file mode 100644 index 50569304a383..000000000000 --- a/qadevOOo/README +++ /dev/null @@ -1,3 +0,0 @@ -Testsuite. - -You can import this as a project into Eclipse (select the qadevOOo folder). \ No newline at end of file diff --git a/qadevOOo/README.md b/qadevOOo/README.md new file mode 100644 index 000000000000..50569304a383 --- /dev/null +++ b/qadevOOo/README.md @@ -0,0 +1,3 @@ +Testsuite. + +You can import this as a project into Eclipse (select the qadevOOo folder). \ No newline at end of file diff --git a/readlicense_oo/README b/readlicense_oo/README deleted file mode 100644 index eb6c4482df15..000000000000 --- a/readlicense_oo/README +++ /dev/null @@ -1,33 +0,0 @@ -Contains the stock libreoffice licensing blurb, as distributed in the install -directory, and also potentially at run-time. - -Generating licence files ------------------------- - -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. - -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. - -Variables used for conditional text: - -- 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 - 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. - -- WITH_THEMES: A space separated list of icon sets that are used in the build. - -Conditional text are surrounded by and extra
tag. The class attribute of -that
tag decides which parameter values are taken into consideration. diff --git a/readlicense_oo/README.md b/readlicense_oo/README.md new file mode 100644 index 000000000000..eb6c4482df15 --- /dev/null +++ b/readlicense_oo/README.md @@ -0,0 +1,33 @@ +Contains the stock libreoffice licensing blurb, as distributed in the install +directory, and also potentially at run-time. + +Generating licence files +------------------------ + +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. + +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. + +Variables used for conditional text: + +- 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 + 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. + +- WITH_THEMES: A space separated list of icon sets that are used in the build. + +Conditional text are surrounded by and extra
tag. The class attribute of +that
tag decides which parameter values are taken into consideration. diff --git a/registry/README b/registry/README deleted file mode 100644 index 914db30a2f01..000000000000 --- a/registry/README +++ /dev/null @@ -1,15 +0,0 @@ -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 -that turns this into a type registry is implemented here. - -While this code is primarily used in only two modes: - -* linear write / concatenate -* random access read - -The API unfortunately exposes a random-access write approach, which - -while ~unused needs before we can re-write this away from the store -backend. diff --git a/registry/README.md b/registry/README.md new file mode 100644 index 000000000000..914db30a2f01 --- /dev/null +++ b/registry/README.md @@ -0,0 +1,15 @@ +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 +that turns this into a type registry is implemented here. + +While this code is primarily used in only two modes: + +* linear write / concatenate +* random access read + +The API unfortunately exposes a random-access write approach, which - +while ~unused needs before we can re-write this away from the store +backend. diff --git a/remotebridges/README b/remotebridges/README deleted file mode 100644 index cfe0d196afef..000000000000 --- a/remotebridges/README +++ /dev/null @@ -1 +0,0 @@ -UNO services dealing with interprocess bridges. diff --git a/remotebridges/README.md b/remotebridges/README.md new file mode 100644 index 000000000000..cfe0d196afef --- /dev/null +++ b/remotebridges/README.md @@ -0,0 +1 @@ +UNO services dealing with interprocess bridges. diff --git a/reportbuilder/README b/reportbuilder/README deleted file mode 100644 index 696cc4b4830a..000000000000 --- a/reportbuilder/README +++ /dev/null @@ -1,7 +0,0 @@ -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], -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/]. diff --git a/reportbuilder/README.md b/reportbuilder/README.md new file mode 100644 index 000000000000..696cc4b4830a --- /dev/null +++ b/reportbuilder/README.md @@ -0,0 +1,7 @@ +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], +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/]. diff --git a/reportdesign/README b/reportdesign/README deleted file mode 100644 index 0cffd43da3ef..000000000000 --- a/reportdesign/README +++ /dev/null @@ -1 +0,0 @@ -Legacy Reports for LibreOffice Base diff --git a/reportdesign/README.md b/reportdesign/README.md new file mode 100644 index 000000000000..0cffd43da3ef --- /dev/null +++ b/reportdesign/README.md @@ -0,0 +1 @@ +Legacy Reports for LibreOffice Base diff --git a/ridljar/README b/ridljar/README deleted file mode 100644 index 0f3afff183a8..000000000000 --- a/ridljar/README +++ /dev/null @@ -1 +0,0 @@ -Implements types for the Java Uno typesystem. diff --git a/ridljar/README.md b/ridljar/README.md new file mode 100644 index 000000000000..0f3afff183a8 --- /dev/null +++ b/ridljar/README.md @@ -0,0 +1 @@ +Implements types for the Java Uno typesystem. diff --git a/sal/README b/sal/README deleted file mode 100644 index 324c64fa4a78..000000000000 --- a/sal/README +++ /dev/null @@ -1,9 +0,0 @@ -System abstraction layer; rtl, osl and sal - -rtl: -Platform independent strings - -osl: -platform specific stuff, threads, dynamic loading, process, ipc, etc - -Exports only C API and some inline-methods (only C++ API). diff --git a/sal/README.md b/sal/README.md new file mode 100644 index 000000000000..324c64fa4a78 --- /dev/null +++ b/sal/README.md @@ -0,0 +1,9 @@ +System abstraction layer; rtl, osl and sal + +rtl: +Platform independent strings + +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 b/salhelper/README deleted file mode 100644 index 019a562df485..000000000000 --- a/salhelper/README +++ /dev/null @@ -1 +0,0 @@ -C++ helpers to make use of sal easier. diff --git a/salhelper/README.md b/salhelper/README.md new file mode 100644 index 000000000000..019a562df485 --- /dev/null +++ b/salhelper/README.md @@ -0,0 +1 @@ +C++ helpers to make use of sal easier. diff --git a/sax/README b/sax/README deleted file mode 100644 index 00ca0f1af5ae..000000000000 --- a/sax/README +++ /dev/null @@ -1,13 +0,0 @@ -UNO services for SAX parsing and C++ functions for XMLSchema-2 data types. - -* source/expwrap: - string-based SAX parser UNO service wrapping expat -* source/fastparser: - multi-threaded token-based SAX parser UNO service wrapping libxml2 -* 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" - diff --git a/sax/README.md b/sax/README.md new file mode 100644 index 000000000000..00ca0f1af5ae --- /dev/null +++ b/sax/README.md @@ -0,0 +1,13 @@ +UNO services for SAX parsing and C++ functions for XMLSchema-2 data types. + +* source/expwrap: + string-based SAX parser UNO service wrapping expat +* source/fastparser: + multi-threaded token-based SAX parser UNO service wrapping libxml2 +* 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" + diff --git a/sc/README b/sc/README deleted file mode 100644 index e355e0c3c612..000000000000 --- a/sc/README +++ /dev/null @@ -1,84 +0,0 @@ -Spreadsheet application code. - -You can dump some information in a dbgutil build: - -=== CTRL+SHIFT+F12 === - -Dumps the column width of the first 20 columns. - -=== CTRL+SHIFT+F11 === - -Dumps the graphic objects and their position and size in pixel. - -=== 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 === - -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: - * Number of Columns: 64 bit unsigned integer - -Column: - * Column Index: 64 bit unsigned integer - * Column Size: 64 bit unsigned integer - * For each cell type block a new ColumnBlock - -ColumnBlock: - * Start Row: 64 bit unsigned integer - * Block Size: 64 bit unsigned integer - * Type: 8 bit unsigned integer - - 0 : empty - - 1 : numeric - * for each cell: 64 bit IEEE 754 double precision value - - 2 : string - * for each cell: 32 bit signed string length followed by string length bytes of the string (UTF-8) - - 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 === - -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 -Expressions *and* depend on the setting under -Tools -> Options -> Calc -> Calculate are those that in ODF OpenFormula (ODFF) -are defined to depend on the HOST-USE-REGULAR-EXPRESSIONS or HOST-USE-WILDCARDS -properties, see -https://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os-part2.html - -* Database Functions - * DAVERAGE - * DCOUNT - * DCOUNTA - * DGET - * DMAX - * DMIN - * DPRODUCT - * DSTDEV - * DSTDEVP - * DSUM - * DVAR - * DVARP -* Information Functions - * COUNTIF - * COUNTIFS -* Lookup Functions - * HLOOKUP - * LOOKUP - * MATCH - * VLOOKUP -* Mathematical Functions - * SUMIF - * SUMIFS -* Statistical Functions - * AVERAGEIF - * AVERAGEIFS -* Text Functions - * SEARCH diff --git a/sc/README.md b/sc/README.md new file mode 100644 index 000000000000..e355e0c3c612 --- /dev/null +++ b/sc/README.md @@ -0,0 +1,84 @@ +Spreadsheet application code. + +You can dump some information in a dbgutil build: + +=== CTRL+SHIFT+F12 === + +Dumps the column width of the first 20 columns. + +=== CTRL+SHIFT+F11 === + +Dumps the graphic objects and their position and size in pixel. + +=== 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 === + +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: + * Number of Columns: 64 bit unsigned integer + +Column: + * Column Index: 64 bit unsigned integer + * Column Size: 64 bit unsigned integer + * For each cell type block a new ColumnBlock + +ColumnBlock: + * Start Row: 64 bit unsigned integer + * Block Size: 64 bit unsigned integer + * Type: 8 bit unsigned integer + - 0 : empty + - 1 : numeric + * for each cell: 64 bit IEEE 754 double precision value + - 2 : string + * for each cell: 32 bit signed string length followed by string length bytes of the string (UTF-8) + - 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 === + +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 +Expressions *and* depend on the setting under +Tools -> Options -> Calc -> Calculate are those that in ODF OpenFormula (ODFF) +are defined to depend on the HOST-USE-REGULAR-EXPRESSIONS or HOST-USE-WILDCARDS +properties, see +https://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os-part2.html + +* Database Functions + * DAVERAGE + * DCOUNT + * DCOUNTA + * DGET + * DMAX + * DMIN + * DPRODUCT + * DSTDEV + * DSTDEVP + * DSUM + * DVAR + * DVARP +* Information Functions + * COUNTIF + * COUNTIFS +* Lookup Functions + * HLOOKUP + * LOOKUP + * MATCH + * VLOOKUP +* Mathematical Functions + * SUMIF + * SUMIFS +* Statistical Functions + * AVERAGEIF + * AVERAGEIFS +* Text Functions + * SEARCH diff --git a/scaddins/README b/scaddins/README deleted file mode 100644 index 1e0f88eacbcf..000000000000 --- a/scaddins/README +++ /dev/null @@ -1,8 +0,0 @@ -Extra functions for calc. - -These provide UNO components that implement more exotic 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] diff --git a/scaddins/README.md b/scaddins/README.md new file mode 100644 index 000000000000..1e0f88eacbcf --- /dev/null +++ b/scaddins/README.md @@ -0,0 +1,8 @@ +Extra functions for calc. + +These provide UNO components that implement more exotic 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] diff --git a/sccomp/README b/sccomp/README deleted file mode 100644 index 30cc7490cef3..000000000000 --- a/sccomp/README +++ /dev/null @@ -1 +0,0 @@ -The (linear) solver for LibreOffice Calc. diff --git a/sccomp/README.md b/sccomp/README.md new file mode 100644 index 000000000000..30cc7490cef3 --- /dev/null +++ b/sccomp/README.md @@ -0,0 +1 @@ +The (linear) solver for LibreOffice Calc. diff --git a/schema/README b/schema/README deleted file mode 100644 index f32038ed82c8..000000000000 --- a/schema/README +++ /dev/null @@ -1,47 +0,0 @@ -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. - -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 -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 -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 -add another attribute like this: - - - - - - - - - -Currently only the features that are actually exported in the unit tests have -been added to the schema; there is still some work to do here to add -everything; the crashtesting script also does ODF validation of all files and -now also uses the custom schema. - -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 - diff --git a/schema/README.md b/schema/README.md new file mode 100644 index 000000000000..f32038ed82c8 --- /dev/null +++ b/schema/README.md @@ -0,0 +1,47 @@ +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. + +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 +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 +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 +add another attribute like this: + + + + + + + + + +Currently only the features that are actually exported in the unit tests have +been added to the schema; there is still some work to do here to add +everything; the crashtesting script also does ODF validation of all files and +now also uses the custom schema. + +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 + diff --git a/scp2/README b/scp2/README deleted file mode 100644 index 8f9d58356093..000000000000 --- a/scp2/README +++ /dev/null @@ -1,6 +0,0 @@ -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 -to build the installation. diff --git a/scp2/README.md b/scp2/README.md new file mode 100644 index 000000000000..8f9d58356093 --- /dev/null +++ b/scp2/README.md @@ -0,0 +1,6 @@ +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 +to build the installation. diff --git a/scripting/README b/scripting/README deleted file mode 100644 index 3a019e27d254..000000000000 --- a/scripting/README +++ /dev/null @@ -1,68 +0,0 @@ -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/] - -This module uses astyle to keep consistent java coding style. Please run - -./Format_java_code.sh - -before committing. - -== Source Code Structure == - -The following directories contain the source code currently used -by the Scripting Framework: - -- 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 -browsing and executing scripts. - -- source/protocolhandler - -C++ for a ProtocolHandler implementation that handles vnd.sun.star.script -URIs and dispatches them for execution to the Scripting Framework. - -- source/basprov - -C++ implementation of the LanguageScriptProvider UNO service for Basic - -- source/dlgprov - -C++ implementation of the DialogProvider UNO service used for loading -UNO dialogs from various languages - -- source/pyprov - -LanguageScriptProvider for Python - -- java/com/sun/star/script/framework/provider - -Implementation of an abstract base class ScriptProvider which provides -core methods for implementing Java based LanguageScriptProvider implementations - -- java/com/sun/star/script/framework/provider/* - -BeanShell, JavaScript and Java LanguageScriptProvider implementations - -- java/com/sun/star/script/framework/browse/* - -BrowseNode implementations for the Java based LanguageScriptProviders - -- java/com/sun/star/script/framework/io -- java/com/sun/star/script/framework/container - -Classes for performing script IO - -- examples - -Example scripts in BeanShell, JavaScript, Java and Python - - -== Deprecated Code == - -- java/org/openoffice/* - -Support for developing scripts in IDEs such as NetBeans. diff --git a/scripting/README.md b/scripting/README.md new file mode 100644 index 000000000000..3a019e27d254 --- /dev/null +++ b/scripting/README.md @@ -0,0 +1,68 @@ +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/] + +This module uses astyle to keep consistent java coding style. Please run + +./Format_java_code.sh + +before committing. + +== Source Code Structure == + +The following directories contain the source code currently used +by the Scripting Framework: + +- 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 +browsing and executing scripts. + +- source/protocolhandler + +C++ for a ProtocolHandler implementation that handles vnd.sun.star.script +URIs and dispatches them for execution to the Scripting Framework. + +- source/basprov + +C++ implementation of the LanguageScriptProvider UNO service for Basic + +- source/dlgprov + +C++ implementation of the DialogProvider UNO service used for loading +UNO dialogs from various languages + +- source/pyprov + +LanguageScriptProvider for Python + +- java/com/sun/star/script/framework/provider + +Implementation of an abstract base class ScriptProvider which provides +core methods for implementing Java based LanguageScriptProvider implementations + +- java/com/sun/star/script/framework/provider/* + +BeanShell, JavaScript and Java LanguageScriptProvider implementations + +- java/com/sun/star/script/framework/browse/* + +BrowseNode implementations for the Java based LanguageScriptProviders + +- java/com/sun/star/script/framework/io +- java/com/sun/star/script/framework/container + +Classes for performing script IO + +- examples + +Example scripts in BeanShell, JavaScript, Java and Python + + +== Deprecated Code == + +- java/org/openoffice/* + +Support for developing scripts in IDEs such as NetBeans. diff --git a/sd/README b/sd/README deleted file mode 100644 index c250d81e7c6c..000000000000 --- a/sd/README +++ /dev/null @@ -1,43 +0,0 @@ -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. - -the slideshow UI lives here as well, the slideshow engine is in -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: - - * 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) - - * 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 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. - -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 -output, we don't write text style for indentation levels now, need to -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) -were shape placeholders and text style inheritance. diff --git a/sd/README.md b/sd/README.md new file mode 100644 index 000000000000..c250d81e7c6c --- /dev/null +++ b/sd/README.md @@ -0,0 +1,43 @@ +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. + +the slideshow UI lives here as well, the slideshow engine is in +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: + + * 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) + + * 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 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. + +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 +output, we don't write text style for indentation levels now, need to +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) +were shape placeholders and text style inheritance. diff --git a/sdext/README b/sdext/README deleted file mode 100644 index 63bfd6d0a793..000000000000 --- a/sdext/README +++ /dev/null @@ -1,30 +0,0 @@ -Extensions for the Impress and Draw applications. - -source/pdfimport/ - PDF import - - Uses an external poppler process to parse and handle PDF - import as draw shapes. - -source/minimizer/ - Presentation Minimizer - - Shrinks presentations by down-scaling images, and removing - extraneous eg. embedded OLE content. - -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. - - 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. diff --git a/sdext/README.md b/sdext/README.md new file mode 100644 index 000000000000..63bfd6d0a793 --- /dev/null +++ b/sdext/README.md @@ -0,0 +1,30 @@ +Extensions for the Impress and Draw applications. + +source/pdfimport/ - PDF import + + Uses an external poppler process to parse and handle PDF + import as draw shapes. + +source/minimizer/ - Presentation Minimizer + + Shrinks presentations by down-scaling images, and removing + extraneous eg. embedded OLE content. + +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. + + 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. diff --git a/sfx2/README b/sfx2/README deleted file mode 100644 index 9726870a6019..000000000000 --- a/sfx2/README +++ /dev/null @@ -1,28 +0,0 @@ -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 -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/ -subdirectory. - -Documentation about SFX dispatch, SDI etc.: -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. - -[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. - -Notable files: -sfx2/source/dialog/backingwindow.cxx Startcenter buttons and the corresponding event handler. diff --git a/sfx2/README.md b/sfx2/README.md new file mode 100644 index 000000000000..9726870a6019 --- /dev/null +++ b/sfx2/README.md @@ -0,0 +1,28 @@ +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 +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/ +subdirectory. + +Documentation about SFX dispatch, SDI etc.: +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. + +[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. + +Notable files: +sfx2/source/dialog/backingwindow.cxx Startcenter buttons and the corresponding event handler. diff --git a/shell/README b/shell/README deleted file mode 100644 index b8e821a66ae1..000000000000 --- a/shell/README +++ /dev/null @@ -1 +0,0 @@ -System helpers - launching URI, system integration, external mailer support etc. diff --git a/shell/README.md b/shell/README.md new file mode 100644 index 000000000000..b8e821a66ae1 --- /dev/null +++ b/shell/README.md @@ -0,0 +1 @@ +System helpers - launching URI, system integration, external mailer support etc. diff --git a/slideshow/README b/slideshow/README deleted file mode 100644 index e67379f43c89..000000000000 --- a/slideshow/README +++ /dev/null @@ -1,43 +0,0 @@ -The Impress slideshow engine - -== 3D transitions == - -The 3D transitions are slideshow transition engine using OpenGL and -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 are simulated by external 2d physics engine -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. - -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 -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. - -If there are multiple physics animations in parallel only one of them -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. -To achieve convincing results these updates are performed by setting -the box2d body's linear velocity or angular velocity instead of -setting directly it's position or rotation. diff --git a/slideshow/README.md b/slideshow/README.md new file mode 100644 index 000000000000..e67379f43c89 --- /dev/null +++ b/slideshow/README.md @@ -0,0 +1,43 @@ +The Impress slideshow engine + +== 3D transitions == + +The 3D transitions are slideshow transition engine using OpenGL and +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 are simulated by external 2d physics engine +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. + +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 +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. + +If there are multiple physics animations in parallel only one of them +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. +To achieve convincing results these updates are performed by setting +the box2d body's linear velocity or angular velocity instead of +setting directly it's position or rotation. diff --git a/smoketest/README b/smoketest/README deleted file mode 100644 index 30dceb678ff0..000000000000 --- a/smoketest/README +++ /dev/null @@ -1,18 +0,0 @@ -Smoke test for each component of LibreOffice. - -* smoketest: - - 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/ -directory. This in turn contains a set of macros in -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 -suitable report in the form of a table. - - The StarBasic smoketests also log their output, this ends up -in instdir/user/temp/smoketest.log. diff --git a/smoketest/README.md b/smoketest/README.md new file mode 100644 index 000000000000..30dceb678ff0 --- /dev/null +++ b/smoketest/README.md @@ -0,0 +1,18 @@ +Smoke test for each component of LibreOffice. + +* smoketest: + + 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/ +directory. This in turn contains a set of macros in +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 +suitable report in the form of a table. + + The StarBasic smoketests also log their output, this ends up +in instdir/user/temp/smoketest.log. diff --git a/solenv/README b/solenv/README deleted file mode 100644 index 68e58e8bc774..000000000000 --- a/solenv/README +++ /dev/null @@ -1,34 +0,0 @@ -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: - - 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/ - implementation of the LibreOffice build system - See gbuild/README for more info. - -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 - trying to entirely rid ourselves of this - -src/ - useful standard / re-usable component map files for components - which shouldn't export anything more than a few registration - symbols. diff --git a/solenv/README.md b/solenv/README.md new file mode 100644 index 000000000000..68e58e8bc774 --- /dev/null +++ b/solenv/README.md @@ -0,0 +1,34 @@ +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: + + 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/ + implementation of the LibreOffice build system + See gbuild/README for more info. + +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 + trying to entirely rid ourselves of this + +src/ + useful standard / re-usable component map files for components + which shouldn't export anything more than a few registration + symbols. diff --git a/sot/README b/sot/README deleted file mode 100644 index 2abadba76756..000000000000 --- a/sot/README +++ /dev/null @@ -1 +0,0 @@ -Compound file storage tools code. diff --git a/sot/README.md b/sot/README.md new file mode 100644 index 000000000000..2abadba76756 --- /dev/null +++ b/sot/README.md @@ -0,0 +1 @@ +Compound file storage tools code. diff --git a/starmath/README b/starmath/README deleted file mode 100644 index d84b3d8e0483..000000000000 --- a/starmath/README +++ /dev/null @@ -1,4 +0,0 @@ -Formula editor code for writer ([[sw]]). - -Good overview from the original developer: -http://www.mail-archive.com/dev@sw.openoffice.org/msg00200.html diff --git a/starmath/README.md b/starmath/README.md new file mode 100644 index 000000000000..d84b3d8e0483 --- /dev/null +++ b/starmath/README.md @@ -0,0 +1,4 @@ +Formula editor code for writer ([[sw]]). + +Good overview from the original developer: +http://www.mail-archive.com/dev@sw.openoffice.org/msg00200.html diff --git a/stoc/README b/stoc/README deleted file mode 100644 index 58f0c6f1a26a..000000000000 --- a/stoc/README +++ /dev/null @@ -1,40 +0,0 @@ -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 -backwards incompatibility. The code causes mental pain, and whenever -you need to touch it you want to run away screaming. One typically ends -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 -that used to be binary but have been mostly changed to XML now) are -represented by a single XRegistry instance each. - -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 -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 -information about the type's ancestors, its methods, etc. Similarly -for information about instantiable services like com.sun.star.baz.Boz. - -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 -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 -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) diff --git a/stoc/README.md b/stoc/README.md new file mode 100644 index 000000000000..58f0c6f1a26a --- /dev/null +++ b/stoc/README.md @@ -0,0 +1,40 @@ +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 +backwards incompatibility. The code causes mental pain, and whenever +you need to touch it you want to run away screaming. One typically ends +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 +that used to be binary but have been mostly changed to XML now) are +represented by a single XRegistry instance each. + +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 +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 +information about the type's ancestors, its methods, etc. Similarly +for information about instantiable services like com.sun.star.baz.Boz. + +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 +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 +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) diff --git a/store/README b/store/README deleted file mode 100644 index 46641014c7b9..000000000000 --- a/store/README +++ /dev/null @@ -1,5 +0,0 @@ -The legacy .rdb format. - -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/store/README.md b/store/README.md new file mode 100644 index 000000000000..46641014c7b9 --- /dev/null +++ b/store/README.md @@ -0,0 +1,5 @@ +The legacy .rdb format. + +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 b/svgio/README deleted file mode 100644 index 722f6c0769b6..000000000000 --- a/svgio/README +++ /dev/null @@ -1 +0,0 @@ -It contains svgio/source/svgreader which is used for "Insert->Picture->From File". diff --git a/svgio/README.md b/svgio/README.md new file mode 100644 index 000000000000..722f6c0769b6 --- /dev/null +++ b/svgio/README.md @@ -0,0 +1 @@ +It contains svgio/source/svgreader which is used for "Insert->Picture->From File". diff --git a/svl/README b/svl/README deleted file mode 100644 index ce257747987b..000000000000 --- a/svl/README +++ /dev/null @@ -1,50 +0,0 @@ -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 -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. - -== Items, Pools and Sets == - -=== 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). - -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. - -=== SfxItemPool === - -Usually there is one item pool per document, with a range of valid WhichIds -that is specific to the type of document. - -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. - -=== 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. - -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, -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 -the actual items. - diff --git a/svl/README.md b/svl/README.md new file mode 100644 index 000000000000..ce257747987b --- /dev/null +++ b/svl/README.md @@ -0,0 +1,50 @@ +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 +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. + +== Items, Pools and Sets == + +=== 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). + +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. + +=== SfxItemPool === + +Usually there is one item pool per document, with a range of valid WhichIds +that is specific to the type of document. + +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. + +=== 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. + +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, +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 +the actual items. + diff --git a/svtools/README b/svtools/README deleted file mode 100644 index dc35c3f38702..000000000000 --- a/svtools/README +++ /dev/null @@ -1 +0,0 @@ -Tools on top of VCL. Common dialogs, file and print dialogs, wizards, vcl filters, lots of helper code. diff --git a/svtools/README.md b/svtools/README.md new file mode 100644 index 000000000000..dc35c3f38702 --- /dev/null +++ b/svtools/README.md @@ -0,0 +1 @@ +Tools on top of VCL. Common dialogs, file and print dialogs, wizards, vcl filters, lots of helper code. diff --git a/svx/README b/svx/README deleted file mode 100644 index 30e946547695..000000000000 --- a/svx/README +++ /dev/null @@ -1,101 +0,0 @@ -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?) - -svdraw -transparent gradient stuff. [seriously? surely much more, too] - -== 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... - -The above is incomplete of course. - -== SdrModel / SdrView == - -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. - - 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 -too): - -SdrPaintView <- SdrSnapView <- SdrMarkView <- SdrEditView <- SdrPolyEditView - ^ - +----------------------------------------------------------------+ - | - SdrGlueEditView <- SdrObjEditView <- SdrExchangeView <- SdrDragView - ^ - +----------------------------------------------------------------+ - | - SdrCreateView <- SdrView - -From SdrView on, it is not flat, but a real hierarchy again. - -== Drawing Layer / SdrObject(s) == - -See drawinglayer/README for general information about drawinglayer. - -Below is the class diagram that comes from -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) diff --git a/svx/README.md b/svx/README.md new file mode 100644 index 000000000000..30e946547695 --- /dev/null +++ b/svx/README.md @@ -0,0 +1,101 @@ +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?) + +svdraw +transparent gradient stuff. [seriously? surely much more, too] + +== 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... + +The above is incomplete of course. + +== SdrModel / SdrView == + +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. + + 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 +too): + +SdrPaintView <- SdrSnapView <- SdrMarkView <- SdrEditView <- SdrPolyEditView + ^ + +----------------------------------------------------------------+ + | + SdrGlueEditView <- SdrObjEditView <- SdrExchangeView <- SdrDragView + ^ + +----------------------------------------------------------------+ + | + SdrCreateView <- SdrView + +From SdrView on, it is not flat, but a real hierarchy again. + +== Drawing Layer / SdrObject(s) == + +See drawinglayer/README for general information about drawinglayer. + +Below is the class diagram that comes from +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) diff --git a/sw/README b/sw/README deleted file mode 100644 index 54feb78fa7d1..000000000000 --- a/sw/README +++ /dev/null @@ -1,211 +0,0 @@ -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 == - * inc: headers available to all source files inside the module - * qa: unit, slow and subsequent tests - * sdi - * source: see below - * uiconfig: user interface configuration - * util: UNO passive registration config - -== Source contents == - * core: Writer core (document model, layout, UNO API implementation) - * filter: Writer internal filters - * ascii: plain text filter - * basflt - * docx: wrapper for the UNO DOCX import filter (in writerfilter) for autotext purposes - * html: HTML filter - * inc: include files for filters - * rtf: thin copy&paste helper around the UNO RTF import filter (in writerfilter) - * writer - * ww8: DOC import, DOC/DOCX/RTF export - * xml: ODF import/export, subclassed from xmloff (where most of the work is done) - * uibase: user interface (those parts that are linked into sw & always loaded) - * ui: user interface (optional parts that are loaded on demand (swui)) - -== 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 - -Writer specific WhichIds are defined in sw/inc/hintids.hxx. - -The details below are mainly about details missing from the Wiki pages. - -=== SwDoc === - -The central class for a document is SwDoc, which represents a document. - -A lot of the functionality is split out into separate Manager classes, -each of which implements some IDocument* interface; there are -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 === - -Basically a (fancy) array of SwNode pointers. There are special subclasses of -SwNode (SwStartNode and SwEndNode) which are used to encode a nested tree -structure into the flat array; the range of nodes from SwStartNode to its -corresponding SwEndNode is sometimes called a "section" (but is not necessarily -what the high-level document model calls a "Section"; that is just one of the -possibilities). - -The SwNodes contains the following top-level sections: - -1. Empty -2. Footnote content -3. Frame / Header / Footer content -4. Deleted Change Tracking content -5. Body content - -=== Undo === - -The Undo/Redo information is stored in a sw::UndoManager member of SwDoc, -which implements the IDocumentUndoRedo interface. -Its members include a SwNodes array containing the document content that -is currently not in the actual document but required for Undo/Redo, and -a stack of SwUndo actions, each of which represents one user-visible -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 === - -The sub-structure of paragraphs is stored in the SwpHintsArray member -SwTextNode::m_pSwpHints. There is a base class SwTextAttr with numerous -subclasses; the SwTextAttr has a start and end index and a SfxPoolItem -to store the actual formatting attribute. - -There are several sub-categories of SwTextAttr: - -- formatting attributes: Character Styles (SwTextCharFormat, RES_TXTATR_CHARFMT) - and Automatic Styles (no special class, RES_TXTATR_AUTOFMT): - these are handled by SwpHintsArray::BuildPortions and MergePortions, - which create non-overlapping portions of formatting attributes. - -- nesting attributes: Hyperlinks (SwTextINetFormat, RES_TXTATR_INETFMT), - Ruby (SwTextRuby, RES_TXTATR_CJK_RUBY) and Meta/MetaField (SwTextMeta, - RES_TXTATR_META/RES_TXTATR_METAFIELD): - these maintain a properly nested tree structure. - The Meta/Metafield are "special" because they have both start/end - and a dummy character at the start. - -- misc. attributes: Reference Marks, ToX Marks - -- attributes without end: Fields, Footnotes, Flys (AS_CHAR) - 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 === - -There are multiple model classes involved for fields: - -- enum SwFieldIds enumerates the different types of fields. -- SwFieldType contains some shared stuff for all fields of a type. - There are many subclasses of SwFieldType, one for each different type - of field. - For most types of fields there is one shared instance of this per type, - which is created in DocumentFieldsManager::InitFieldTypes() - but for some there are more than one, and they are dynamically created, see - DocumentFieldsManager::InsertFieldType(). An example for the latter are - variable fields (SwFieldIds::GetExp/SwFieldIds::SetExp), with one SwFieldType per - variable. -- SwXFieldMaster is the UNO wrapper of a field type. - It is a SwClient registered at the SwFieldType. - Its life-cycle is determined by UNO clients outside of sw; it will get - disposed when the SwFieldType dies. -- SwFormatField is the SfxPoolItem of a field. - The SwFormatField is a SwClient registered at its SwFieldType. - The SwFormatField owns the SwField of the field. -- SwField contains the core logic of a field. - The SwField is owned by the SwFormatField of the field. - There are many subclasses of SwField, one for each different type of field. - Note that there are not many places that can Expand the field to its - correct value, since for example page number fields require a View - with an up to date layout; therefore the correct expansion is cached. -- SwTextField is the text attribute of a field. - It owns the SwFormatField of the field (like all text attributes). -- SwXTextField is the UNO wrapper object of a field. - It is a SwClient registered at the SwFormatField. - Its life-cycle is determined by UNO clients outside of sw; it will get - disposed when the SwFormatField dies. - -=== Lists === - -- SwNumFormat (subclass of SvxNumFormat) determines the formatting of a single - numbering level. - -- SwNumRule (NOT a subclass of SvxNumRule) is a *list style*, containing one - SwNumFormat per list level. - SwNumRule::maTextNodeList is the list of SwTextNode that have this list style - applied. - -- SwNumberTreeNode is a base class that represents an abstract node in a - hierarchical tree of numbered nodes. - -- SwNodeNum is the subclass of SwNumberTreeNode that connects it with an - actual SwTextNode and also with a SwNumRule; - SwTextNode::mpNodeNum points back in the other direction - -- SwList represents a list, which is (mostly) a vector of SwNodeNum trees, - one per SwNodes top-level section (why that?). - -- IDocumentListsAccess, sw::DocumentListsManager owns all SwList instances, - and maintains mappings: - + from list-id to SwList - + from list style name to SwList (the "default" SwList for that list style) - -- IDocumentListItems, sw::DocumentListItemsManager contains a set of all - SwNodeNum instances, ordered by SwNode index - -- the special Outline numbering rule: SwDoc::mpOutlineRule - -- IDocumentOutlineNodes, sw::DocumentOutlineNodesManager maintain - a list (which is actually stored in SwNodes::m_pOutlineNodes) of SwTextNodes - that either have the Outline numrule applied, - or have the RES_PARATR_OUTLINELEVEL item set (note that in the latter case, - the SwTextNode does not have a SwNodeNum and is not associated with the - SwDoc::mpOutlineRule). - -- SwTextNodes and paragraph styles have items/properties: - + RES_PARATR_OUTLINELEVEL/"OutlineLevel" to specify an outline level without - necessarily having the outline SwNumRule assigned - + RES_PARATR_NUMRULE/"NumberingStyleName" the list style to apply; may be - empty "" which means no list style (to override inherited value) - Only SwTextNode has these items: - + RES_PARATR_LIST_ID/"ListId" - determines the SwList to which the node is added - + RES_PARATR_LIST_LEVEL/"NumberingLevel" - the level at which the SwTextNode will appear in the list - + RES_PARATR_LIST_ISRESTART/"ParaIsNumberingRestart" - restart numbering sequence at this SwTextNode - + RES_PARATR_LIST_RESTARTVALUE/"NumberingStartValue" - restart numbering sequence at this SwTextNode with this value - + RES_PARATR_LIST_ISCOUNTED/"NumberingIsNumber" - determines if the node is actually counted in the numbering sequence; - these are different from "phantoms" because there's still a SwTextNode. - -Note that there is no UNO service to represent a list. - -=== Layout === - -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. -- The functionality of flowing of a frame across multiple parents (e.g. pages) - is implemented in SwFlowFrame, which is not an SwFrame subclass. The logical - chain of such frames can be visited using the follow and precede pointers. - ("Leaf" is a term that refers to such a relationship.) -- In case a frame is split into multiple parts, then the first one is called - master, while the others are called follows. diff --git a/sw/README.md b/sw/README.md new file mode 100644 index 000000000000..54feb78fa7d1 --- /dev/null +++ b/sw/README.md @@ -0,0 +1,211 @@ +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 == + * inc: headers available to all source files inside the module + * qa: unit, slow and subsequent tests + * sdi + * source: see below + * uiconfig: user interface configuration + * util: UNO passive registration config + +== Source contents == + * core: Writer core (document model, layout, UNO API implementation) + * filter: Writer internal filters + * ascii: plain text filter + * basflt + * docx: wrapper for the UNO DOCX import filter (in writerfilter) for autotext purposes + * html: HTML filter + * inc: include files for filters + * rtf: thin copy&paste helper around the UNO RTF import filter (in writerfilter) + * writer + * ww8: DOC import, DOC/DOCX/RTF export + * xml: ODF import/export, subclassed from xmloff (where most of the work is done) + * uibase: user interface (those parts that are linked into sw & always loaded) + * ui: user interface (optional parts that are loaded on demand (swui)) + +== 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 + +Writer specific WhichIds are defined in sw/inc/hintids.hxx. + +The details below are mainly about details missing from the Wiki pages. + +=== SwDoc === + +The central class for a document is SwDoc, which represents a document. + +A lot of the functionality is split out into separate Manager classes, +each of which implements some IDocument* interface; there are +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 === + +Basically a (fancy) array of SwNode pointers. There are special subclasses of +SwNode (SwStartNode and SwEndNode) which are used to encode a nested tree +structure into the flat array; the range of nodes from SwStartNode to its +corresponding SwEndNode is sometimes called a "section" (but is not necessarily +what the high-level document model calls a "Section"; that is just one of the +possibilities). + +The SwNodes contains the following top-level sections: + +1. Empty +2. Footnote content +3. Frame / Header / Footer content +4. Deleted Change Tracking content +5. Body content + +=== Undo === + +The Undo/Redo information is stored in a sw::UndoManager member of SwDoc, +which implements the IDocumentUndoRedo interface. +Its members include a SwNodes array containing the document content that +is currently not in the actual document but required for Undo/Redo, and +a stack of SwUndo actions, each of which represents one user-visible +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 === + +The sub-structure of paragraphs is stored in the SwpHintsArray member +SwTextNode::m_pSwpHints. There is a base class SwTextAttr with numerous +subclasses; the SwTextAttr has a start and end index and a SfxPoolItem +to store the actual formatting attribute. + +There are several sub-categories of SwTextAttr: + +- formatting attributes: Character Styles (SwTextCharFormat, RES_TXTATR_CHARFMT) + and Automatic Styles (no special class, RES_TXTATR_AUTOFMT): + these are handled by SwpHintsArray::BuildPortions and MergePortions, + which create non-overlapping portions of formatting attributes. + +- nesting attributes: Hyperlinks (SwTextINetFormat, RES_TXTATR_INETFMT), + Ruby (SwTextRuby, RES_TXTATR_CJK_RUBY) and Meta/MetaField (SwTextMeta, + RES_TXTATR_META/RES_TXTATR_METAFIELD): + these maintain a properly nested tree structure. + The Meta/Metafield are "special" because they have both start/end + and a dummy character at the start. + +- misc. attributes: Reference Marks, ToX Marks + +- attributes without end: Fields, Footnotes, Flys (AS_CHAR) + 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 === + +There are multiple model classes involved for fields: + +- enum SwFieldIds enumerates the different types of fields. +- SwFieldType contains some shared stuff for all fields of a type. + There are many subclasses of SwFieldType, one for each different type + of field. + For most types of fields there is one shared instance of this per type, + which is created in DocumentFieldsManager::InitFieldTypes() + but for some there are more than one, and they are dynamically created, see + DocumentFieldsManager::InsertFieldType(). An example for the latter are + variable fields (SwFieldIds::GetExp/SwFieldIds::SetExp), with one SwFieldType per + variable. +- SwXFieldMaster is the UNO wrapper of a field type. + It is a SwClient registered at the SwFieldType. + Its life-cycle is determined by UNO clients outside of sw; it will get + disposed when the SwFieldType dies. +- SwFormatField is the SfxPoolItem of a field. + The SwFormatField is a SwClient registered at its SwFieldType. + The SwFormatField owns the SwField of the field. +- SwField contains the core logic of a field. + The SwField is owned by the SwFormatField of the field. + There are many subclasses of SwField, one for each different type of field. + Note that there are not many places that can Expand the field to its + correct value, since for example page number fields require a View + with an up to date layout; therefore the correct expansion is cached. +- SwTextField is the text attribute of a field. + It owns the SwFormatField of the field (like all text attributes). +- SwXTextField is the UNO wrapper object of a field. + It is a SwClient registered at the SwFormatField. + Its life-cycle is determined by UNO clients outside of sw; it will get + disposed when the SwFormatField dies. + +=== Lists === + +- SwNumFormat (subclass of SvxNumFormat) determines the formatting of a single + numbering level. + +- SwNumRule (NOT a subclass of SvxNumRule) is a *list style*, containing one + SwNumFormat per list level. + SwNumRule::maTextNodeList is the list of SwTextNode that have this list style + applied. + +- SwNumberTreeNode is a base class that represents an abstract node in a + hierarchical tree of numbered nodes. + +- SwNodeNum is the subclass of SwNumberTreeNode that connects it with an + actual SwTextNode and also with a SwNumRule; + SwTextNode::mpNodeNum points back in the other direction + +- SwList represents a list, which is (mostly) a vector of SwNodeNum trees, + one per SwNodes top-level section (why that?). + +- IDocumentListsAccess, sw::DocumentListsManager owns all SwList instances, + and maintains mappings: + + from list-id to SwList + + from list style name to SwList (the "default" SwList for that list style) + +- IDocumentListItems, sw::DocumentListItemsManager contains a set of all + SwNodeNum instances, ordered by SwNode index + +- the special Outline numbering rule: SwDoc::mpOutlineRule + +- IDocumentOutlineNodes, sw::DocumentOutlineNodesManager maintain + a list (which is actually stored in SwNodes::m_pOutlineNodes) of SwTextNodes + that either have the Outline numrule applied, + or have the RES_PARATR_OUTLINELEVEL item set (note that in the latter case, + the SwTextNode does not have a SwNodeNum and is not associated with the + SwDoc::mpOutlineRule). + +- SwTextNodes and paragraph styles have items/properties: + + RES_PARATR_OUTLINELEVEL/"OutlineLevel" to specify an outline level without + necessarily having the outline SwNumRule assigned + + RES_PARATR_NUMRULE/"NumberingStyleName" the list style to apply; may be + empty "" which means no list style (to override inherited value) + Only SwTextNode has these items: + + RES_PARATR_LIST_ID/"ListId" + determines the SwList to which the node is added + + RES_PARATR_LIST_LEVEL/"NumberingLevel" + the level at which the SwTextNode will appear in the list + + RES_PARATR_LIST_ISRESTART/"ParaIsNumberingRestart" + restart numbering sequence at this SwTextNode + + RES_PARATR_LIST_RESTARTVALUE/"NumberingStartValue" + restart numbering sequence at this SwTextNode with this value + + RES_PARATR_LIST_ISCOUNTED/"NumberingIsNumber" + determines if the node is actually counted in the numbering sequence; + these are different from "phantoms" because there's still a SwTextNode. + +Note that there is no UNO service to represent a list. + +=== Layout === + +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. +- The functionality of flowing of a frame across multiple parents (e.g. pages) + is implemented in SwFlowFrame, which is not an SwFrame subclass. The logical + chain of such frames can be visited using the follow and precede pointers. + ("Leaf" is a term that refers to such a relationship.) +- In case a frame is split into multiple parts, then the first one is called + master, while the others are called follows. diff --git a/swext/README b/swext/README deleted file mode 100644 index 71eaa268cddf..000000000000 --- a/swext/README +++ /dev/null @@ -1 +0,0 @@ -Writer extensions (currently only MediaWiki Extension). diff --git a/swext/README.md b/swext/README.md new file mode 100644 index 000000000000..71eaa268cddf --- /dev/null +++ b/swext/README.md @@ -0,0 +1 @@ +Writer extensions (currently only MediaWiki Extension). diff --git a/sysui/README b/sysui/README deleted file mode 100644 index beedede865db..000000000000 --- a/sysui/README +++ /dev/null @@ -1 +0,0 @@ -.desktop files for various Linux distros, and similar stuff for other OSes diff --git a/sysui/README.md b/sysui/README.md new file mode 100644 index 000000000000..beedede865db --- /dev/null +++ b/sysui/README.md @@ -0,0 +1 @@ +.desktop files for various Linux distros, and similar stuff for other OSes diff --git a/test/README b/test/README deleted file mode 100644 index dc0afd80a8d9..000000000000 --- a/test/README +++ /dev/null @@ -1,4 +0,0 @@ -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. diff --git a/test/README.md b/test/README.md new file mode 100644 index 000000000000..dc0afd80a8d9 --- /dev/null +++ b/test/README.md @@ -0,0 +1,4 @@ +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. diff --git a/testtools/README b/testtools/README deleted file mode 100644 index c71e4c8b607d..000000000000 --- a/testtools/README +++ /dev/null @@ -1,34 +0,0 @@ -Testing tools - -== 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 -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 -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 -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 - -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. - - -== 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 -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/testtools/README.md b/testtools/README.md new file mode 100644 index 000000000000..c71e4c8b607d --- /dev/null +++ b/testtools/README.md @@ -0,0 +1,34 @@ +Testing tools + +== 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 +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 +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 +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 + +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. + + +== 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 +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 b/toolkit/README deleted file mode 100644 index b67f037b08cc..000000000000 --- a/toolkit/README +++ /dev/null @@ -1,11 +0,0 @@ -"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 -might be inspired by it API-wise, perhaps. (If you know differently, feel free -to improve this README 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. diff --git a/toolkit/README.md b/toolkit/README.md new file mode 100644 index 000000000000..b67f037b08cc --- /dev/null +++ b/toolkit/README.md @@ -0,0 +1,11 @@ +"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 +might be inspired by it API-wise, perhaps. (If you know differently, feel free +to improve this README 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. diff --git a/tools/README b/tools/README deleted file mode 100644 index 4b98a7342af5..000000000000 --- a/tools/README +++ /dev/null @@ -1,9 +0,0 @@ -Predates sal - string functions, url manipulation, stream stuff, -polygons, etc. - -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). diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 000000000000..4b98a7342af5 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,9 @@ +Predates sal - string functions, url manipulation, stream stuff, +polygons, etc. + +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). diff --git a/ucb/README b/ucb/README deleted file mode 100644 index c6b153130e9c..000000000000 --- a/ucb/README +++ /dev/null @@ -1,7 +0,0 @@ -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 -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 -is best for what etc. diff --git a/ucb/README.md b/ucb/README.md new file mode 100644 index 000000000000..c6b153130e9c --- /dev/null +++ b/ucb/README.md @@ -0,0 +1,7 @@ +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 +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 +is best for what etc. diff --git a/ucbhelper/README b/ucbhelper/README deleted file mode 100644 index ff3d49b0b8f6..000000000000 --- a/ucbhelper/README +++ /dev/null @@ -1 +0,0 @@ -C++ wrappers to help make using content providers easy. diff --git a/ucbhelper/README.md b/ucbhelper/README.md new file mode 100644 index 000000000000..ff3d49b0b8f6 --- /dev/null +++ b/ucbhelper/README.md @@ -0,0 +1 @@ +C++ wrappers to help make using content providers easy. diff --git a/udkapi/README b/udkapi/README deleted file mode 100644 index 9fb99e8ae013..000000000000 --- a/udkapi/README +++ /dev/null @@ -1,9 +0,0 @@ -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). - -See also: -[[offapi]] diff --git a/udkapi/README.md b/udkapi/README.md new file mode 100644 index 000000000000..9fb99e8ae013 --- /dev/null +++ b/udkapi/README.md @@ -0,0 +1,9 @@ +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). + +See also: +[[offapi]] diff --git a/uitest/README b/uitest/README deleted file mode 100644 index c941673e7927..000000000000 --- a/uitest/README +++ /dev/null @@ -1 +0,0 @@ -The code for the UI testing framework and the UI tests. diff --git a/uitest/README.md b/uitest/README.md new file mode 100644 index 000000000000..c941673e7927 --- /dev/null +++ b/uitest/README.md @@ -0,0 +1 @@ +The code for the UI testing framework and the UI tests. diff --git a/unodevtools/README b/unodevtools/README deleted file mode 100644 index f53328e9a0a3..000000000000 --- a/unodevtools/README +++ /dev/null @@ -1,6 +0,0 @@ -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 diff --git a/unodevtools/README.md b/unodevtools/README.md new file mode 100644 index 000000000000..f53328e9a0a3 --- /dev/null +++ b/unodevtools/README.md @@ -0,0 +1,6 @@ +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 diff --git a/unoidl/README b/unoidl/README deleted file mode 100644 index 9a2f9d263382..000000000000 --- a/unoidl/README +++ /dev/null @@ -1,283 +0,0 @@ -Support for UNOIDL registry formats - -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 -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 -now.) - -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. - -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 == - -The format uses byte-oriented, platform-independent, binary files. Larger -quantities are stored LSB first, without alignment requirements. Offsets are -32 bit, effectively limiting the overall file size to 4GB, but that is not -considered a limitation in practice (and avoids unnecessary bloat compared to -64 bit offsets). - -Annotations can be added for (non-module) entities and certain parts of such -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. -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 -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) - bytes -* 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 -* 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 -itself is at the end of the file): - -* 7 byte magic header "UNOIDL\xFF" -* version byte 0 -* Offset 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" - -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 - -Layout of per-entry payload in a constant group Map: - -* kind byte: -** 0x80 bit: 1 if annotated -** remaining bits: - -*** 0: BOOLEAN -**** followed by value byte, 0 represents false, 1 represents true - -*** 1: BYTE -**** followed by value byte, 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 - -*** 4: LONG -**** followed by UInt32 value, representing values with two's complement - -*** 5: UNSIGNED LONG -**** followed by UInt32 value - -*** 6: HYPER -**** followed by UInt64 value, representing values with two's complement - -*** 7: UNSIGNED HYPER -**** followed by UInt64 value - -*** 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, - LSB first - -* if annotated, followed by: Annotations diff --git a/unoidl/README.md b/unoidl/README.md new file mode 100644 index 000000000000..9a2f9d263382 --- /dev/null +++ b/unoidl/README.md @@ -0,0 +1,283 @@ +Support for UNOIDL registry formats + +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 +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 +now.) + +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. + +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 == + +The format uses byte-oriented, platform-independent, binary files. Larger +quantities are stored LSB first, without alignment requirements. Offsets are +32 bit, effectively limiting the overall file size to 4GB, but that is not +considered a limitation in practice (and avoids unnecessary bloat compared to +64 bit offsets). + +Annotations can be added for (non-module) entities and certain parts of such +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. +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 +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) + bytes +* 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 +* 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 +itself is at the end of the file): + +* 7 byte magic header "UNOIDL\xFF" +* version byte 0 +* Offset 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" + +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 + +Layout of per-entry payload in a constant group Map: + +* kind byte: +** 0x80 bit: 1 if annotated +** remaining bits: + +*** 0: BOOLEAN +**** followed by value byte, 0 represents false, 1 represents true + +*** 1: BYTE +**** followed by value byte, 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 + +*** 4: LONG +**** followed by UInt32 value, representing values with two's complement + +*** 5: UNSIGNED LONG +**** followed by UInt32 value + +*** 6: HYPER +**** followed by UInt64 value, representing values with two's complement + +*** 7: UNSIGNED HYPER +**** followed by UInt64 value + +*** 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, + LSB first + +* if annotated, followed by: Annotations diff --git a/unoil/README b/unoil/README deleted file mode 100644 index 9ccd36d2501a..000000000000 --- a/unoil/README +++ /dev/null @@ -1 +0,0 @@ -As offuh but for Java UNO: Maps IDL into java classes definitions. diff --git a/unoil/README.md b/unoil/README.md new file mode 100644 index 000000000000..9ccd36d2501a --- /dev/null +++ b/unoil/README.md @@ -0,0 +1 @@ +As offuh but for Java UNO: Maps IDL into java classes definitions. diff --git a/unotools/README b/unotools/README deleted file mode 100644 index bac492a83105..000000000000 --- a/unotools/README +++ /dev/null @@ -1 +0,0 @@ -Helpers for C++ use of UNO. diff --git a/unotools/README.md b/unotools/README.md new file mode 100644 index 000000000000..bac492a83105 --- /dev/null +++ b/unotools/README.md @@ -0,0 +1 @@ +Helpers for C++ use of UNO. diff --git a/unoxml/README b/unoxml/README deleted file mode 100644 index 6ca6382fb10c..000000000000 --- a/unoxml/README +++ /dev/null @@ -1 +0,0 @@ -UNO wrappers for XML services. diff --git a/unoxml/README.md b/unoxml/README.md new file mode 100644 index 000000000000..6ca6382fb10c --- /dev/null +++ b/unoxml/README.md @@ -0,0 +1 @@ +UNO wrappers for XML services. diff --git a/ure/README b/ure/README deleted file mode 100644 index 23b15bf863cb..000000000000 --- a/ure/README +++ /dev/null @@ -1,8 +0,0 @@ -Contains the UNO Runtime Environment (URE). - -Beginnings of standalone UNO distribution. - - -You may also want to read the README located at: -[git:ure/source/README] - diff --git a/ure/README.md b/ure/README.md new file mode 100644 index 000000000000..23b15bf863cb --- /dev/null +++ b/ure/README.md @@ -0,0 +1,8 @@ +Contains the UNO Runtime Environment (URE). + +Beginnings of standalone UNO distribution. + + +You may also want to read the README located at: +[git:ure/source/README] + diff --git a/uui/README b/uui/README deleted file mode 100644 index 43a582a44bbc..000000000000 --- a/uui/README +++ /dev/null @@ -1 +0,0 @@ -Contains an Interaction Handler for the [[ucb]] and other uses. Works via VCL. diff --git a/uui/README.md b/uui/README.md new file mode 100644 index 000000000000..43a582a44bbc --- /dev/null +++ b/uui/README.md @@ -0,0 +1 @@ +Contains an Interaction Handler for the [[ucb]] and other uses. Works via VCL. diff --git a/vbahelper/README b/vbahelper/README deleted file mode 100644 index bf569d4cd915..000000000000 --- a/vbahelper/README +++ /dev/null @@ -1 +0,0 @@ -Static helper functions for the VBA filters \ No newline at end of file diff --git a/vbahelper/README.md b/vbahelper/README.md new file mode 100644 index 000000000000..bf569d4cd915 --- /dev/null +++ b/vbahelper/README.md @@ -0,0 +1 @@ +Static helper functions for the VBA filters \ No newline at end of file diff --git a/vcl/README b/vcl/README deleted file mode 100644 index e0944688f2f3..000000000000 --- a/vcl/README +++ /dev/null @@ -1,242 +0,0 @@ -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). - -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/ - + the main cross-platform chunk of source - -inc/ - + cross-platform abstraction headers - -headless/ - + a backend renderer that draws to bitmaps - -android/ - + Android backend - -osx/ - + macOS backend - -ios/ - + iOS backend - -quartz/ - + code common to macOS and iOS - -win/ - + Windows backend - -qt5/ - + Qt5 (under construction) - -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/ - + pluggable framework to select correct unx backend - - 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 - - + InitVCL calls 'CreateSalInstance' - + this is implemented by the compiled-in platform backend - + it stores various bits of global state in the - 'SalData' (inc/saldatabasic.hxx) structure but: - + the SalInstance vtable is the primary outward facing gateway - API for platform backends - + It is a factory for: - SalFrames, SalVirtualDevices, SalPrinters, - Timers, the SolarMutex, Drag&Drop and other - objects, as well as the primary event loop wrapper. - -Note: references to "SV" in the code mean StarView, which was a -portable C++ class library for GUIs, with very old roots, that was -developed by StarDivision. Nowadays it is not used by anything except -LibreOffice (and OpenOffice). - -"svp" stands for "StarView Plugin". - -== 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() - into MTA (free-threaded) - -== 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 -can store a GDIMetafile as XML, which makes debugging much easier -since you can just use "diff" to see changes. - -== EMF+ == - -emf+ is vector file format used by MSO and is successor of wmf and -emf formats. see -http://msdn.microsoft.com/en-us/library/cc230724.aspx for -documentation. note that we didn't have this documentation from -start, so part of the code predates to the time when we had guessed -some parts and can be enhanced today. there also still many thing not -complete - -emf+ is handled a bit differently compared to original emf/wmf files, -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 - -emf+ is encapsulated into GDIMetafile inside comment records and -parsed/rendered later, when it reaches cppcanvas. It is parsed and -rendered in cppcanvas/source/mtfrenderer. also note that there are -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 - -parsing: - - wmf/emf filter --> GDI metafile with emf+ in comments --> cppcanvas metafile renderer - -lately the GDIMetafile rendering path changed which also influenced -emf+ rendering. now many things happen in drawing layer, where -GDIMetafile is translated into drawing layer primitives. for -metafiles with emf+ we let the mtfrenderer render them into bitmap -(with transparency) and use this bitmap in drawinlayer. cleaner -solution for current state would be to extend the drawing layer for -missing features and move parsing into drawing layer (might be quite -a lot of work). intermediary enhancement would be to know better the -needed size/resolution of the bitmap, before we render emf+ into -bitmap in drawing layer. Thorsten is working on the same problem with -svg rendering, so hopefully his approach could be extended for emf+ as -well. the places in drawing layer where we use canvas mtfrenderer to -render into bitmaps can be found when you grep for GetUseCanvas. also -look at vcl/source/gdi/gdimetafile.cxx where you can look for -UseCanvas again. moving the parsing into drawinglayer might also have -nice side effect for emf+-dual metafiles. in case the emf+ records -are broken, it would be easier to use the duplicit emf -rendering. fortunately we didn't run into such a broken emf+ file -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: - - before - - vcl --> cppcanvas metafile renderer --> vcl - - now - - drawing layer --> vcl --> cppcanvas metafile renderer --> vcl --> drawing layer - -another interesting part is actual rendering into canvas bitmap and -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 - -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 - - -== Printing/PDF export == - -Printing from Writer works like this: - -1) individual pages print by passing an appropriate OutputDevice to XRenderable -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* - -Creating the ODF thumbnail for the first page works as above except step 3 is: - -3) the GDIMetaFile is replayed to create the thumbnail - -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 - - -=== Debugging PDF export === - -Debugging the PDF export becomes much easier when -compression is disabled (so the PDF file is directly readable) and -the MARK function puts comments into the PDF file about which method -generated the following PDF content. - -The compression can be disabled even using an env. var: - -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 - -=== 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 -times, and only the last unlock will actually release the mutex. - -UNO methods on components can be called from multiple threads, while the -majority of the codebase is not prepared for multi-threading. One way to get -around this mismatch is to create a SolarMutexGuard instance at the start of -each & every UNO method implementation, but only when it is necessary: - -- Only acquire the SolarMutex if you actually need it (e.g., not in functions - that return static information). - -- Only around the code that actually needs it (i.e., never call out with it - locked). - -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. - -Event listeners are a special (but frequent) case of the "never call out with -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. - -- This can be problematic if later calling out (an event handler is called), - where the called function may be an UNO method implementation as well and - may be invoked on a different thread. - -- So we try to not own the solar mutex, whenever we call out (invoke event - listeners). - -In short, never hold any mutex unless necessary, especially not when calling -out. diff --git a/vcl/README.md b/vcl/README.md new file mode 100644 index 000000000000..e0944688f2f3 --- /dev/null +++ b/vcl/README.md @@ -0,0 +1,242 @@ +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). + +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/ + + the main cross-platform chunk of source + +inc/ + + cross-platform abstraction headers + +headless/ + + a backend renderer that draws to bitmaps + +android/ + + Android backend + +osx/ + + macOS backend + +ios/ + + iOS backend + +quartz/ + + code common to macOS and iOS + +win/ + + Windows backend + +qt5/ + + Qt5 (under construction) + +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/ + + pluggable framework to select correct unx backend + + 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 + + + InitVCL calls 'CreateSalInstance' + + this is implemented by the compiled-in platform backend + + it stores various bits of global state in the + 'SalData' (inc/saldatabasic.hxx) structure but: + + the SalInstance vtable is the primary outward facing gateway + API for platform backends + + It is a factory for: + SalFrames, SalVirtualDevices, SalPrinters, + Timers, the SolarMutex, Drag&Drop and other + objects, as well as the primary event loop wrapper. + +Note: references to "SV" in the code mean StarView, which was a +portable C++ class library for GUIs, with very old roots, that was +developed by StarDivision. Nowadays it is not used by anything except +LibreOffice (and OpenOffice). + +"svp" stands for "StarView Plugin". + +== 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() + into MTA (free-threaded) + +== 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 +can store a GDIMetafile as XML, which makes debugging much easier +since you can just use "diff" to see changes. + +== EMF+ == + +emf+ is vector file format used by MSO and is successor of wmf and +emf formats. see +http://msdn.microsoft.com/en-us/library/cc230724.aspx for +documentation. note that we didn't have this documentation from +start, so part of the code predates to the time when we had guessed +some parts and can be enhanced today. there also still many thing not +complete + +emf+ is handled a bit differently compared to original emf/wmf files, +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 + +emf+ is encapsulated into GDIMetafile inside comment records and +parsed/rendered later, when it reaches cppcanvas. It is parsed and +rendered in cppcanvas/source/mtfrenderer. also note that there are +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 + +parsing: + + wmf/emf filter --> GDI metafile with emf+ in comments --> cppcanvas metafile renderer + +lately the GDIMetafile rendering path changed which also influenced +emf+ rendering. now many things happen in drawing layer, where +GDIMetafile is translated into drawing layer primitives. for +metafiles with emf+ we let the mtfrenderer render them into bitmap +(with transparency) and use this bitmap in drawinlayer. cleaner +solution for current state would be to extend the drawing layer for +missing features and move parsing into drawing layer (might be quite +a lot of work). intermediary enhancement would be to know better the +needed size/resolution of the bitmap, before we render emf+ into +bitmap in drawing layer. Thorsten is working on the same problem with +svg rendering, so hopefully his approach could be extended for emf+ as +well. the places in drawing layer where we use canvas mtfrenderer to +render into bitmaps can be found when you grep for GetUseCanvas. also +look at vcl/source/gdi/gdimetafile.cxx where you can look for +UseCanvas again. moving the parsing into drawinglayer might also have +nice side effect for emf+-dual metafiles. in case the emf+ records +are broken, it would be easier to use the duplicit emf +rendering. fortunately we didn't run into such a broken emf+ file +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: + + before + + vcl --> cppcanvas metafile renderer --> vcl + + now + + drawing layer --> vcl --> cppcanvas metafile renderer --> vcl --> drawing layer + +another interesting part is actual rendering into canvas bitmap and +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 + +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 + + +== Printing/PDF export == + +Printing from Writer works like this: + +1) individual pages print by passing an appropriate OutputDevice to XRenderable +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* + +Creating the ODF thumbnail for the first page works as above except step 3 is: + +3) the GDIMetaFile is replayed to create the thumbnail + +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 + + +=== Debugging PDF export === + +Debugging the PDF export becomes much easier when +compression is disabled (so the PDF file is directly readable) and +the MARK function puts comments into the PDF file about which method +generated the following PDF content. + +The compression can be disabled even using an env. var: + +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 + +=== 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 +times, and only the last unlock will actually release the mutex. + +UNO methods on components can be called from multiple threads, while the +majority of the codebase is not prepared for multi-threading. One way to get +around this mismatch is to create a SolarMutexGuard instance at the start of +each & every UNO method implementation, but only when it is necessary: + +- Only acquire the SolarMutex if you actually need it (e.g., not in functions + that return static information). + +- Only around the code that actually needs it (i.e., never call out with it + locked). + +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. + +Event listeners are a special (but frequent) case of the "never call out with +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. + +- This can be problematic if later calling out (an event handler is called), + where the called function may be an UNO method implementation as well and + may be invoked on a different thread. + +- So we try to not own the solar mutex, whenever we call out (invoke event + listeners). + +In short, never hold any mutex unless necessary, especially not when calling +out. diff --git a/winaccessibility/README b/winaccessibility/README deleted file mode 100644 index 2f507beacc64..000000000000 --- a/winaccessibility/README +++ /dev/null @@ -1,61 +0,0 @@ -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 -Accessible Technologies (ATs) such as the NVDA screen reader. - -The code breaks into three bits: - -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 - to provide native peers for the accessibility code. - -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/ - -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 -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 -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 -not by actual end users. - -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 - -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... - diff --git a/winaccessibility/README.md b/winaccessibility/README.md new file mode 100644 index 000000000000..2f507beacc64 --- /dev/null +++ b/winaccessibility/README.md @@ -0,0 +1,61 @@ +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 +Accessible Technologies (ATs) such as the NVDA screen reader. + +The code breaks into three bits: + +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 + to provide native peers for the accessibility code. + +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/ + +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 +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 +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 +not by actual end users. + +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 + +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... + diff --git a/wizards/README b/wizards/README deleted file mode 100644 index 332c53507af0..000000000000 --- a/wizards/README +++ /dev/null @@ -1,4 +0,0 @@ -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 diff --git a/wizards/README.md b/wizards/README.md new file mode 100644 index 000000000000..332c53507af0 --- /dev/null +++ b/wizards/README.md @@ -0,0 +1,4 @@ +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 diff --git a/writerfilter/README b/writerfilter/README deleted file mode 100644 index 7a9c8cc57df4..000000000000 --- a/writerfilter/README +++ /dev/null @@ -1,20 +0,0 @@ -The writerfilter module contains import filters for Writer, using its UNO API. - -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 - -== 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 diff --git a/writerfilter/README.md b/writerfilter/README.md new file mode 100644 index 000000000000..7a9c8cc57df4 --- /dev/null +++ b/writerfilter/README.md @@ -0,0 +1,20 @@ +The writerfilter module contains import filters for Writer, using its UNO API. + +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 + +== 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 diff --git a/writerperfect/README b/writerperfect/README deleted file mode 100644 index 9edcb4011ec0..000000000000 --- a/writerperfect/README +++ /dev/null @@ -1,6 +0,0 @@ -WordPerfect and other filters, 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" -because the libraries they use all have the same "style" of API and are -developed, at least partially, by the same person or group of persons. diff --git a/writerperfect/README.md b/writerperfect/README.md new file mode 100644 index 000000000000..9edcb4011ec0 --- /dev/null +++ b/writerperfect/README.md @@ -0,0 +1,6 @@ +WordPerfect and other filters, 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" +because the libraries they use all have the same "style" of API and are +developed, at least partially, by the same person or group of persons. diff --git a/xmerge/README b/xmerge/README deleted file mode 100644 index d45f6c4e0411..000000000000 --- a/xmerge/README +++ /dev/null @@ -1,6 +0,0 @@ -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/] diff --git a/xmerge/README.md b/xmerge/README.md new file mode 100644 index 000000000000..d45f6c4e0411 --- /dev/null +++ b/xmerge/README.md @@ -0,0 +1,6 @@ +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/] diff --git a/xmlhelp/README b/xmlhelp/README deleted file mode 100644 index 3e54ddc51bb2..000000000000 --- a/xmlhelp/README +++ /dev/null @@ -1 +0,0 @@ -Help reader and viewer for online help. \ No newline at end of file diff --git a/xmlhelp/README.md b/xmlhelp/README.md new file mode 100644 index 000000000000..3e54ddc51bb2 --- /dev/null +++ b/xmlhelp/README.md @@ -0,0 +1 @@ +Help reader and viewer for online help. \ No newline at end of file diff --git a/xmlreader/README b/xmlreader/README deleted file mode 100644 index 0c6bae91bd1d..000000000000 --- a/xmlreader/README +++ /dev/null @@ -1,6 +0,0 @@ -fast/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 -services.rdb files). It supports a subset of XML features, but is fast -and small. diff --git a/xmlreader/README.md b/xmlreader/README.md new file mode 100644 index 000000000000..0c6bae91bd1d --- /dev/null +++ b/xmlreader/README.md @@ -0,0 +1,6 @@ +fast/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 +services.rdb files). It supports a subset of XML features, but is fast +and small. diff --git a/xmlscript/README b/xmlscript/README deleted file mode 100644 index 84cfec6e7fde..000000000000 --- a/xmlscript/README +++ /dev/null @@ -1,6 +0,0 @@ -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 diff --git a/xmlscript/README.md b/xmlscript/README.md new file mode 100644 index 000000000000..84cfec6e7fde --- /dev/null +++ b/xmlscript/README.md @@ -0,0 +1,6 @@ +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 diff --git a/xmlsecurity/README b/xmlsecurity/README deleted file mode 100644 index 52a479009403..000000000000 --- a/xmlsecurity/README +++ /dev/null @@ -1,4 +0,0 @@ -Stuff for document signing. - -This code provides dialogs, and infrastructure wrapping libxmlsec and gpgme that -implements document signing. diff --git a/xmlsecurity/README.md b/xmlsecurity/README.md new file mode 100644 index 000000000000..52a479009403 --- /dev/null +++ b/xmlsecurity/README.md @@ -0,0 +1,4 @@ +Stuff for document signing. + +This code provides dialogs, and infrastructure wrapping libxmlsec and gpgme that +implements document signing. -- cgit