From bbe5827c94cc9b0e393ff3e6eef6dec2376317e2 Mon Sep 17 00:00:00 2001 From: Nick Wellnhofer Date: Mon, 28 Apr 2025 17:21:05 +0200 Subject: [PATCH] doc: Build docs with Doxygen and xsltproc Build the documentation as part of the build process with support for all build systems. This adds a new configuration option --with-docs to build documentation. Required tools are Doxygen, xsltproc and the DocBook 4 XSLT stylesheets. Doxygen will also be required to build the Python bindings. --- .gitlab-ci.yml | 4 +- .gitlab-ci/Dockerfile | 8 +- .gitlab-ci/install.sh | 2 +- .gitlab-ci/setup_mingw.sh | 2 +- CMakeLists.txt | 81 ++++- Doxyfile | 107 ++++++ MAINTAINERS.md | 37 +- Makefile.am | 9 +- NEWS | 7 +- README.md | 8 + configure.ac | 28 +- doc/.gitignore | 2 + doc/Makefile.am | 53 ++- doc/libxml2.css | 9 + doc/meson.build | 62 +++- doc/xmlcatalog.1 | 356 -------------------- doc/xmlcatalog.html | 144 -------- doc/xmllint.1 | 688 -------------------------------------- doc/xmllint.html | 191 ----------- meson.build | 11 +- meson_options.txt | 41 +-- 21 files changed, 375 insertions(+), 1475 deletions(-) create mode 100644 Doxyfile create mode 100644 doc/.gitignore create mode 100644 doc/libxml2.css delete mode 100644 doc/xmlcatalog.1 delete mode 100644 doc/xmlcatalog.html delete mode 100644 doc/xmllint.1 delete mode 100644 doc/xmllint.html diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 082496d0..0f5686ff 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -323,9 +323,9 @@ dist: dotenv: build.env pages: + needs: [install] script: - - mkdir -p public - - cp -r doc/xmllint.html doc/xmlcatalog.html public + - cp -r install/share/doc/libxml2 public artifacts: paths: - public diff --git a/.gitlab-ci/Dockerfile b/.gitlab-ci/Dockerfile index 775bda21..e6b34684 100644 --- a/.gitlab-ci/Dockerfile +++ b/.gitlab-ci/Dockerfile @@ -4,9 +4,12 @@ # ------------------------------------------------------------ # libclang-rt-dev sanitizer runtimes # llvm llvm-symbolizer (for sanitizer backtraces) -# git libxslt +# git libxslt, downstream projects # libgcrypt-dev libxslt # xz-utils make dist +# doxygen documentation +# xsltproc documentation +# docbook-xsl documentation FROM ubuntu:24.04 ENV DEBIAN_FRONTEND=noninteractive @@ -19,7 +22,8 @@ RUN apt-get update && \ zlib1g-dev liblzma-dev libgcrypt-dev \ python3-dev \ cmake meson \ - xz-utils + xz-utils \ + doxygen xsltproc docbook-xsl WORKDIR /tests RUN curl https://www.w3.org/XML/Test/xmlts20080827.tar.gz |tar xz diff --git a/.gitlab-ci/install.sh b/.gitlab-ci/install.sh index c0c6ca8d..6b90f40c 100644 --- a/.gitlab-ci/install.sh +++ b/.gitlab-ci/install.sh @@ -8,7 +8,7 @@ mkdir -p install installdir="$srcdir/install" export PKG_CONFIG_PATH="$installdir/lib/pkgconfig" -sh autogen.sh "--prefix=$installdir" --with-http --with-zlib --without-python +sh autogen.sh "--prefix=$installdir" --with-docs --with-zlib make -j$(nproc) make install diff --git a/.gitlab-ci/setup_mingw.sh b/.gitlab-ci/setup_mingw.sh index e9df9a62..bdc3df02 100644 --- a/.gitlab-ci/setup_mingw.sh +++ b/.gitlab-ci/setup_mingw.sh @@ -6,7 +6,7 @@ prefix= if [ -n "$MINGW_PACKAGE_PREFIX" ]; then prefix="${MINGW_PACKAGE_PREFIX}-" fi -for module in libiconv python xz zlib "$@"; do +for module in doxygen libiconv python xz zlib "$@"; do pacman --noconfirm -S --needed ${prefix}$module done diff --git a/CMakeLists.txt b/CMakeLists.txt index bdaafa38..508f369b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -26,6 +26,7 @@ include(GNUInstallDirs) option(BUILD_SHARED_LIBS "Build shared libraries" ON) option(LIBXML2_WITH_CATALOG "Add the Catalog support" ON) option(LIBXML2_WITH_DEBUG "Add the debugging module" ON) +option(LIBXML2_WITH_DOCS "Build documentation" OFF) option(LIBXML2_WITH_HTML "Add the HTML support" ON) option(LIBXML2_WITH_HTTP "ABI compatibility for removed HTTP support" OFF) option(LIBXML2_WITH_ICONV "Add ICONV support" ON) @@ -508,6 +509,20 @@ if(LIBXML2_WITH_TESTS) add_test(NAME testrecurse COMMAND testrecurse WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) endif() +if(LIBXML2_WITH_DOCS OR LIBXML2_WITH_PYTHON) + set(DOXYFILE ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile) + add_custom_command( + OUTPUT doc/html doc/xml + COMMAND ${CMAKE_COMMAND} -E env + SOURCE_ROOT=${CMAKE_CURRENT_SOURCE_DIR}/ + BUILD_ROOT=${CMAKE_CURRENT_BINARY_DIR}/ + doxygen -q ${DOXYFILE} + MAIN_DEPENDENCY ${DOXYFILE} + DEPENDS ${LIBXML2_HDRS} ${LIBXML2_SRCS} + ) + add_custom_target(Doxygen ALL DEPENDS doc/html doc/xml) +endif() + if(LIBXML2_WITH_PYTHON) execute_process( COMMAND @@ -549,19 +564,61 @@ if(LIBXML2_WITH_PYTHON) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/libxml2.py DESTINATION ${LIBXML2_PYTHON_INSTALL_DIR} COMPONENT runtime) endif() -install(FILES doc/xml2-config.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 COMPONENT documentation) -if(LIBXML2_WITH_PROGRAMS) - install(FILES doc/xmlcatalog.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 COMPONENT documentation) - install(FILES doc/xmllint.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 COMPONENT documentation) +if (LIBXML2_WITH_DOCS) + set(MAN_PAGES doc/xml2-config.1) + + if(LIBXML2_WITH_PROGRAMS) + set(PROGNAMES xmllint) + if(LIBXML2_WITH_CATALOG AND LIBXML2_WITH_OUTPUT) + list(APPEND PROGNAMES xmlcatalog) + endif() + foreach(PROG IN ITEMS ${PROGNAMES}) + set(XML_SRC ${CMAKE_CURRENT_SOURCE_DIR}/doc/${PROG}.xml) + + add_custom_command( + OUTPUT ${PROG}.1 + COMMAND xsltproc + --nonet --novalid + --param man.output.quietly 1 + -o ${PROG}.1 + http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl + ${XML_SRC} + MAIN_DEPENDENCY ${XML_SRC} + ) + list(APPEND MAN_PAGES ${CMAKE_CURRENT_BINARY_DIR}/${PROG}.1) + + add_custom_command( + OUTPUT ${PROG}.html + COMMAND xsltproc + --nonet --novalid + -o ${PROG}.html + http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl + ${XML_SRC} + MAIN_DEPENDENCY ${XML_SRC} + ) + list(APPEND HTML_PAGES ${CMAKE_CURRENT_BINARY_DIR}/${PROG}.html) + endforeach() + + add_custom_target(DocBook ALL DEPENDS ${MAN_PAGES} ${HTML_PAGES}) + + install( + FILES ${HTML_PAGES} + DESTINATION ${CMAKE_INSTALL_DOCDIR} + COMPONENT documentation + ) + endif() + + install( + FILES ${MAN_PAGES} + DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 + COMPONENT documentation + ) + install( + DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc/html + DESTINATION ${CMAKE_INSTALL_DOCDIR} + COMPONENT documentation + ) endif() -install(DIRECTORY doc/ DESTINATION ${CMAKE_INSTALL_DOCDIR} COMPONENT documentation - PATTERN "Makefile.*" EXCLUDE - PATTERN "meson.build" EXCLUDE - PATTERN "*.1" EXCLUDE - PATTERN "*.py" EXCLUDE - PATTERN "*.res" EXCLUDE - PATTERN "*.xml" EXCLUDE - PATTERN "*.xsl" EXCLUDE) configure_package_config_file( libxml2-config.cmake.cmake.in libxml2-config.cmake diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 00000000..1dc9b639 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,107 @@ +PROJECT_NAME = libxml2 +OUTPUT_DIRECTORY = $(BUILD_ROOT)doc +STRIP_FROM_PATH = $(SOURCE_ROOT)include/libxml +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_LOCAL_CLASSES = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_SCOPE_NAMES = YES +SHOW_INCLUDE_FILES = NO +WARN_NO_PARAMDOC = YES +INPUT = $(SOURCE_ROOT)README.md \ + $(SOURCE_ROOT)include/libxml/c14n.h \ + $(SOURCE_ROOT)include/libxml/catalog.h \ + $(SOURCE_ROOT)include/libxml/chvalid.h \ + $(SOURCE_ROOT)include/libxml/debugXML.h \ + $(SOURCE_ROOT)include/libxml/dict.h \ + $(SOURCE_ROOT)include/libxml/encoding.h \ + $(SOURCE_ROOT)include/libxml/entities.h \ + $(SOURCE_ROOT)include/libxml/hash.h \ + $(SOURCE_ROOT)include/libxml/HTMLparser.h \ + $(SOURCE_ROOT)include/libxml/HTMLtree.h \ + $(SOURCE_ROOT)include/libxml/list.h \ + $(SOURCE_ROOT)include/libxml/parser.h \ + $(SOURCE_ROOT)include/libxml/parserInternals.h \ + $(SOURCE_ROOT)include/libxml/pattern.h \ + $(SOURCE_ROOT)include/libxml/relaxng.h \ + $(SOURCE_ROOT)include/libxml/SAX2.h \ + $(SOURCE_ROOT)include/libxml/schemasInternals.h \ + $(SOURCE_ROOT)include/libxml/schematron.h \ + $(SOURCE_ROOT)include/libxml/threads.h \ + $(SOURCE_ROOT)include/libxml/tree.h \ + $(SOURCE_ROOT)include/libxml/uri.h \ + $(SOURCE_ROOT)include/libxml/valid.h \ + $(SOURCE_ROOT)include/libxml/xinclude.h \ + $(SOURCE_ROOT)include/libxml/xlink.h \ + $(SOURCE_ROOT)include/libxml/xmlautomata.h \ + $(SOURCE_ROOT)include/libxml/xmlerror.h \ + $(SOURCE_ROOT)include/libxml/xmlIO.h \ + $(SOURCE_ROOT)include/libxml/xmlmemory.h \ + $(SOURCE_ROOT)include/libxml/xmlmodule.h \ + $(SOURCE_ROOT)include/libxml/xmlreader.h \ + $(SOURCE_ROOT)include/libxml/xmlregexp.h \ + $(SOURCE_ROOT)include/libxml/xmlsave.h \ + $(SOURCE_ROOT)include/libxml/xmlschemas.h \ + $(SOURCE_ROOT)include/libxml/xmlschemastypes.h \ + $(SOURCE_ROOT)include/libxml/xmlstring.h \ + $(SOURCE_ROOT)include/libxml/xmlunicode.h \ + $(SOURCE_ROOT)include/libxml/xmlwriter.h \ + $(SOURCE_ROOT)include/libxml/xpath.h \ + $(SOURCE_ROOT)include/libxml/xpathInternals.h \ + $(SOURCE_ROOT)include/libxml/xpointer.h \ + $(SOURCE_ROOT)buf.c \ + $(SOURCE_ROOT)c14n.c \ + $(SOURCE_ROOT)catalog.c \ + $(SOURCE_ROOT)chvalid.c \ + $(SOURCE_ROOT)debugXML.c \ + $(SOURCE_ROOT)dict.c \ + $(SOURCE_ROOT)encoding.c \ + $(SOURCE_ROOT)entities.c \ + $(SOURCE_ROOT)error.c \ + $(SOURCE_ROOT)globals.c \ + $(SOURCE_ROOT)hash.c \ + $(SOURCE_ROOT)HTMLparser.c \ + $(SOURCE_ROOT)HTMLtree.c \ + $(SOURCE_ROOT)list.c \ + $(SOURCE_ROOT)parser.c \ + $(SOURCE_ROOT)parserInternals.c \ + $(SOURCE_ROOT)pattern.c \ + $(SOURCE_ROOT)relaxng.c \ + $(SOURCE_ROOT)SAX2.c \ + $(SOURCE_ROOT)schematron.c \ + $(SOURCE_ROOT)threads.c \ + $(SOURCE_ROOT)tree.c \ + $(SOURCE_ROOT)uri.c \ + $(SOURCE_ROOT)valid.c \ + $(SOURCE_ROOT)xinclude.c \ + $(SOURCE_ROOT)xlink.c \ + $(SOURCE_ROOT)xmlcatalog.c \ + $(SOURCE_ROOT)xmlIO.c \ + $(SOURCE_ROOT)xmlmemory.c \ + $(SOURCE_ROOT)xmlmodule.c \ + $(SOURCE_ROOT)xmlreader.c \ + $(SOURCE_ROOT)xmlregexp.c \ + $(SOURCE_ROOT)xmlsave.c \ + $(SOURCE_ROOT)xmlschemas.c \ + $(SOURCE_ROOT)xmlschemastypes.c \ + $(SOURCE_ROOT)xmlstring.c \ + $(SOURCE_ROOT)xmlwriter.c \ + $(SOURCE_ROOT)xpath.c \ + $(SOURCE_ROOT)xpointer.c +USE_MDFILE_AS_MAINPAGE = $(SOURCE_ROOT)README.md +EXCLUDE_SYMLINKS = YES +VERBATIM_HEADERS = NO +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +HTML_EXTRA_STYLESHEET = $(SOURCE_ROOT)doc/libxml2.css +ENUM_VALUES_PER_LINE = 0 +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_PROGRAMLISTING = NO +MACRO_EXPANSION = YES +INCLUDE_PATH = $(SOURCE_ROOT). \ + $(SOURCE_ROOT)include \ + $(BUILD_ROOT). \ + $(BUILD_ROOT)include +PREDEFINED = XML_TREE_INTERNALS +HAVE_DOT = NO diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 37a45d19..fe214f16 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -14,33 +14,34 @@ expected results. You can restore the original results by running ## Generated files -The documentation and other generated files can be rebuilt by running +Some source code is generated with Python scripts in the `tools` +directory. - make -C doc rebuild +- `tools/genChRanges.py` generates code to handle character ranges + from chvalid.def: + - `chvalid.c` + - `include/libxml/chvalid.h` -Besides Python, this requires `xsltproc` and the DocBook stylesheets in -your XML Catalog. On Debian/Ubuntu, try +- `tools/genEscape prints lookup tables for serialization. - apt install xsltproc docbook-xsl docbook-xml +- `tools/genHtml5LibTests.py` creates test cases and expected results + from the html5lib test suite: + - `test/html-tokenizer` + - `result/html-tokenizer` -doc/apibuild.py generates doc/libxml2-api.xml which is used to generate +- `tools/genHtmlEnt.py` prints lookup tables for HTML5 named character + references (predefined entities): + - `html5ent.inc` -- API documentation with XSLT stylesheets -- testapi.c with gentest.py -- Python bindings with python/generator.py +- `tools/gentest.py` generates test code using the Doxygen XML output: + - `testapi.c` -Man pages and HTML documentation for xmllint and xmlcatalog are -generated with xsltproc and DocBook stylesheets. +- `tools/genUnicode.py` generates code to handle Unicode ranges + from Unicode data files: + - `xmlunicode.c` ## Making a release -### Rebuild generated files and documentation - -See above for details and run `make -C doc rebuild`. - -Look for new warning messages and inspect changes for correctness -before committing. - ### Update the NEWS file You can get started by running diff --git a/Makefile.am b/Makefile.am index 0809a16f..012cd609 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2,7 +2,10 @@ ACLOCAL_AMFLAGS = -I m4 -SUBDIRS = include . doc example xstc +SUBDIRS = include . example xstc +if WITH_DOXYGEN +SUBDIRS += doc +endif if WITH_PYTHON SUBDIRS += python endif @@ -206,8 +209,8 @@ EXTRA_DIST = Copyright libxml2-config.cmake.in autogen.sh \ timsort.h \ README.zOS README.md \ CMakeLists.txt config.h.cmake.in libxml2-config.cmake.cmake.in \ - meson.build meson_options.txt xml2-config-meson - + meson.build meson_options.txt xml2-config-meson \ + Doxyfile pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = libxml-2.0.pc diff --git a/NEWS b/NEWS index b45b616d..3f5b87d7 100644 --- a/NEWS +++ b/NEWS @@ -4,7 +4,12 @@ v2.15.0: not released yet ### Major changes -The Python bindings are disabled by default now. +The API documentation is now generated with Doxygen. Building the +documentation requires the new --with-docs configuration option as well +as Doxygen, xsltproc and the DocBook 4 XSLT stylesheets. + +The Python bindings are disabled by default now. Building the bindings +also requires Doxygen. ### Removals diff --git a/README.md b/README.md index d75f42e5..6e91c10d 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ The following options disable or enable code modules and relevant symbols: --with-c14n Canonical XML 1.0 support (on) --with-catalog XML Catalogs support (on) --with-debug debugging module (on) + --with-docs Build documentation (off) --with-history history support for xmllint shell (off) --with-readline[=DIR] use readline in DIR for shell (off) --with-html HTML parser (on) @@ -152,6 +153,13 @@ Use of this feature is discouraged. The xmllint executable uses libreadline and libhistory if enabled. +### Build requirements + +Besides build system tools, only a C compiler should be required. +Reconfiguration of the Autotools build requires the pkg.m4 macro from +pkg-config. Building the documentation requires Doxygen, xsltproc and the +DocBook 4 XSLT stylesheets. Building the Python bindings requires Doxygen. + ## Contributing The current version of the code can be found in GNOME's GitLab at diff --git a/configure.ac b/configure.ac index 2e26231c..1c24b0ab 100644 --- a/configure.ac +++ b/configure.ac @@ -55,7 +55,6 @@ AC_PROG_LN_S AC_PROG_MKDIR_P AC_PATH_PROG(TAR, tar, /bin/tar) AC_PATH_PROG(WGET, wget, /usr/bin/wget) -AC_PATH_PROG(XSLTPROC, xsltproc, /usr/bin/xsltproc) PKG_PROG_PKG_CONFIG LT_INIT([disable-static]) @@ -73,6 +72,8 @@ AC_ARG_WITH(catalog, [ --with-catalog XML Catalogs support (on)]) AC_ARG_WITH(debug, [ --with-debug debugging module (on)]) +AC_ARG_WITH(docs, +[ --with-docs Build documentation (off)]) AC_ARG_WITH(history, [ --with-history history support for xmllint shell (off)]) AC_ARG_WITH(readline, @@ -561,6 +562,18 @@ fi AC_SUBST(WITH_DEBUG) AM_CONDITIONAL(WITH_DEBUG_SOURCES, test "$WITH_DEBUG" = "1") +if test "$with_docs" = "yes" ; then + echo Enabling documentation + AC_PATH_PROG(XSLTPROC, xsltproc, [no]) + if test "$XSLTPROC" = "no"; then + AC_MSG_ERROR([cannot find xsltproc]) + fi + WITH_DOCS=1 +else + WITH_DOCS=0 +fi +AM_CONDITIONAL(WITH_DOCS, test "$WITH_DOCS" = "1") + dnl dnl Check for Python dnl @@ -571,6 +584,19 @@ AS_IF([test "x$with_python" = "xyes"], [ ]) AM_CONDITIONAL([WITH_PYTHON], [test "x$with_python" = "xyes"]) +dnl +dnl Check for Doxygen +dnl + +if test "$with_python" = "yes" || test "$with_docs" = "yes"; then + AC_PATH_PROG(DOXYGEN, doxygen, [no]) + if test "$DOXYGEN" = "no"; then + AC_MSG_ERROR([cannot find doxygen]) + fi + WITH_DOXYGEN=1 +fi +AM_CONDITIONAL([WITH_DOXYGEN], test "$WITH_DOXYGEN" = "1") + dnl dnl Extra Python flags dnl diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..a2449d69 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +/html/ +/xml/ diff --git a/doc/Makefile.am b/doc/Makefile.am index e3d5f83e..918a15be 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,9 +1,4 @@ ## Process this file with automake to produce Makefile.in -nobase_dist_doc_DATA = \ - xmlcatalog.html \ - xmllint.html - -dist_man_MANS = xml2-config.1 xmllint.1 xmlcatalog.1 EXTRA_DIST = \ libxml2-api.xml \ @@ -11,12 +6,48 @@ EXTRA_DIST = \ xmllint.xml \ meson.build +all-local: html.stamp + +html.stamp: $(top_srcdir)/Doxyfile + SOURCE_ROOT=$(top_srcdir)/ BUILD_ROOT=$(top_builddir)/ \ + $(DOXYGEN) -q $< + @touch $@ + +CLEANFILES = html.stamp + +clean-local: + rm -rf html xml + +if WITH_DOCS + +man_MANS = xml2-config.1 xmllint.1 +doc_DATA = xmllint.html +CLEANFILES += xmllint.1 xmllint.html + +if WITH_CATALOG_SOURCES +if WITH_OUTPUT_SOURCES +man_MANS += xmlcatalog.1 +doc_DATA += xmlcatalog.html +CLEANFILES += xmlcatalog.1 xmlcatalog.html +endif +endif + +DOCBOOK_MAN = http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl DOCBOOK_HTML = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl -rebuild: - cd $(srcdir) && $(XSLTPROC) --nonet xmllint.xml - cd $(srcdir) && $(XSLTPROC) --nonet -o xmllint.html $(DOCBOOK_HTML) xmllint.xml - cd $(srcdir) && $(XSLTPROC) --nonet xmlcatalog.xml - cd $(srcdir) && $(XSLTPROC) --nonet -o xmlcatalog.html $(DOCBOOK_HTML) xmlcatalog.xml +.xml.1: + $(XSLTPROC) --nonet --novalid --param man.output.quietly 1 \ + -o $@ $(DOCBOOK_MAN) $< -.PHONY: rebuild +.xml.html: + $(XSLTPROC) --nonet --novalid -o $@ $(DOCBOOK_HTML) $< + +install-data-local: + $(MKDIR_P) $(DESTDIR)$(docdir)/html/search + find html -type f -exec $(INSTALL_DATA) {} $(DESTDIR)$(docdir)/html \; + find html/search -type f -exec $(INSTALL_DATA) {} $(DESTDIR)$(docdir)/html/search \; + +uninstall-local: + -rm -rf $(DESTDIR)$(docdir)/html + +endif diff --git a/doc/libxml2.css b/doc/libxml2.css new file mode 100644 index 00000000..b75749cd --- /dev/null +++ b/doc/libxml2.css @@ -0,0 +1,9 @@ +div.contents { + max-width: 60em; +} +h1 { + font-size: 1.5em; +} +h2 { + font-size: 1.25em; +} diff --git a/doc/meson.build b/doc/meson.build index c80fda9b..66641124 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,10 +1,60 @@ +# Doxygen -install_man(files(['xml2-config.1', 'xmlcatalog.1', 'xmllint.1'])) +doxygen = find_program('doxygen') - -tutorial_files = files( - 'xmlcatalog.html', - 'xmllint.html', +doxygen_docs = custom_target( + 'Doxygen documentation', + input: [ xml_src_files, libxml_headers ], + output: [ 'html', 'xml' ], + command: [ doxygen, '-q', doxyfile ], + env: { + 'SOURCE_ROOT': meson.project_source_root() + '/', + 'BUILD_ROOT': meson.project_build_root() + '/', + }, + install: true, + install_dir: [ want_docs ? dir_doc : false, false ], ) -install_data(tutorial_files, install_dir: dir_doc) +if want_docs + # xml2-config + + install_man('xml2-config.1') + + # Docbook + + xsltproc = find_program('xsltproc') + types = [ + [ 'manpages', '.1', dir_man ], + [ 'html', '.html', dir_doc ], + ] + programs = [ 'xmllint' ] + if want_catalog and want_output + programs += 'xmlcatalog' + endif + + foreach prog : programs + foreach type : types + format = type[0] + ext = type[1] + install_dir = type[2] + + xsl = 'http://docbook.sourceforge.net' + \ + f'/release/xsl/current/@format@/docbook.xsl' + output = prog + ext + + custom_target( + output, + input: prog + '.xml', + output: output, + command: [xsltproc, + '--nonet', '--novalid', + '--param', 'man.output.quietly', '1', + '-o', '@OUTPUT@', + xsl, '@INPUT@' + ], + install: true, + install_dir: install_dir + ) + endforeach + endforeach +endif diff --git a/doc/xmlcatalog.1 b/doc/xmlcatalog.1 deleted file mode 100644 index 38270cad..00000000 --- a/doc/xmlcatalog.1 +++ /dev/null @@ -1,356 +0,0 @@ -'\" t -.\" Title: xmlcatalog -.\" Author: John Fleck -.\" Generator: DocBook XSL Stylesheets vsnapshot -.\" Date: 06/12/2024 -.\" Manual: xmlcatalog Manual -.\" Source: libxml2 -.\" Language: English -.\" -.TH "XMLCATALOG" "1" "06/12/2024" "libxml2" "xmlcatalog Manual" -.\" ----------------------------------------------------------------- -.\" * Define some portability stuff -.\" ----------------------------------------------------------------- -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.\" http://bugs.debian.org/507673 -.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" ----------------------------------------------------------------- -.\" * set default formatting -.\" ----------------------------------------------------------------- -.\" disable hyphenation -.nh -.\" disable justification (adjust text to left margin only) -.ad l -.\" ----------------------------------------------------------------- -.\" * MAIN CONTENT STARTS HERE * -.\" ----------------------------------------------------------------- -.SH "NAME" -xmlcatalog \- Command line tool to parse and manipulate XML or SGML catalog files\&. -.SH "SYNOPSIS" -.HP \w'\fBxmlcatalog\fR\ 'u -\fBxmlcatalog\fR [\fB\-\-sgml\fR | \fB\-\-shell\fR | \fB\-\-convert\fR | \fB\-\-create\fR | \fB\-\-del\ \fR\fB\fIVALUE(S)\fR\fR | [\ \fB\-\-add\ \fR\fB\fITYPE\fR\fR\fB\ \fR\fB\fIORIG\fR\fR\fB\ \fR\fB\fIREPLACE\fR\fR\fB\ \fR\ |\ \fB\-\-add\ \fR\fB\fIFILENAME\fR\fR] | \fB\-\-noout\fR | \fB\-\-no\-super\-update\fR | [\fB\-v\fR\ |\ \fB\-\-verbose\fR]] {\fICATALOGFILE\fR} {\fIENTITIES\fR...} -.SH "DESCRIPTION" -.PP -\fBxmlcatalog\fR -is a command line application allowing users to monitor and manipulate -XML -and -SGML -catalogs\&. It is included in -\fBlibxml\fR(3)\&. -.PP -Its functions can be invoked from a single command from the command line, or it can perform multiple functions in interactive mode\&. It can operate on both -XML -and -SGML -files\&. -.SH "OPTIONS" -.PP -\fBxmlcatalog\fR -accepts the following options (in alphabetical order): -.PP -\fB\-\-add \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIORIG\fR\fR\fB \fR\fB\fIREPLACE\fR\fR\fB \fR -.RS 4 -Add an entry to -CATALOGFILE\&. -\fITYPE\fR -indicates the type of entry\&. Possible types are: -\fIpublic\fR, \fIsystem\fR, \fIuri\fR, \fIrewriteSystem\fR, \fIrewriteURI\fR, \fIdelegatePublic\fR, \fIdelegateSystem\fR, \fIdelegateURI\fR, \fInextCatalog\fR\&. -\fIORIG\fR -is the original reference to be replaced, and -\fIREPLACE\fR -is the -URI -of the replacement entity to be used\&. The -\fB\-\-add\fR -option will not overwrite -CATALOGFILE, outputting to -stdout, unless -\fB\-\-noout\fR -is used\&. The -\fB\-\-add\fR -will always take three parameters even if some of the -XML -catalog constructs will have only a single argument\&. -.RE -.PP -\fB\-\-add \fR\fB\fIFILENAME\fR\fR -.RS 4 -If the -\fB\-\-add\fR -option is used following the -\fB\-\-sgml\fR -option, only a single argument, a -\fIFILENAME\fR, is used\&. This is used to add the name of a catalog file to an -SGML -supercatalog, a file that contains references to other included -SGML -catalog files\&. -.RE -.PP -\fB\-\-convert\fR -.RS 4 -Convert SGML catalog to XML\&. -.RE -.PP -\fB\-\-create\fR -.RS 4 -Create a new -XML -catalog\&. Outputs to -stdout, ignoring -\fIfilename\fR -unless -\fB\-\-noout\fR -is used, in which case it creates a new catalog file -\fIfilename\fR\&. -.RE -.PP -\fB\-\-del \fR\fB\fIVALUE(S)\fR\fR -.RS 4 -Remove entries from -\fICATALOGFILE\fR -matching -\fIVALUE(S)\fR\&. The -\fB\-\-del\fR -option will not overwrite -\fICATALOGFILE\fR, outputting to -stdout, unless -\fB\-\-noout\fR -is used\&. -.RE -.PP -\fB\-\-noout\fR -.RS 4 -Save output to the named file rather than outputting to -stdout\&. -.RE -.PP -\fB\-\-no\-super\-update\fR -.RS 4 -Do not update the -SGML -super catalog\&. -.RE -.PP -\fB\-\-shell\fR -.RS 4 -Run a shell allowing interactive queries on catalog file -\fICATALOGFILE\fR\&. For the set of available commands see -the section called \(lqSHELL COMMANDS\(rq\&. -.RE -.PP -\fB\-\-sgml\fR -.RS 4 -Uses -SGML -super catalogs for -\fB\-\-add\fR -and -\fB\-\-del\fR -options\&. -.RE -.PP -\fB\-v\fR, \fB\-\-verbose\fR -.RS 4 -Output debugging information\&. -.RE -.PP -Invoking -\fBxmlcatalog\fR -non\-interactively without a designated action (imposed with options like -\fB\-\-add\fR) will result in a lookup of the catalog entry for -\fIENTITIES\fR -in the catalog denoted with -\fICATALOGFILE\fR\&. The corresponding entries will be output to the command line\&. This mode of operation, together with -\fB\-\-shell\fR -mode and non\-modifying (i\&.e\&. without -\fB\-\-noout\fR) direct actions, allows for a special shortcut of the void -\fICATALOGFILE\fR -specification (possibly expressed as "" in the shell environment) appointing the default system catalog\&. That simplifies the handling when its exact location is irrelevant but the respective built\-in still needs to be consulted\&. -.SH "SHELL COMMANDS" -.PP -Invoking -\fBxmlcatalog\fR -with the -\fB\-\-shell \fR\fB\fICATALOGFILE\fR\fR -option opens a command line shell allowing interactive access to the catalog file identified by -\fICATALOGFILE\fR\&. Invoking the shell provides a command line prompt after which the following commands (described in alphabetical order) can be entered\&. -.PP -\fBadd \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIORIG\fR\fR\fB \fR\fB\fIREPLACE\fR\fR\fB \fR -.RS 4 -Add an entry to the catalog file\&. -\fITYPE\fR -indicates the type of entry\&. Possible types are: -\fIpublic\fR, \fIsystem\fR, \fIuri\fR, \fIrewriteSystem\fR, \fIrewriteURI\fR, \fIdelegatePublic\fR, \fIdelegateSystem\fR, \fIdelegateURI\fR, \fInextCatalog\fR\&. -\fIORIG\fR -is the original reference to be replaced, and -\fIREPLACE\fR -is the -URI -of the replacement entity to be used\&. The -\fB\-\-add\fR -option will not overwrite -CATALOGFILE, outputting to -stdout, unless -\fB\-\-noout\fR -is used\&. The -\fB\-\-add\fR -will always take three parameters even if some of the -XML -catalog constructs will have only a single argument\&. -.RE -.PP -\fBdebug\fR -.RS 4 -Print debugging statements showing the steps -\fBxmlcatalog\fR -is executing\&. -.RE -.PP -\fBdel \fR\fB\fIVALUE(S)\fR\fR -.RS 4 -Remove the catalog entry corresponding to -\fIVALUE(S)\fR\&. -.RE -.PP -\fBdump\fR -.RS 4 -Print the current catalog\&. -.RE -.PP -\fBexit\fR -.RS 4 -Quit the shell\&. -.RE -.PP -\fBpublic \fR\fB\fIPUBLIC\-ID\fR\fR -.RS 4 -Execute a Formal Public Identifier lookup of the catalog entry for -\fIPUBLIC\-ID\fR\&. The corresponding entry will be output to the command line\&. -.RE -.PP -\fBquiet\fR -.RS 4 -Stop printing debugging statements\&. -.RE -.PP -\fBsystem \fR\fB\fISYSTEM\-ID\fR\fR -.RS 4 -Execute a Formal Public Identifier lookup of the catalog entry for -\fISYSTEM\-ID\fR\&. The corresponding entry will be output to the command line\&. -.RE -.SH "ENVIRONMENT" -.PP -\fBXML_CATALOG_FILES\fR -.RS 4 -XML -catalog behavior can be changed by redirecting queries to the user\*(Aqs own set of catalogs\&. This can be done by setting the -\fBXML_CATALOG_FILES\fR -environment variable to a space\-separated list of catalogs\&. Use percent\-encoding to escape spaces or other characters\&. An empty variable should deactivate loading the default catalog from -/etc/xml/catalog -or, more specifically, -${sysconfdir}/xml/catalog\&. -.RE -.SH "DIAGNOSTICS" -.PP -\fBxmlcatalog\fR -return codes provide information that can be used when calling it from scripts\&. -.PP -\fB0\fR -.RS 4 -No error -.RE -.PP -\fB1\fR -.RS 4 -Failed to remove an entry from the catalog -.RE -.PP -\fB2\fR -.RS 4 -Failed to save to the catalog, check file permissions -.RE -.PP -\fB3\fR -.RS 4 -Failed to add an entry to the catalog -.RE -.PP -\fB4\fR -.RS 4 -Failed to look up an entry in the catalog -.RE -.SH "SEE ALSO" -.PP -\fBlibxml\fR(3) -.PP -More information can be found at -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -\fBlibxml\fR(3) -web page -\m[blue]\fB\%https://gitlab.gnome.org/GNOME/libxml2\fR\m[] -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -\fBlibxml\fR(3) -catalog support web page at -\m[blue]\fB\%https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support\fR\m[] -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -James Clark\*(Aqs -SGML -catalog page -\m[blue]\fB\%http://www.jclark.com/sp/catalog.htm\fR\m[] -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -OASIS -XML -catalog specification -\m[blue]\fB\%http://www.oasis-open.org/committees/entity/spec.html\fR\m[] -.RE -.sp -.SH "AUTHOR" -.PP -\fBJohn Fleck\fR <\&jfleck@inkstain\&.net\&> -.RS 4 -Author. -.RE -.SH "COPYRIGHT" -.br -Copyright \(co 2001, 2004 -.br diff --git a/doc/xmlcatalog.html b/doc/xmlcatalog.html deleted file mode 100644 index 01ff8640..00000000 --- a/doc/xmlcatalog.html +++ /dev/null @@ -1,144 +0,0 @@ -xmlcatalog

