configure: Improve help-options handling

This patch includes:

* A README.help.md as a general documentation for the different
  help types, the LO code and help-related build options.
* Adds --disable-xmlhelp for removing the xmlhelp support from the
  build. Disable for iOS, Android and Emscripten. This was partly
  included in HAVE_FEATURE_DESKTOP before.
* Rename WITH_HELP define to WITH_HELPPACKS, which reflects the
  actual usage AFAIK.
* Depend --with-omindex on --with-help=online and don't override
  the --with-help setting. Error out on conflicting options.
* Depend --with-helppack-integration on build help variants, which
  actually result in help packs.

Kind of reverts commit 2c38ea6d16
("Building without --with-help is not supposed to disable help
functionality").

Change-Id: Ie4cb73905b3ed94e991d9f1bd75cfbd6de9da385
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/116222
Tested-by: Jenkins
Reviewed-by: Jan-Marek Glogowski <glogow@fbihome.de>
This commit is contained in:
Jan-Marek Glogowski 2021-05-24 14:12:18 +02:00
parent 75c42c1f3b
commit 14069d8417
24 changed files with 223 additions and 112 deletions

59
README.help.md Normal file
View file

@ -0,0 +1,59 @@
# LibreOffice help build
LibreOffice can build three kinds of help output from helpcontent2:
* XML (local, bundeled with LibreOffice < 6.0)
* HTML (local, bundeled with LibreOffice >= 6.0)
* HTML (online)
Both local help variants can be included in help-packs, which might be bundeled
with the installer or provided as separate packages. They are supposed to be
installed by a user to provide localized help. Both HTML-based help types are
displayed in a browser, while the XML help uses an internal viewer component.
The XML help is the only one supported in extensions.
## configure options
--with-help: selects the help type to build
--with-omindex: prepares the online help for a Xapian Omega based search index
--disable-xmlhelp: removes support for the XML help
--with-helppack-integration: includes the help-packs in the installer
Also see `configure --help`.
## XML help, bundeled
This type was bundeled per-default until LibreOffice 6.0.
This help output is generated by using two tools: HelpIndexer and HelpLinker.
It uses an internal viewer component. Extensions still use this help type to
ship their help. This output is originally based on JavaDoc.
The main support for this help type is in the following directories:
* helpcompiler: tooling and support library
* xmlhelp: the viewer component
* desktop/source/deployment/registry/help: extensions / help-pack support
Most code is "marked" by HAVE_FEATURE_XMLHELP precompiler blocks or conditioned
by the XMLHELP flag in the $BUILD_TYPE variable.
Interestingly the HelpIndexer and HelpLinker are used by gbuild to build the
help inside bundeled extensions, but both are not part of the LibreOffice SDK.
## HTML help, bundeled
This type is bundeled per-default since LibreOffice 6.0 and displayed in a
browser.
## HTML help, online
This help is the external one, currently provided by help.libreoffice.org. It
differs from the bundeled HTML help in three main aspects:
* has a language chooser widget
* provides an additional Xapian Omega, CGI- / server-based search index
* includes some additional multimedia assets
It is opened in a browser.

View file

@ -18,8 +18,10 @@
#
$(eval $(call gb_Helper_register_executables,NONE, \
$(call gb_Helper_optional,HELPTOOLS, \
HelpIndexer \
HelpLinker \
) \
bestreversemap \
canvasdemo \
cfgex \
@ -368,7 +370,7 @@ $(eval $(call gb_Helper_register_libraries_for_install,OOOLIBS,ooo, \
fwk \
$(if $(filter WNT,$(OS)),gdipluscanvas) \
guesslang \
$(if $(filter DESKTOP,$(BUILD_TYPE)),helplinker) \
$(call gb_Helper_optionals_or,HELPTOOLS XMLHELP,helplinker) \
i18npool \
i18nsearch \
hyphen \
@ -622,7 +624,7 @@ $(eval $(call gb_Helper_register_libraries_for_install,PLAINLIBS_OOO,ooo, \
$(if $(WITH_WEBDAV),ucpdav1) \
ucpfile1 \
ucpftp1 \
ucpchelp1 \
$(call gb_Helper_optional,XMLHELP,ucpchelp1) \
ucphier1 \
ucppkg1 \
unopkgapp \
@ -914,7 +916,7 @@ $(eval $(call gb_Helper_register_packages_for_install,ooo,\
$(if $(filter $(OS),MACOSX),vcl_osxres) \
xmloff_dtd \
xmlscript_dtd \
xmlhelp_helpxsl \
$(call gb_Helper_optional,XMLHELP,xmlhelp_helpxsl) \
$(if $(ENABLE_JAVA),\
scripting_java \
scripting_java_jars \

View file

@ -87,10 +87,8 @@ $(eval $(call gb_Module_add_moduledirs,cross_toolset,\
xmloff \
xmlscript \
) \
$(call gb_Helper_optional_for_host,DESKTOP, \
helpcompiler \
xmlhelp \
) \
$(call gb_Helper_optionals_or,HELPTOOLS XMLHELP,helpcompiler) \
$(call gb_Helper_optional,XMLHELP,xmlhelp) \
$(call gb_Helper_optional,QADEVOOO,qadevOOo) \
))

View file

@ -60,7 +60,7 @@ $(eval $(call gb_Module_add_moduledirs,libreoffice,\
formula \
$(call gb_Helper_optional,DESKTOP,fpicker) \
framework \
$(call gb_Helper_optional,DESKTOP,helpcompiler) \
$(call gb_Helper_optionals_or,HELPTOOLS XMLHELP,helpcompiler) \
$(call gb_Helper_optional,HELP,helpcontent2) \
hwpfilter \
i18nlangtag \
@ -153,7 +153,7 @@ $(eval $(call gb_Module_add_moduledirs,libreoffice,\
writerfilter \
writerperfect \
xmerge \
$(call gb_Helper_optional,DESKTOP,xmlhelp) \
$(call gb_Helper_optional,XMLHELP,xmlhelp) \
xmloff \
xmlreader \
xmlscript \

View file

@ -145,4 +145,11 @@
*/
#define HAVE_FEATURE_COMMUNITY_FLAVOR 0
/* XMLHELP - whether we include the XML help mechanisms
*
* Can be turned off with --without-xmlhelp
*/
#define HAVE_FEATURE_XMLHELP 0
#endif

View file

@ -981,6 +981,7 @@ ios*) # iOS
enable_coinmp=no
enable_lpsolve=no
enable_extension_integration=no
enable_xmlhelp=no
with_ppds=no
if test "$enable_ios_simulator" = "yes"; then
host=x86_64-apple-darwin
@ -1080,6 +1081,7 @@ linux-android*)
enable_lpsolve=no
enable_odk=no
enable_python=no
enable_xmlhelp=no
_os=Android
AC_DEFINE(HAVE_FT_FACE_GETCHARVARIANTINDEX)
@ -1108,6 +1110,7 @@ emscripten)
test_webdav=no
enable_database_connectivity=no
enable_lpsolve=no
enable_xmlhelp=no
with_system_zlib=no
with_theme="breeze"
_os=Emscripten
@ -1941,6 +1944,11 @@ AC_ARG_ENABLE(wasm-strip,
[Strip the static build like for WASM/emscripten platform.]),
,enable_wasm_strip=yes)
AC_ARG_ENABLE(xmlhelp,
AS_HELP_STRING([--disable-xmlhelp],
[Disable XML help support]),
,enable_xmlhelp=yes)
dnl ===================================================================
dnl Optional Packages (--with/without-)
@ -2977,6 +2985,9 @@ fi
if test "$enable_extensions" = yes; then
BUILD_TYPE="$BUILD_TYPE EXTENSIONS"
AC_DEFINE(HAVE_FEATURE_EXTENSIONS)
else
enable_extension_integration=no
enable_extension_update=no
fi
if test -z "$enable_scripting"; then
@ -5295,6 +5306,97 @@ else
fi
AC_SUBST(PKGFORMAT)
dnl ===================================================================
dnl handle help related options
dnl
dnl If you change help related options, please update README.help
dnl ===================================================================
ENABLE_HTMLHELP=
HELP_OMINDEX_PAGE=
HELP_ONLINE=
WITH_HELPPACKS=
AC_MSG_CHECKING([which help to build])
if test -n "$with_help" -a "$with_help" != "no"; then
GIT_NEEDED_SUBMODULES="helpcontent2 $GIT_NEEDED_SUBMODULES"
BUILD_TYPE="$BUILD_TYPE HELP"
case "$with_help" in
"html")
ENABLE_HTMLHELP=TRUE
WITH_HELPPACKS=TRUE
SCPDEFS="$SCPDEFS -DWITH_HELPPACKS"
AC_MSG_RESULT([HTML (local)])
;;
"online")
ENABLE_HTMLHELP=TRUE
HELP_ONLINE=TRUE
AC_MSG_RESULT([HTML (online)])
;;
yes)
WITH_HELPPACKS=TRUE
SCPDEFS="$SCPDEFS -DWITH_HELPPACKS"
AC_MSG_RESULT([XML (local)])
;;
*)
AC_MSG_ERROR([Unknown --with-help=$with_help])
;;
esac
else
AC_MSG_RESULT([no])
fi
if test "$with_help" = yes -o "$enable_extension_integration" != no; then
BUILD_TYPE="$BUILD_TYPE HELPTOOLS"
fi
AC_MSG_CHECKING([whether to enable xapian-omega support for online help])
if test -n "$with_omindex" -a "$with_omindex" != "no"; then
if test "$HELP_ONLINE" != TRUE; then
AC_MSG_ERROR([Can't build xapian-omega index without --help=online])
fi
case "$with_omindex" in
"server")
HELP_OMINDEX_PAGE=TRUE
AC_MSG_RESULT([SERVER])
;;
"noxap")
AC_MSG_RESULT([NOXAP])
;;
*)
AC_MSG_ERROR([Unknown --with-omindex=$with_omindex])
;;
esac
else
AC_MSG_RESULT([no])
fi
AC_MSG_CHECKING([whether to include the XML-help support])
if test "$enable_xmlhelp" = yes; then
BUILD_TYPE="$BUILD_TYPE XMLHELP"
AC_DEFINE(HAVE_FEATURE_XMLHELP)
AC_MSG_RESULT([yes])
else
if test "$with_help" = yes; then
add_warning "Building the XML help, but LO with disabled xmlhelp support. Generated help can't be accesssed from this LO build!"
fi
AC_MSG_RESULT([no])
fi
dnl Test whether to integrate helppacks into the product's installer
AC_MSG_CHECKING([for helppack integration])
if test -z "$WITH_HELPPACKS" -o "$with_helppack_integration" = no; then
AC_MSG_RESULT([no integration])
else
SCPDEFS="$SCPDEFS -DWITH_HELPPACK_INTEGRATION"
AC_MSG_RESULT([integration])
fi
AC_SUBST([ENABLE_HTMLHELP])
AC_SUBST([HELP_OMINDEX_PAGE])
AC_SUBST([HELP_ONLINE])
# WITH_HELPPACKS is used only in configure
dnl ===================================================================
dnl Set up a different compiler to produce tools to run on the build
dnl machine when doing cross-compilation
@ -5381,6 +5483,7 @@ if test "$cross_compiling" = "yes"; then
--build="$build_alias" \
--disable-cairo-canvas \
--disable-cups \
--disable-extensions \
--disable-firebird-sdbc \
--disable-gpgmepp \
--disable-gstreamer-1-0 \
@ -5712,65 +5815,6 @@ else
fi
AC_SUBST(DO_FETCH_TARBALLS)
AC_MSG_CHECKING([whether to build help])
if test -n "$with_help" -a "$with_help" != "no" -a $_os != iOS -a $_os != Android; then
BUILD_TYPE="$BUILD_TYPE HELP"
GIT_NEEDED_SUBMODULES="helpcontent2 $GIT_NEEDED_SUBMODULES"
case "$with_help" in
"html")
ENABLE_HTMLHELP=TRUE
SCPDEFS="$SCPDEFS -DWITH_HELP"
AC_MSG_RESULT([HTML])
;;
"online")
ENABLE_HTMLHELP=TRUE
HELP_ONLINE=TRUE
AC_MSG_RESULT([HTML])
;;
yes)
SCPDEFS="$SCPDEFS -DWITH_HELP"
AC_MSG_RESULT([yes])
;;
*)
AC_MSG_ERROR([Unknown --with-help=$with_help])
;;
esac
else
AC_MSG_RESULT([no])
fi
AC_SUBST([ENABLE_HTMLHELP])
AC_SUBST([HELP_ONLINE])
AC_MSG_CHECKING([whether to enable xapian-omega support for help])
if test -n "$with_omindex" -a "$with_omindex" != "no" -a $_os != iOS -a $_os != Android; then
BUILD_TYPE="$BUILD_TYPE HELP"
GIT_NEEDED_SUBMODULES="helpcontent2 $GIT_NEEDED_SUBMODULES"
case "$with_omindex" in
"server")
ENABLE_HTMLHELP=TRUE
HELP_ONLINE=TRUE
HELP_OMINDEX_PAGE=TRUE
AC_MSG_RESULT([SERVER])
;;
"noxap")
ENABLE_HTMLHELP=TRUE
HELP_ONLINE=TRUE
HELP_OMINDEX_PAGE=FALSE
AC_MSG_RESULT([NOXAP])
;;
*)
AC_MSG_ERROR([Unknown --with-omindex=$with_omindex])
;;
esac
else
HELP_OMINDEX_PAGE=FALSE
AC_MSG_RESULT([no])
fi
AC_SUBST([ENABLE_HTMLHELP])
AC_SUBST([HELP_OMINDEX_PAGE])
AC_SUBST([HELP_ONLINE])
dnl Test whether to include MySpell dictionaries
dnl ===================================================================
AC_MSG_CHECKING([whether to include MySpell dictionaries])
@ -9184,6 +9228,7 @@ dnl ===================================================================
dnl we should rather be using
dnl libo_CHECK_SYSTEM_MODULE([clucence],[CLUCENE],[liblucence-core]) here
dnl but the contribs-lib check seems tricky
if test "$enable_xmlhelp" = yes -o "$enable_extension_integration" = yes; then
AC_MSG_CHECKING([which clucene to use])
if test "$with_system_clucene" = "yes"; then
AC_MSG_RESULT([external])
@ -9211,6 +9256,7 @@ else
SYSTEM_CLUCENE=
BUILD_TYPE="$BUILD_TYPE CLUCENE"
fi
fi
AC_SUBST(SYSTEM_CLUCENE)
AC_SUBST(CLUCENE_CFLAGS)
AC_SUBST(CLUCENE_LIBS)
@ -12874,17 +12920,6 @@ for theme in $with_theme; do
esac
done
dnl ===================================================================
dnl Test whether to integrate helppacks into the product's installer
dnl ===================================================================
AC_MSG_CHECKING([for helppack integration])
if test "$with_helppack_integration" = "no"; then
AC_MSG_RESULT([no integration])
else
SCPDEFS="$SCPDEFS -DWITH_HELPPACK_INTEGRATION"
AC_MSG_RESULT([integration])
fi
###############################################################################
# Extensions checking
###############################################################################