Name

xmlcatalog — - Command line tool to parse and manipulate XML - or SGML catalog files. -

Synopsis

xmlcatalog [ --sgml | --shell | --convert | --create | --del VALUE(S) | - [ - --add - TYPE - ORIG - REPLACE - - | --add FILENAME ] - | --noout | --no-super-update | - [ -v | --verbose ] - ] {CATALOGFILE} {ENTITIES...}

DESCRIPTION

- xmlcatalog is a command line application allowing users to monitor and - manipulate XML and SGML catalogs. It - is included in libxml(3). -

- Its functions can be invoked from a single command from the command line, - or it can perform multiple functions in interactive mode. It can operate - on both XML and SGML files. -

OPTIONS

- xmlcatalog accepts the following options (in alphabetical order): -

- --add - TYPE - ORIG - REPLACE - -

- Add an entry to CATALOGFILE. TYPE - indicates the type of entry. Possible types are: public, system, uri, rewriteSystem, rewriteURI, delegatePublic, delegateSystem, delegateURI, nextCatalog. ORIG is the original - reference to be replaced, and REPLACE - is the URI of the replacement entity to be - used. The --add option will not overwrite - CATALOGFILE, outputting - to stdout, unless - --noout is used. The --add will - always take three parameters even if some of the XML - catalog constructs will have only a single argument. -

--add FILENAME

- If the --add option is used following - the --sgml option, only a single argument, - a FILENAME, is used. This is used to add - the name of a catalog file to an SGML supercatalog, - a file that contains references to other included SGML - catalog files. -

--convert

- Convert SGML catalog to XML. -

--create

- Create a new XML catalog. Outputs - to stdout, - ignoring filename unless --noout is - used, in which case it creates a new catalog - file filename. -

--del VALUE(S)

- Remove entries from CATALOGFILE - matching VALUE(S). The --del - option will not overwrite CATALOGFILE, - outputting to stdout, - unless --noout is used. -

--noout

- Save output to the named file rather than outputting - to stdout. -

--no-super-update

- Do not update the SGML super catalog. -

--shell

- Run a shell allowing interactive queries on catalog - file CATALOGFILE. For the set of available - commands see the section called “SHELL COMMANDS”. -

--sgml

- Uses SGML super catalogs for --add - and --del options. -

-v, --verbose

Output debugging information.

- Invoking xmlcatalog non-interactively without a designated action - (imposed with options like --add) will result in a lookup - of the catalog entry for ENTITIES in the - catalog denoted with CATALOGFILE. The - corresponding entries will be output to the command line. This mode of - operation, together with --shell mode and non-modifying - (i.e. without --noout) direct actions, allows for - a special shortcut of the void CATALOGFILE - specification (possibly expressed as "" in the shell - environment) appointing the default system catalog. That simplifies the - handling when its exact location is irrelevant but the respective built-in - still needs to be consulted. -