View file

@ -70,7 +70,7 @@ $(eval $(call gb_Library_add_exception_objects,deployment,\
desktop/source/deployment/registry/sfwk/dp_sfwk \
))
ifneq (,$(filter DESKTOP,$(BUILD_TYPE)))
ifneq (,$(filter XMLHELP,$(BUILD_TYPE)))
$(eval $(call gb_Library_use_libraries,deployment,\
helplinker \

View file

@ -0,0 +1 @@
Support for help integrated in extensions. Also see /README.help.md.

View file

@ -18,7 +18,7 @@
*/
#include <memory>
#include <config_feature_desktop.h>
#include <config_features.h>
#include <strings.hrc>
#include <dp_backend.h>
@ -31,7 +31,7 @@
#include <unotools/pathoptions.hxx>
#include <cppuhelper/supportsservice.hxx>
#if HAVE_FEATURE_DESKTOP
#if HAVE_FEATURE_XMLHELP
#include <helpcompiler/compilehelp.hxx>
#include <helpcompiler/HelpIndexer.hxx>
#endif
@ -378,7 +378,7 @@ void BackendImpl::implProcessHelp(
data.dataUrl = xPackage->getURL();
if (!package->extensionContainsCompiledHelp())
{
#if HAVE_FEATURE_DESKTOP
#if HAVE_FEATURE_XMLHELP
const OUString sHelpFolder = createFolder(xCmdEnv);
data.dataUrl = sHelpFolder;

View file

@ -9,13 +9,9 @@
$(eval $(call gb_Module_Module,clucene))
# do we need the Android check below? Shouldn't it be already covered by
# gb_Helper_optional in Module_external.mk?
ifneq ($(OS),ANDROID)
$(eval $(call gb_Module_add_targets,clucene,\
Library_clucene \
UnpackedTarball_clucene \
))
endif
# vim: set noet sw=4 ts=4:

View file

@ -10,8 +10,10 @@
$(eval $(call gb_Module_Module,helpcompiler))
$(eval $(call gb_Module_add_targets,helpcompiler,\
Executable_HelpIndexer \
Executable_HelpLinker \
$(call gb_Helper_optional,HELPTOOLS, \
Executable_HelpIndexer \
Executable_HelpLinker \
) \
Library_helplinker \
))

View file

@ -224,6 +224,7 @@ $(eval $(call gb_Rdb_add_components,services,\
wizards/com/sun/star/wizards/report/report \
wizards/com/sun/star/wizards/table/table \
) \
$(call gb_Helper_optional,XMLHELP,xmlhelp/util/ucpchelp1) \
))
$(eval $(call gb_Rdb_add_components,services,\
@ -298,7 +299,6 @@ $(eval $(call gb_Rdb_add_components,services,\
extensions/source/logging/log \
extensions/source/scanner/scn \
extensions/source/update/feed/updatefeed \
xmlhelp/util/ucpchelp1 \
$(if $(filter-out WNT,$(OS)),\
shell/source/cmdmail/cmdmail \
) \

View file

@ -18,7 +18,7 @@
#include "macros.inc"
#if defined WITH_HELP
#if defined WITH_HELPPACKS
File gid_File_Help_Sdatabase_Zip
Dir = FILELIST_DIR;
FILELIST_TXT_FILE_BODY_HELPPACK;

View file

@ -25,7 +25,7 @@ File gid_File_Share_Registry_Calc_Xcd
Name = "calc.xcd";
End
#if defined WITH_HELP
#if defined WITH_HELPPACKS
File gid_File_Help_Scalc_Zip
Dir = FILELIST_DIR;
FILELIST_TXT_FILE_BODY_HELPPACK;

View file

@ -25,7 +25,7 @@ File gid_File_Share_Registry_Draw_Xcd
Name = "draw.xcd";
End
#if defined WITH_HELP
#if defined WITH_HELPPACKS
File gid_File_Help_Sdraw_Zip
Dir = FILELIST_DIR;
FILELIST_TXT_FILE_BODY_HELPPACK;

View file

@ -25,7 +25,7 @@ File gid_File_Share_Registry_Impress_Xcd
Name = "impress.xcd";
End
#if defined WITH_HELP
#if defined WITH_HELPPACKS
File gid_File_Help_Simpress_Zip
Dir = FILELIST_DIR;
FILELIST_TXT_FILE_BODY_HELPPACK;

View file

@ -25,7 +25,7 @@ File gid_File_Share_Registry_Math_Xcd
Name = "math.xcd";
End
#if defined WITH_HELP
#if defined WITH_HELPPACKS
File gid_File_Help_Smath_Zip
Dir = FILELIST_DIR;
FILELIST_TXT_FILE_BODY_HELPPACK;

View file

@ -27,7 +27,7 @@
#include "macros.inc"
#if defined WITH_HELP
#if defined WITH_HELPPACKS
File gid_File_Help_Common_Zip
Dir = FILELIST_DIR;
FILELIST_TXT_FILE_BODY_HELPPACK;

View file

@ -18,7 +18,7 @@
#include "macros.inc"
#if defined WITH_HELP
#if defined WITH_HELPPACKS
File gid_File_Help_Swriter_Zip
Dir = FILELIST_DIR;
FILELIST_TXT_FILE_BODY_HELPPACK;

View file

@ -67,7 +67,7 @@ using namespace ::com::sun::star;
static SfxApplication* g_pSfxApplication = nullptr;
#if HAVE_FEATURE_DESKTOP
#if HAVE_FEATURE_XMLHELP
static SfxHelp* pSfxHelp = nullptr;
#endif
@ -127,7 +127,7 @@ SfxApplication* SfxApplication::GetOrCreate()
::framework::SetStatusBarControllerCreator( SfxStatusBarControllerFactory );
::framework::SetDockingWindowCreator( SfxDockingWindowFactory );
::framework::SetIsDockingWindowVisible( IsDockingWindowVisible );
#if HAVE_FEATURE_DESKTOP
#if HAVE_FEATURE_XMLHELP
Application::SetHelp( pSfxHelp );
if (!utl::ConfigManager::IsFuzzing() && SvtHelpOptions().IsHelpTips())
Help::EnableQuickHelp();
@ -167,7 +167,7 @@ SfxApplication::SfxApplication()
(void)bOk;
#endif
#if HAVE_FEATURE_DESKTOP
#if HAVE_FEATURE_XMLHELP
pSfxHelp = new SfxHelp;
#endif
@ -187,7 +187,7 @@ SfxApplication::~SfxApplication()
for (auto &module : pImpl->aModules) // Clear modules
module.reset();
#if HAVE_FEATURE_DESKTOP
#if HAVE_FEATURE_XMLHELP
delete pSfxHelp;
Application::SetHelp();
#endif

View file

@ -301,8 +301,21 @@ $(1) : $(2) | $(dir $(1)).dir
$(call gb_Deliver_add_deliverable,$(1),$(2),$(1))
endef
# call gb_Helper_optional,build_type,if-true,if-false
define gb_Helper_optional
$(if $(filter $(1),$(BUILD_TYPE)),$(2))
$(if $(filter $(1),$(BUILD_TYPE)),$(2),$(3))
endef
# call gb_Helper_optionals_or,build_types,if-true,if-false
define gb_Helper_optionals_or
$(call gb_Helper_optional,$(1),$(2),$(3))
endef
gb_Helper_optionals_and_token = $(subst $(gb_SPACE),_,gb $(sort $(1)))
# call gb_Helper_optionals_and,build_types,if-true,if-false
define gb_Helper_optionals_and
$(if $(filter $(call gb_Helper_optionals_and_token,$(1)),$(call gb_Helper_optionals_and_token,$(filter $(1),$(BUILD_TYPE)))),$(2),$(3))
endef
ifeq ($(WITH_LOCALES),)

View file

@ -33,11 +33,11 @@ gb_BUILD_TOOLS_executables = \
unoidl-check \
unoidl-write \
xrmex \
$(call gb_Helper_optional_for_host,DESKTOP, \
HelpIndexer \
HelpLinker \
lngconvex \
) \
$(call gb_Helper_optional_for_host,HELPTOOLS, \
HelpIndexer \
HelpLinker \
) \
$(if $(filter WNT,$(OS)),$(call gb_Helper_optional_for_host,DESKTOP,lngconvex)) \
gb_BUILD_TOOLS_executables_extern = \
python \

View file

@ -87,12 +87,12 @@ class HyperlinkDialog(UITestCase):
# opened in the user's default browser):
if os.getenv('ENABLE_HTMLHELP') == 'TRUE':
return
# Skip this test for --with-help, as that would fail with a
# Skip this test for --enable-xmlhelp, as that would fail with a
# "uno.com.sun.star.uno.RuntimeException: Could not find child with id: cancel" thrown from
# the below execute_blocking_action call, as it would open the "LibreOffice Help" window
# instead of the apparently expected "LibreOffice Help Not Installed" dialog that has a
# "Cancel" button:
if re.compile(r'-DWITH_HELP\b').search(os.getenv('SCPDEFS')):
if re.compile(r'XMLHELP\b').search(os.getenv('BUILD_TYPE')):
return
self.ui_test.create_doc_in_start_center("writer")

View file

@ -1,3 +1 @@
# XML Help
Help reader and viewer for online help.
Help viewer component for the XML help. For more info see /README.help.md.