SHELL COMMANDS

- Invoking xmlcatalog with - the --shell CATALOGFILE option opens - a command line shell allowing interactive access to the catalog file - identified by CATALOGFILE. Invoking the shell - provides a command line prompt after which the following commands (described in - alphabetical order) can be entered. -

- add - TYPE - ORIG - REPLACE - -

- Add an entry to the catalog file. TYPE - indicates the type of entry. Possible types are: public, system, uri, rewriteSystem, rewriteURI, delegatePublic, delegateSystem, delegateURI, nextCatalog. ORIG is the original - reference to be replaced, and REPLACE - is the URI of the replacement entity to be - used. The --add option will not overwrite - CATALOGFILE, outputting - to stdout, unless - --noout is used. The --add will - always take three parameters even if some of the XML - catalog constructs will have only a single argument. -

debug

- Print debugging statements showing the steps xmlcatalog is executing. -

del VALUE(S)

- Remove the catalog entry corresponding to VALUE(S). -

dump

Print the current catalog.

exit

Quit the shell.

public PUBLIC-ID

- Execute a Formal Public Identifier lookup of the catalog entry - for PUBLIC-ID. The corresponding entry will be - output to the command line. -

quiet

Stop printing debugging statements.

system SYSTEM-ID

- Execute a Formal Public Identifier lookup of the catalog entry - for SYSTEM-ID. The corresponding entry will be - output to the command line. -

ENVIRONMENT

XML_CATALOG_FILES

XML catalog behavior can be changed by redirecting - queries to the user's own set of catalogs. This can be done by setting - the XML_CATALOG_FILES environment variable to a space-separated - list of catalogs. Use percent-encoding to escape spaces or other characters. - An empty variable should deactivate loading the default catalog from - /etc/xml/catalog or, more specifically, - ${sysconfdir}/xml/catalog. -

DIAGNOSTICS

- xmlcatalog return codes provide information that can be used when - calling it from scripts. -

0

No error

1

Failed to remove an entry from the catalog

2

Failed to save to the catalog, check file permissions

3

Failed to add an entry to the catalog

4

Failed to look up an entry in the catalog

SEE ALSO

libxml(3) -

- More information can be found at -

-

diff --git a/doc/xmllint.1 b/doc/xmllint.1 deleted file mode 100644 index 267ff151..00000000 --- a/doc/xmllint.1 +++ /dev/null @@ -1,688 +0,0 @@ -'\" t -.\" Title: xmllint -.\" Author: John Fleck -.\" Generator: DocBook XSL Stylesheets vsnapshot -.\" Date: 03/27/2025 -.\" Manual: xmllint Manual -.\" Source: libxml2 -.\" Language: English -.\" -.TH "XMLLINT" "1" "03/27/2025" "libxml2" "xmllint Manual" -.\" ----------------------------------------------------------------- -.\" * Define some portability stuff -.\" ----------------------------------------------------------------- -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.\" http://bugs.debian.org/507673 -.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" ----------------------------------------------------------------- -.\" * set default formatting -.\" ----------------------------------------------------------------- -.\" disable hyphenation -.nh -.\" disable justification (adjust text to left margin only) -.ad l -.\" ----------------------------------------------------------------- -.\" * MAIN CONTENT STARTS HERE * -.\" ----------------------------------------------------------------- -.SH "NAME" -xmllint \- command line XML tool -.SH "SYNOPSIS" -.HP \w'\fBxmllint\fR\ 'u -\fBxmllint\fR [\fB\-\-version\fR | \fB\-\-debug\fR | \fB\-\-quiet\fR | \fB\-\-shell\fR | \fB\-\-xpath\ "\fR\fB\fIXPath_expression\fR\fR\fB"\fR | \fB\-\-debugent\fR | \fB\-\-copy\fR | \fB\-\-recover\fR | \fB\-\-huge\fR | \fB\-\-nocompact\fR | \fB\-\-nodefdtd\fR | \fB\-\-nodict\fR | \fB\-\-noenc\fR | \fB\-\-noent\fR | \fB\-\-nofixup\-base\-uris\fR | \fB\-\-noout\fR | \fB\-\-nonet\fR | \fB\-\-path\ "\fR\fB\fIPATH(S)\fR\fR\fB"\fR | \fB\-\-load\-trace\fR | \fB\-\-htmlout\fR | \fB\-\-nowrap\fR | \fB\-\-valid\fR | \fB\-\-postvalid\fR | \fB\-\-dtdvalid\ \fR\fB\fIURL\fR\fR | \fB\-\-dtdvalidfpi\ \fR\fB\fIFPI\fR\fR | \fB\-\-timing\fR | \fB\-\-output\ \fR\fB\fIFILE\fR\fR | \fB\-\-repeat\fR | \fB\-\-insert\fR | \fB\-\-compress\fR | \fB\-\-html\fR | \fB\-\-xmlout\fR | \fB\-\-push\fR | \fB\-\-memory\fR | \fB\-\-max\-ampl\ \fR\fB\fIINTEGER\fR\fR | \fB\-\-maxmem\ \fR\fB\fINBBYTES\fR\fR | \fB\-\-nowarning\fR | \fB\-\-noblanks\fR | \fB\-\-nocdata\fR | \fB\-\-format\fR | \fB\-\-pretty\ \fR\fB\fIINTEGER\fR\fR | \fB\-\-encode\ \fR\fB\fIENCODING\fR\fR | \fB\-\-dropdtd\fR | \fB\-\-nsclean\fR | \fB\-\-testIO\fR | \fB\-\-catalogs\fR | \fB\-\-nocatalogs\fR | \fB\-\-auto\fR | \fB\-\-xinclude\fR | \fB\-\-noxincludenode\fR | \fB\-\-loaddtd\fR | \fB\-\-dtdattr\fR | \fB\-\-stream\fR | \fB\-\-walker\fR | \fB\-\-pattern\ \fR\fB\fIPATTERNVALUE\fR\fR | \fB\-\-relaxng\ \fR\fB\fISCHEMA\fR\fR | \fB\-\-schema\ \fR\fB\fISCHEMA\fR\fR | \fB\-\-schematron\ \fR\fB\fISCHEMA\fR\fR | \fB\-\-c14n\fR | \fB\-\-c14n11\fR | \fB\-\-exc\-c14n\fR | \fB\-\-pedantic\fR | \fB\-\-sax\fR | \fB\-\-sax1\fR | \fB\-\-oldxml10\fR] {\fIXML\-FILE(S)\fR... | \-} -.SH "DESCRIPTION" -.PP -The -\fBxmllint\fR -program parses one or more -XML -files, specified on the command line as -\fIXML\-FILE\fR -(or the standard input if the filename provided is -\fB\-\fR -)\&. It prints various types of output, depending upon the options selected\&. It is useful for detecting errors both in -XML -code and in the -XML -parser itself\&. -.PP -\fBxmllint\fR -is included in -\fBlibxml\fR(3)\&. -.SH "OPTIONS" -.PP -\fBxmllint\fR -accepts the following options (in alphabetical order): -.PP -\fB\-\-auto\fR -.RS 4 -Generate a small document for testing purposes\&. -.RE -.PP -\fB\-\-catalogs\fR -.RS 4 -Use the -SGML -catalog(s) from -\fBSGML_CATALOG_FILES\fR\&. Otherwise -XML -catalogs starting from -/etc/xml/catalog -or, more specifically, -${sysconfdir}/xml/catalog -are used by default\&. -.RE -.PP -\fB\-\-compress\fR -.RS 4 -Turn on -\fBgzip\fR(1) -compression of output\&. -.RE -.PP -\fB\-\-copy\fR -.RS 4 -Test the internal copy implementation\&. -.RE -.PP -\fB\-\-c14n\fR, \fB\-\-c14n11\fR, \fB\-\-exc\-c14n\fR -.RS 4 -Use the W3C -XML -Canonicalisation (C14N) to serialize the result of parsing to -stdout\&. It keeps comments in the result\&. -.RE -.PP -\fB\-\-dtdvalid \fR\fB\fIURL\fR\fR -.RS 4 -Use the -DTD -specified by an -\fIURL\fR -for validation\&. -.RE -.PP -\fB\-\-dtdvalidfpi \fR\fB\fIFPI\fR\fR -.RS 4 -Use the -DTD -specified by a Formal Public Identifier -\fIFPI\fR -for validation, note that this will require a catalog exporting that Formal Public Identifier to work\&. -.RE -.PP -\fB\-\-debug\fR -.RS 4 -Parse a file and output an annotated tree of the in\-memory version of the document\&. -.RE -.PP -\fB\-\-debugent\fR -.RS 4 -Debug the entities defined in the document\&. -.RE -.PP -\fB\-\-dropdtd\fR -.RS 4 -Remove -DTD -from output\&. -.RE -.PP -\fB\-\-dtdattr\fR -.RS 4 -Fetch external -DTD -and populate the tree with inherited attributes\&. -.RE -.PP -\fB\-\-encode \fR\fB\fIENCODING\fR\fR -.RS 4 -Output in the given encoding\&. Note that this works for full document not fragments or result from XPath queries\&. -.RE -.PP -\fB\-\-format\fR -.RS 4 -Reformat and reindent the output\&. The -\fBXMLLINT_INDENT\fR -environment variable controls the indentation\&. The default value is two spaces " ")\&. -.sp -Especially in the absence of a DTD, this feature has never worked reliably and is fundamentally broken\&. -.RE -.PP -\fB\-\-html\fR -.RS 4 -Use the -HTML -parser\&. -.RE -.PP -\fB\-\-htmlout\fR -.RS 4 -Output results as an -HTML -file\&. This causes -\fBxmllint\fR -to output the necessary -HTML -tags surrounding the result tree output so the results can be displayed/viewed in a browser\&. -.RE -.PP -\fB\-\-huge\fR -.RS 4 -Ignore some hardcoded parser limits\&. -.RE -.PP -\fB\-\-insert\fR -.RS 4 -Test for valid insertions\&. -.RE -.PP -\fB\-\-loaddtd\fR -.RS 4 -Fetch an external -DTD\&. -.RE -.PP -\fB\-\-load\-trace\fR -.RS 4 -Display all the documents loaded during the processing to -stderr\&. -.RE -.PP -\fB\-\-max\-ampl \fR\fB\fIINTEGER\fR\fR -.RS 4 -Set the maximum amplification factor which protects against exponential entity expansion ("billion laughs")\&. The default value is 5\&. Documents making heavy use of entity expansion may require a higher value\&. -.RE -.PP -\fB\-\-maxmem \fR\fB\fINNBYTES\fR\fR -.RS 4 -Test the parser memory support\&. -\fINNBYTES\fR -is the maximum number of bytes the library is allowed to allocate\&. This can also be used to make sure batch processing of -XML -files will not exhaust the virtual memory of the server running them\&. -.RE -.PP -\fB\-\-memory\fR -.RS 4 -Parse from memory\&. -.RE -.PP -\fB\-\-noblanks\fR -.RS 4 -Drop ignorable blank spaces\&. -.RE -.PP -\fB\-\-nocatalogs\fR -.RS 4 -Do not use any catalogs\&. -.RE -.PP -\fB\-\-nocdata\fR -.RS 4 -Substitute CDATA section by equivalent text nodes\&. -.RE -.PP -\fB\-\-nocompact\fR -.RS 4 -Do not generate compact text nodes (parser option XML_PARSE_COMPACT)\&. Only for debugging\&. -.RE -.PP -\fB\-\-nodefdtd\fR -.RS 4 -Do not set default HTML doctype (parser option HTML_PARSE_NODEFDTD)\&. -.RE -.PP -\fB\-\-nodict\fR -.RS 4 -Don\*(Aqt use dictionaries (parser option XML_PARSE_NODICT)\&. Only for debugging\&. -.RE -.PP -\fB\-\-noenc\fR -.RS 4 -Ignore encoding declaration (parser option XML_PARSE_IGNORE_ENC)\&. -.RE -.PP -\fB\-\-noent\fR -.RS 4 -Substitute entity values for entity references\&. By default, -\fBxmllint\fR -leaves entity references in place\&. -.RE -.PP -\fB\-\-nofixup\-base\-uris\fR -.RS 4 -Don\*(Aqt fix xml:base URIs when processing XIncludes (parser option XML_PARSE_NOBASEFIX)\&. -.RE -.PP -\fB\-\-nonet\fR -.RS 4 -Do not use the Internet to fetch -DTDs or entities\&. -.RE -.PP -\fB\-\-noout\fR -.RS 4 -Suppress output\&. By default, -\fBxmllint\fR -outputs the result tree\&. -.RE -.PP -\fB\-\-nowarning\fR -.RS 4 -Do not emit warnings from the parser and/or validator\&. -.RE -.PP -\fB\-\-nowrap\fR -.RS 4 -Do not output -HTML -doc wrapper\&. -.RE -.PP -\fB\-\-noxincludenode\fR -.RS 4 -Do XInclude processing but do not generate XInclude start and end nodes\&. -.RE -.PP -\fB\-\-nsclean\fR -.RS 4 -Remove redundant namespace declarations\&. -.RE -.PP -\fB\-\-oldxml10\fR -.RS 4 -Use deprecated parsing rules before XML 1\&.0, 5th edition\&. -.RE -.PP -\fB\-\-output \fR\fB\fIFILE\fR\fR -.RS 4 -Define a file path where -\fBxmllint\fR -will save the result of parsing\&. Usually the programs build a tree and save it on -stdout, with this option the result -XML -instance will be saved onto a file\&. -.RE -.PP -\fB\-\-path "\fR\fB\fIPATH(S)\fR\fR\fB"\fR -.RS 4 -Use the (space\- or colon\-separated) list of filesystem paths specified by -\fIPATHS\fR -to load -DTDs or entities\&. Enclose space\-separated lists by quotation marks\&. -.RE -.PP -\fB\-\-pattern \fR\fB\fIPATTERNVALUE\fR\fR -.RS 4 -Used to exercise the pattern recognition engine, which can be used with the reader interface to the parser\&. It allows to select some nodes in the document based on an XPath (subset) expression\&. Used for debugging\&. -.RE -.PP -\fB\-\-pedantic\fR -.RS 4 -Enable additional warnings\&. -.RE -.PP -\fB\-\-postvalid\fR -.RS 4 -Validate after parsing has completed\&. -.RE -.PP -\fB\-\-pretty \fR\fB\fIINTEGER\fR\fR -.RS 4 -Value 0 means no formatting, 1 means XML_SAVE_FORMAT (same as \-\-format), 2 means XML_SAVE_WSNONSIG\&. -.RE -.PP -\fB\-\-push\fR -.RS 4 -Use the push mode of the parser\&. -.RE -.PP -\fB\-\-quiet\fR -.RS 4 -Don\*(Aqt print informational messages to stderr\&. -.RE -.PP -\fB\-\-recover\fR -.RS 4 -Output any parsable portions of an invalid document\&. -.RE -.PP -\fB\-\-relaxng \fR\fB\fISCHEMA\fR\fR -.RS 4 -Use RelaxNG file named -\fISCHEMA\fR -for validation\&. -.RE -.PP -\fB\-\-repeat\fR -.RS 4 -Repeat 100 times, for timing or profiling\&. -.RE -.PP -\fB\-\-sax\fR -.RS 4 -Print SAX callbacks (only for debugging)\&. -.RE -.PP -\fB\-\-sax1\fR -.RS 4 -Use deprecated SAX1 interface (only for debugging)\&. -.RE -.PP -\fB\-\-schema \fR\fB\fISCHEMA\fR\fR -.RS 4 -Use a W3C -XML -Schema file named -\fISCHEMA\fR -for validation\&. -.RE -.PP -\fB\-\-schematron \fR\fB\fISCHEMA\fR\fR -.RS 4 -Use a Schematron file named -\fISCHEMA\fR -for validation\&. -.RE -.PP -\fB\-\-shell\fR -.RS 4 -Run a navigating shell\&. Details on available commands in shell mode are below (see -the section called \(lqSHELL COMMANDS\(rq)\&. -.RE -.PP -\fB\-\-xpath "\fR\fB\fIXPath_expression\fR\fR\fB"\fR -.RS 4 -Run an XPath expression given as argument and print the result\&. In case of a nodeset result, each node in the node set is serialized in full in the output\&. In case of an empty node set the "XPath set is empty" result will be shown and exit code 11 will be returned\&.\&. This feature is EXPERIMENTAL\&. Implementation details can change without futher notice\&. -.RE -.PP -\fB\-\-stream\fR -.RS 4 -Use streaming -API -\- useful when used in combination with -\fB\-\-relaxng\fR -or -\fB\-\-valid\fR -options for validation of files that are too large to be held in memory\&. -.RE -.PP -\fB\-\-testIO\fR -.RS 4 -Test user input/output support\&. -.RE -.PP -\fB\-\-timing\fR -.RS 4 -Output information about the time it takes -\fBxmllint\fR -to perform the various steps\&. -.RE -.PP -\fB\-\-valid\fR -.RS 4 -Determine if the document is a valid instance of the included Document Type Definition (DTD)\&. A -DTD -to be validated against also can be specified at the command line using the -\fB\-\-dtdvalid\fR -option\&. By default, -\fBxmllint\fR -also checks to determine if the document is well\-formed\&. -.RE -.PP -\fB\-\-version\fR -.RS 4 -Display the version of -\fBlibxml\fR(3) -used\&. -.RE -.PP -\fB\-\-walker\fR -.RS 4 -Test the walker module, which is a reader interface but for a document tree, instead of using the reader -API -on an unparsed document it works on an existing in\-memory tree\&. Used for debugging\&. -.RE -.PP -\fB\-\-xinclude\fR -.RS 4 -Do XInclude processing\&. -.RE -.PP -\fB\-\-xmlout\fR -.RS 4 -Used in conjunction with -\fB\-\-html\fR\&. Usually when -HTML -is parsed the document is saved with the -HTML -serializer\&. But with this option the resulting document is saved with the -XML -serializer\&. This is primarily used to generate -XHTML -from -HTML -input\&. -.RE -.SH "SHELL COMMANDS" -.PP -\fBxmllint\fR -offers an interactive shell mode invoked with the -\fB\-\-shell\fR -command\&. Available commands in shell mode include (in alphabetical order): -.PP -\fBbase\fR -.RS 4 -Display -XML -base of the node\&. -.RE -.PP -\fBbye\fR -.RS 4 -Leave the shell\&. -.RE -.PP -\fBcat \fR\fB\fINODE\fR\fR -.RS 4 -Display the given node or the current one\&. -.RE -.PP -\fBcd \fR\fB\fIPATH\fR\fR -.RS 4 -Change the current node to the given path (if unique) or root if no argument is given\&. -.RE -.PP -\fBdir \fR\fB\fIPATH\fR\fR -.RS 4 -Dumps information about the node (namespace, attributes, content)\&. -.RE -.PP -\fBdu \fR\fB\fIPATH\fR\fR -.RS 4 -Show the structure of the subtree under the given path or the current node\&. -.RE -.PP -\fBexit\fR -.RS 4 -Leave the shell\&. -.RE -.PP -\fBhelp\fR -.RS 4 -Show this help\&. -.RE -.PP -\fBload \fR\fB\fIFILENAME\fR\fR -.RS 4 -Load a new document with the given filename\&. -.RE -.PP -\fBls \fR\fB\fIPATH\fR\fR -.RS 4 -List contents of the given path or the current directory\&. -.RE -.PP -\fBpwd\fR -.RS 4 -Display the path to the current node\&. -.RE -.PP -\fBquit\fR -.RS 4 -Leave the shell\&. -.RE -.PP -\fBsave \fR\fB\fIFILENAME\fR\fR -.RS 4 -Save the current document to the given filename or to the original name\&. -.RE -.PP -\fBvalidate\fR -.RS 4 -Check the document for errors\&. -.RE -.PP -\fBwrite \fR\fB\fIFILENAME\fR\fR -.RS 4 -Write the current node to the given filename\&. -.RE -.SH "ENVIRONMENT" -.PP -\fBSGML_CATALOG_FILES\fR -.RS 4 -SGML -catalog behavior can be changed by redirecting queries to the user\*(Aqs own set of catalogs\&. This can be done by setting the -\fBSGML_CATALOG_FILES\fR -environment variable to a list of catalogs\&. An empty one should deactivate loading the default catalog\&. -.RE -.PP -\fBXML_CATALOG_FILES\fR -.RS 4 -XML -catalog behavior can be changed by redirecting queries to the user\*(Aqs own set of catalogs\&. This can be done by setting the -\fBXML_CATALOG_FILES\fR -environment variable to a space\-separated list of catalogs\&. Use percent\-encoding to escape spaces or other characters\&. An empty variable should deactivate loading the default catalog\&. -.RE -.PP -\fBXML_DEBUG_CATALOG\fR -.RS 4 -Setting the environment variable -\fBXML_DEBUG_CATALOG\fR -to -\fInon\-zero\fR -using the -\fBexport\fR -command outputs debugging information related to catalog operations\&. -.RE -.PP -\fBXMLLINT_INDENT\fR -.RS 4 -Setting the environment variable -\fBXMLLINT_INDENT\fR -controls the indentation\&. The default value is two spaces " "\&. -.RE -.SH "DIAGNOSTICS" -.PP -\fBxmllint\fR -return codes provide information that can be used when calling it from scripts\&. -.PP -\fB0\fR -.RS 4 -No error -.RE -.PP -\fB1\fR -.RS 4 -Unclassified -.RE -.PP -\fB2\fR -.RS 4 -Error in -DTD -.RE -.PP -\fB3\fR -.RS 4 -Validation error -.RE -.PP -\fB4\fR -.RS 4 -Validation error -.RE -.PP -\fB5\fR -.RS 4 -Error in schema compilation -.RE -.PP -\fB6\fR -.RS 4 -Error writing output -.RE -.PP -\fB7\fR -.RS 4 -Error in pattern (generated when -\fB\-\-pattern\fR -option is used) -.RE -.PP -\fB9\fR -.RS 4 -Out of memory error -.RE -.PP -\fB10\fR -.RS 4 -XPath evaluation error -.RE -.PP -\fB11\fR -.RS 4 -XPath result is empty -.RE -.SH "SEE ALSO" -.PP -\fBlibxml\fR(3) -.PP -More information can be found at -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -\fBlibxml\fR(3) -web page -\m[blue]\fB\%https://gitlab.gnome.org/GNOME/libxml2\fR\m[] -.RE -.sp -.SH "AUTHORS" -.PP -\fBJohn Fleck\fR <\&jfleck@inkstain\&.net\&> -.RS 4 -Author. -.RE -.PP -\fBZiying Sherwin\fR <\&sherwin@nlm\&.nih\&.gov\&> -.RS 4 -Author. -.RE -.PP -\fBHeiko Rupp\fR <\&hwr@pilhuhn\&.de\&> -.RS 4 -Author. -.RE -.SH "COPYRIGHT" -.br -Copyright \(co 2001, 2004 -.br diff --git a/doc/xmllint.html b/doc/xmllint.html deleted file mode 100644 index d15528ae..00000000 --- a/doc/xmllint.html +++ /dev/null @@ -1,191 +0,0 @@ -xmllint

Name

xmllint — command line XML tool

Synopsis

xmllint [ --version | --debug | --quiet | --shell | --xpath "XPath_expression" | --debugent | --copy | --recover | --huge | --nocompact | --nodefdtd | --nodict | --noenc | --noent | --nofixup-base-uris | --noout | --nonet | --path "PATH(S)" | --load-trace | --htmlout | --nowrap | --valid | --postvalid | --dtdvalid URL | --dtdvalidfpi FPI | --timing | --output FILE | --repeat | --insert | --compress | --html | --xmlout | --push | --memory | --max-ampl INTEGER | --maxmem NBBYTES | --nowarning | --noblanks | --nocdata | --format | --pretty INTEGER | --encode ENCODING | --dropdtd | --nsclean | --testIO | --catalogs | --nocatalogs | --auto | --xinclude | --noxincludenode | --loaddtd | --dtdattr | --stream | --walker | --pattern PATTERNVALUE | --relaxng SCHEMA | --schema SCHEMA | --schematron SCHEMA | --c14n | --c14n11 | --exc-c14n | --pedantic | --sax | --sax1 | --oldxml10 ] { XML-FILE(S)... | - }

DESCRIPTION

- The xmllint program parses one or more XML files, - specified on the command line as XML-FILE - (or the standard input if the filename provided - is - ). It prints various types of - output, depending upon the options selected. It is useful for detecting - errors both in XML code and in - the XML parser itself. -

xmllint is included in libxml(3).

OPTIONS

- xmllint accepts the following options (in alphabetical order): -

--auto

Generate a small document for testing purposes.

--catalogs

- Use the SGML catalog(s) from SGML_CATALOG_FILES. - Otherwise XML catalogs starting - from /etc/xml/catalog or, more specifically, - ${sysconfdir}/xml/catalog are used by default. -

--compress

- Turn on gzip(1) compression of output. -

--copy

Test the internal copy implementation.

--c14n, --c14n11, --exc-c14n

- Use the W3C XML Canonicalisation (C14N) to - serialize the result of parsing to stdout. - It keeps comments in the result. -

--dtdvalid URL

- Use the DTD specified by - an URL for validation. -

--dtdvalidfpi FPI

- Use the DTD specified by a Formal Public - Identifier FPI for validation, note that this - will require a catalog exporting that Formal Public Identifier to work. -

--debug

- Parse a file and output an annotated tree of the - in-memory version of the document. -

--debugent

Debug the entities defined in the document.

--dropdtd

Remove DTD from output.

--dtdattr

- Fetch external DTD and populate the tree with - inherited attributes. -

--encode ENCODING

Output in the given encoding. Note that this works for full document not fragments or result from XPath queries.

--format

- Reformat and reindent the output. The XMLLINT_INDENT - environment variable controls the indentation. The default value is two - spaces " "). -

- Especially in the absence of a DTD, this feature has never worked reliably - and is fundamentally broken. -

--html

Use the HTML parser.

--htmlout

- Output results as an HTML file. This - causes xmllint to output the necessary HTML - tags surrounding the result tree output so the results can be - displayed/viewed in a browser. -

--huge

Ignore some hardcoded parser limits.

--insert

Test for valid insertions.

--loaddtd

Fetch an external DTD.

--load-trace

- Display all the documents loaded during the processing - to stderr. -

--max-ampl INTEGER

- Set the maximum amplification factor which protects against - exponential entity expansion ("billion laughs"). The default value - is 5. Documents making heavy use of entity expansion may require a - higher value. -

--maxmem NNBYTES

- Test the parser memory support. NNBYTES - is the maximum number of bytes the library is allowed to allocate. - This can also be used to make sure batch processing - of XML files will not exhaust the virtual memory - of the server running them. -

--memory

Parse from memory.

--noblanks

Drop ignorable blank spaces.

--nocatalogs

Do not use any catalogs.

--nocdata

Substitute CDATA section by equivalent text nodes.

--nocompact

- Do not generate compact text nodes (parser option - XML_PARSE_COMPACT). Only for debugging. -

--nodefdtd

- Do not set default HTML doctype (parser option - HTML_PARSE_NODEFDTD). -

--nodict

- Don't use dictionaries (parser option XML_PARSE_NODICT). - Only for debugging. -

--noenc

- Ignore encoding declaration (parser option - XML_PARSE_IGNORE_ENC). -

--noent

- Substitute entity values for entity references. By default, xmllint - leaves entity references in place. -

--nofixup-base-uris

- Don't fix xml:base URIs when processing XIncludes - (parser option XML_PARSE_NOBASEFIX). -

--nonet

- Do not use the Internet to fetch DTDs or entities. -

--noout

- Suppress output. By default, xmllint outputs the result tree. -

--nowarning

Do not emit warnings from the parser and/or validator.

--nowrap

Do not output HTML doc wrapper.

--noxincludenode

- Do XInclude processing but do not generate XInclude start and end nodes. -

--nsclean

Remove redundant namespace declarations.

--oldxml10

- Use deprecated parsing rules before XML 1.0, - 5th edition. -

--output FILE

- Define a file path where xmllint will save the result of parsing. - Usually the programs build a tree and save it - on stdout, with this option - the result XML instance will be saved onto a file. -

--path "PATH(S)"

- Use the (space- or colon-separated) list of filesystem paths specified - by PATHS to load DTDs or - entities. Enclose space-separated lists by quotation marks. -

--pattern PATTERNVALUE

- Used to exercise the pattern recognition engine, which can be used - with the reader interface to the parser. It allows to select some - nodes in the document based on an XPath (subset) expression. Used - for debugging. -

--pedantic

Enable additional warnings.

--postvalid

Validate after parsing has completed.

--pretty INTEGER

- Value 0 means no formatting, 1 means XML_SAVE_FORMAT - (same as --format), 2 means XML_SAVE_WSNONSIG. -

--push

Use the push mode of the parser.

--quiet

Don't print informational messages to stderr.

--recover

Output any parsable portions of an invalid document.

--relaxng SCHEMA

- Use RelaxNG file named SCHEMA - for validation. -

--repeat

Repeat 100 times, for timing or profiling.

--sax

Print SAX callbacks (only for debugging).

--sax1

Use deprecated SAX1 interface (only for debugging).

--schema SCHEMA

- Use a W3C XML Schema file - named SCHEMA for validation. -

--schematron SCHEMA

- Use a Schematron file - named SCHEMA for validation. -

--shell

- Run a navigating shell. Details on available commands in shell mode - are below (see the section called “SHELL COMMANDS”). -

--xpath "XPath_expression"

- Run an XPath expression given as argument and print the - result. In case of a nodeset result, each node in the - node set is serialized in full in the output. In case - of an empty node set the "XPath set is empty" result - will be shown and exit code 11 will be returned.. - This feature is EXPERIMENTAL. Implementation details can - change without futher notice. -

--stream

- Use streaming API - useful when used in combination - with --relaxng or --valid options - for validation of files that are too large to be held in memory. -

--testIO

Test user input/output support.

--timing

- Output information about the time it takes xmllint to perform the - various steps. -

--valid

- Determine if the document is a valid instance of the included - Document Type Definition (DTD). - A DTD to be validated against also can be - specified at the command line using the --dtdvalid - option. By default, xmllint also checks to determine if the - document is well-formed. -

--version

- Display the version of libxml(3) used. -

--walker

- Test the walker module, which is a reader interface but for a - document tree, instead of using the reader API on - an unparsed document it works on an existing in-memory tree. Used for - debugging. -

--xinclude

Do XInclude processing.

--xmlout

- Used in conjunction with --html. Usually - when HTML is parsed the document is saved with - the HTML serializer. But with this option the - resulting document is saved with the XML - serializer. This is primarily used to - generate XHTML from HTML input. -

SHELL COMMANDS

- xmllint offers an interactive shell mode invoked with - the --shell command. Available commands in shell mode - include (in alphabetical order): -

base

Display XML base of the node.

bye

Leave the shell.

cat NODE

Display the given node or the current one.

cd PATH

- Change the current node to the given path (if unique) or root if no - argument is given. -

dir PATH

- Dumps information about the node (namespace, attributes, content). -

du PATH

- Show the structure of the subtree under the given path or the current node. -

exit

Leave the shell.

help

Show this help.

load FILENAME

Load a new document with the given filename.

ls PATH

List contents of the given path or the current directory.

pwd

Display the path to the current node.

quit

Leave the shell.

save FILENAME

- Save the current document to the given filename or to the original name. -

validate

Check the document for errors.

write FILENAME

Write the current node to the given filename.

ENVIRONMENT

SGML_CATALOG_FILES

SGML catalog behavior can be changed by redirecting - queries to the user's own set of catalogs. This can be done by setting - the SGML_CATALOG_FILES environment variable to a list - of catalogs. An empty one should deactivate loading the - default catalog. -

XML_CATALOG_FILES

XML catalog behavior can be changed by redirecting - queries to the user's own set of catalogs. This can be done by setting - the XML_CATALOG_FILES environment variable to a space-separated - list of catalogs. Use percent-encoding to escape spaces or other characters. - An empty variable should deactivate loading the default catalog. -

XML_DEBUG_CATALOG

Setting the environment variable XML_DEBUG_CATALOG - to non-zero using the export - command outputs debugging information related to catalog operations. -

XMLLINT_INDENT

Setting the environment variable XMLLINT_INDENT - controls the indentation. The default value is two spaces " ". -

DIAGNOSTICS

- xmllint return codes provide information that can be used when - calling it from scripts. -

0

No error

1

Unclassified

2

Error in DTD

3

Validation error

4

Validation error

5

Error in schema compilation

6

Error writing output

7

- Error in pattern (generated when --pattern option is used) -

9

Out of memory error

10

XPath evaluation error

11

XPath result is empty

SEE ALSO

libxml(3) -

- More information can be found at -

-

diff --git a/meson.build b/meson.build index 26fd4c74..4e1306b8 100644 --- a/meson.build +++ b/meson.build @@ -28,6 +28,7 @@ dir_bin = dir_prefix / get_option('bindir') dir_include = dir_prefix / get_option('includedir') dir_pkginclude = dir_include / meson.project_name() dir_lib = dir_prefix / get_option('libdir') +dir_man = dir_prefix / get_option('mandir') dir_data = dir_prefix / get_option('datadir') dir_doc = dir_data / 'doc' / meson.project_name() dir_locale = dir_prefix / get_option('localedir') @@ -80,6 +81,7 @@ add_project_arguments(global_args, language: 'c') # options # disabled by default +want_docs = get_option('docs').enabled() want_http = get_option('http').enabled() want_icu = get_option('icu').enabled() want_legacy = get_option('legacy').enabled() @@ -450,13 +452,14 @@ foreach file : xml_opt_src endif endforeach +xml_src_files = files(xml_src) v_min_compat = 14 so_version = v_maj + v_min_compat age = v_min - v_min_compat darwin_compat = v_maj + v_min + 1 xml_lib = library( 'xml2', - files(xml_src), + xml_src_files, c_args: libxml2_cflags, dependencies: xml_deps, include_directories: config_dir, @@ -547,7 +550,11 @@ if sh.found() endif subdir('example') -subdir('doc') + +if want_docs or want_python + doxyfile = files('Doxyfile') + subdir('doc') +endif if want_python == true subdir('python') diff --git a/meson_options.txt b/meson_options.txt index 6530c823..c3c2d073 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -1,39 +1,3 @@ - -# AC_ARG_WITH / AC_ARG_ENABLE in configure.ac -# [X] c14n -# [X] catalog -# [X] debugging -# [X] history -# [X] html -# [X] http -# [X] iconv -# [X] icu - not minimum -# [X] iso8859x -# [X] legacy -# [X] lzma -# [X] modules -# [X] output -# [X] pattern -# [X] push -# [ ] python -# [X] reader -# [X] readline -# [X] regexps -# [X] sax1 -# [X] schemas -# [X] schematron -# [X] threads -# [X] thread-alloc -# [X] tls -# [X] valid -# [X] writer -# [X] xinclude -# [X] xpath -# [X] xptr -# [X] zlib - -# [X] minimum - option('c14n', type: 'feature', description: 'Canonical XML 1.0 support' @@ -49,6 +13,11 @@ option('debugging', description: 'Debugging module and shell' ) +option('docs', + type: 'feature', + description: 'Build documentation' +) + option('history', type: 'feature', description: 'History support for shell'