GNOME/libxml2
1
0
Fork 0
mirror of https://github.com/GNOME/libxml2.git synced 2025-05-07 20:39:30 +08:00
Code Issues Releases Wiki Activity

doc: Build docs with Doxygen and xsltproc

Browse Source 
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.
This commit is contained in:
Nick Wellnhofer 2025-04-28 17:21:05 +02:00
parent e525564f65
commit bbe5827c94
21 changed files with 375 additions and 1475 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitlab-ci.yml
View File

@ -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

8
.gitlab-ci/Dockerfile
View File

@ -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

2
.gitlab-ci/install.sh
View File

@ -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

2
.gitlab-ci/setup_mingw.sh
View File

@ -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

81
CMakeLists.txt
View File

@ -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

107
Doxyfile Normal file
View File

@ -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

37
MAINTAINERS.md
View File

@ -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

9
Makefile.am
View File

@ -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

7
NEWS
View File

@ -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

8
README.md
View File

@ -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

28
configure.ac
View File

@ -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

2
doc/.gitignore vendored Normal file
View File

@ -0,0 +1,2 @@
/html/
/xml/

53
doc/Makefile.am
View File

@ -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

9
doc/libxml2.css Normal file
View File

@ -0,0 +1,9 @@
div.contents {
max-width: 60em;
}
h1 {
font-size: 1.5em;
}
h2 {
font-size: 1.25em;
}

62
doc/meson.build
View File

@ -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

356
doc/xmlcatalog.1
View File

@ -1,356 +0,0 @@
'\" t
.\" Title: xmlcatalog
.\" Author: John Fleck <jfleck@inkstain.net>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" 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

144
doc/xmlcatalog.html
View File

@ -1,144 +0,0 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>xmlcatalog</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry"><a name="idm1"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>xmlcatalog &#8212;
Command line tool to parse and manipulate <acronym class="acronym">XML</acronym>
or <acronym class="acronym">SGML</acronym> catalog files.
</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">xmlcatalog</code> [ <code class="option">--sgml</code> | <code class="option">--shell</code> | <code class="option">--convert</code> | <code class="option">--create</code> | <code class="option">--del <em class="replaceable"><code>VALUE(S)</code></em></code> |
[
<code class="option">--add
<em class="replaceable"><code>TYPE</code></em>
<em class="replaceable"><code>ORIG</code></em>
<em class="replaceable"><code>REPLACE</code></em>
</code>
| <code class="option">--add <em class="replaceable"><code>FILENAME</code></em></code> ]
| <code class="option">--noout</code> | <code class="option">--no-super-update</code> |
[ <code class="option">-v</code> | <code class="option">--verbose</code> ]
] {<em class="replaceable"><code>CATALOGFILE</code></em>} {<em class="replaceable"><code>ENTITIES</code></em>...}</p></div></div><div class="refsect1"><a name="description"></a><h2>DESCRIPTION</h2><p>
<span class="command"><strong>xmlcatalog</strong></span> is a command line application allowing users to monitor and
manipulate <acronym class="acronym">XML</acronym> and <acronym class="acronym">SGML</acronym> catalogs. It
is included in <span class="citerefentry"><span class="refentrytitle">libxml</span>(3)</span>.
</p><p>
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 <acronym class="acronym">XML</acronym> and <acronym class="acronym">SGML</acronym> files.
</p></div><div class="refsect1"><a name="options"></a><h2>OPTIONS</h2><p>
<span class="command"><strong>xmlcatalog</strong></span> accepts the following options (in alphabetical order):
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">--add
<em class="replaceable"><code>TYPE</code></em>
<em class="replaceable"><code>ORIG</code></em>
<em class="replaceable"><code>REPLACE</code></em>
</code>
</span></dt><dd><p>
Add an entry to <code class="filename">CATALOGFILE</code>. <em class="replaceable"><code>TYPE</code></em>
indicates the type of entry. Possible types are: <span class="simplelist"><em class="parameter"><code>public</code></em>, <em class="parameter"><code>system</code></em>, <em class="parameter"><code>uri</code></em>, <em class="parameter"><code>rewriteSystem</code></em>, <em class="parameter"><code>rewriteURI</code></em>, <em class="parameter"><code>delegatePublic</code></em>, <em class="parameter"><code>delegateSystem</code></em>, <em class="parameter"><code>delegateURI</code></em>, <em class="parameter"><code>nextCatalog</code></em></span>. <em class="replaceable"><code>ORIG</code></em> is the original
reference to be replaced, and <em class="replaceable"><code>REPLACE</code></em>
is the <acronym class="acronym">URI</acronym> of the replacement entity to be
used. The <code class="option">--add</code> option will not overwrite
<code class="filename">CATALOGFILE</code>, outputting
to <code class="filename">stdout</code>, unless
<code class="option">--noout</code> is used. The <code class="option">--add</code> will
always take three parameters even if some of the <acronym class="acronym">XML</acronym>
catalog constructs will have only a single argument.
</p></dd><dt><span class="term"><code class="option">--add <em class="replaceable"><code>FILENAME</code></em></code></span></dt><dd><p>
If the <code class="option">--add</code> option is used following
the <code class="option">--sgml</code> option, only a single argument,
a <em class="replaceable"><code>FILENAME</code></em>, is used. This is used to add
the name of a catalog file to an <acronym class="acronym">SGML</acronym> supercatalog,
a file that contains references to other included <acronym class="acronym">SGML</acronym>
catalog files.
</p></dd><dt><span class="term"><code class="option">--convert</code></span></dt><dd><p>
Convert SGML catalog to XML.
</p></dd><dt><span class="term"><code class="option">--create</code></span></dt><dd><p>
Create a new <acronym class="acronym">XML</acronym> catalog. Outputs
to <code class="filename">stdout</code>,
ignoring <em class="replaceable"><code>filename</code></em> unless <code class="option">--noout</code> is
used, in which case it creates a new catalog
file <em class="replaceable"><code>filename</code></em>.
</p></dd><dt><span class="term"><code class="option">--del <em class="replaceable"><code>VALUE(S)</code></em></code></span></dt><dd><p>
Remove entries from <em class="replaceable"><code>CATALOGFILE</code></em>
matching <em class="replaceable"><code>VALUE(S)</code></em>. The <code class="option">--del</code>
option will not overwrite <em class="replaceable"><code>CATALOGFILE</code></em>,
outputting to <code class="filename">stdout</code>,
unless <code class="option">--noout</code> is used.
</p></dd><dt><span class="term"><code class="option">--noout</code></span></dt><dd><p>
Save output to the named file rather than outputting
to <code class="filename">stdout</code>.
</p></dd><dt><span class="term"><code class="option">--no-super-update</code></span></dt><dd><p>
Do not update the <acronym class="acronym">SGML</acronym> super catalog.
</p></dd><dt><span class="term"><code class="option">--shell</code></span></dt><dd><p>
Run a shell allowing interactive queries on catalog
file <em class="replaceable"><code>CATALOGFILE</code></em>. For the set of available
commands see <a class="xref" href="#shell" title="SHELL COMMANDS">the section called &#8220;SHELL COMMANDS&#8221;</a>.
</p></dd><dt><span class="term"><code class="option">--sgml</code></span></dt><dd><p>
Uses <acronym class="acronym">SGML</acronym> super catalogs for <code class="option">--add</code>
and <code class="option">--del</code> options.
</p></dd><dt><span class="term"><code class="option">-v</code>, </span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>Output debugging information.</p></dd></dl></div><p>
Invoking <span class="command"><strong>xmlcatalog</strong></span> non-interactively without a designated action
(imposed with options like <code class="option">--add</code>) will result in a lookup
of the catalog entry for <em class="replaceable"><code>ENTITIES</code></em> in the
catalog denoted with <em class="replaceable"><code>CATALOGFILE</code></em>. The
corresponding entries will be output to the command line. This mode of
operation, together with <code class="option">--shell</code> mode and non-modifying
(i.e. without <code class="option">--noout</code>) direct actions, allows for
a special shortcut of the void <em class="replaceable"><code>CATALOGFILE</code></em>
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.
</p></div><div class="refsect1"><a name="shell"></a><h2>SHELL COMMANDS</h2><p>
Invoking <span class="command"><strong>xmlcatalog</strong></span> with
the <code class="option">--shell <em class="replaceable"><code>CATALOGFILE</code></em></code> option opens
a command line shell allowing interactive access to the catalog file
identified by <em class="replaceable"><code>CATALOGFILE</code></em>. Invoking the shell
provides a command line prompt after which the following commands (described in
alphabetical order) can be entered.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">add
<em class="replaceable"><code>TYPE</code></em>
<em class="replaceable"><code>ORIG</code></em>
<em class="replaceable"><code>REPLACE</code></em>
</code>
</span></dt><dd><p>
Add an entry to the catalog file. <em class="replaceable"><code>TYPE</code></em>
indicates the type of entry. Possible types are: <span class="simplelist"><em class="parameter"><code>public</code></em>, <em class="parameter"><code>system</code></em>, <em class="parameter"><code>uri</code></em>, <em class="parameter"><code>rewriteSystem</code></em>, <em class="parameter"><code>rewriteURI</code></em>, <em class="parameter"><code>delegatePublic</code></em>, <em class="parameter"><code>delegateSystem</code></em>, <em class="parameter"><code>delegateURI</code></em>, <em class="parameter"><code>nextCatalog</code></em></span>. <em class="replaceable"><code>ORIG</code></em> is the original
reference to be replaced, and <em class="replaceable"><code>REPLACE</code></em>
is the <acronym class="acronym">URI</acronym> of the replacement entity to be
used. The <code class="option">--add</code> option will not overwrite
<code class="filename">CATALOGFILE</code>, outputting
to <code class="filename">stdout</code>, unless
<code class="option">--noout</code> is used. The <code class="option">--add</code> will
always take three parameters even if some of the <acronym class="acronym">XML</acronym>
catalog constructs will have only a single argument.
</p></dd><dt><span class="term"><code class="option">debug</code></span></dt><dd><p>
Print debugging statements showing the steps <span class="command"><strong>xmlcatalog</strong></span> is executing.
</p></dd><dt><span class="term"><code class="option">del <em class="replaceable"><code>VALUE(S)</code></em></code></span></dt><dd><p>
Remove the catalog entry corresponding to <em class="replaceable"><code>VALUE(S)</code></em>.
</p></dd><dt><span class="term"><code class="option">dump</code></span></dt><dd><p>Print the current catalog.</p></dd><dt><span class="term"><code class="option">exit</code></span></dt><dd><p>Quit the shell.</p></dd><dt><span class="term"><code class="option">public <em class="replaceable"><code>PUBLIC-ID</code></em></code></span></dt><dd><p>
Execute a Formal Public Identifier lookup of the catalog entry
for <em class="replaceable"><code>PUBLIC-ID</code></em>. The corresponding entry will be
output to the command line.
</p></dd><dt><span class="term"><code class="option">quiet</code></span></dt><dd><p>Stop printing debugging statements.</p></dd><dt><span class="term"><code class="option">system <em class="replaceable"><code>SYSTEM-ID</code></em></code></span></dt><dd><p>
Execute a Formal Public Identifier lookup of the catalog entry
for <em class="replaceable"><code>SYSTEM-ID</code></em>. The corresponding entry will be
output to the command line.
</p></dd></dl></div></div><div class="refsect1"><a name="environment"></a><h2>ENVIRONMENT</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">XML_CATALOG_FILES</code></span></dt><dd><p><acronym class="acronym">XML</acronym> catalog behavior can be changed by redirecting
queries to the user's own set of catalogs. This can be done by setting
the <code class="envar">XML_CATALOG_FILES</code> 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
<code class="filename">/etc/xml/catalog</code> or, more specifically,
<code class="filename">${sysconfdir}/xml/catalog</code>.
</p></dd></dl></div></div><div class="refsect1"><a name="diagnostics"></a><h2>DIAGNOSTICS</h2><p>
<span class="command"><strong>xmlcatalog</strong></span> return codes provide information that can be used when
calling it from scripts.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorcode">0</span></span></dt><dd><p>No error</p></dd><dt><span class="term"><span class="errorcode">1</span></span></dt><dd><p>Failed to remove an entry from the catalog</p></dd><dt><span class="term"><span class="errorcode">2</span></span></dt><dd><p>Failed to save to the catalog, check file permissions</p></dd><dt><span class="term"><span class="errorcode">3</span></span></dt><dd><p>Failed to add an entry to the catalog</p></dd><dt><span class="term"><span class="errorcode">4</span></span></dt><dd><p>Failed to look up an entry in the catalog</p></dd></dl></div></div><div class="refsect1"><a name="seealso"></a><h2>SEE ALSO</h2><p><span class="citerefentry"><span class="refentrytitle">libxml</span>(3)</span>
</p><p>
More information can be found at
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="citerefentry"><span class="refentrytitle">libxml</span>(3)</span> web page <a class="ulink" href="https://gitlab.gnome.org/GNOME/libxml2" target="_top">https://gitlab.gnome.org/GNOME/libxml2</a>
</p></li><li class="listitem"><p><span class="citerefentry"><span class="refentrytitle">libxml</span>(3)</span> catalog support web page
at <a class="ulink" href="https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support" target="_top">https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support</a>
</p></li><li class="listitem"><p>James Clark's <acronym class="acronym">SGML</acronym> catalog
page <a class="ulink" href="http://www.jclark.com/sp/catalog.htm" target="_top">http://www.jclark.com/sp/catalog.htm</a>
</p></li><li class="listitem"><p><acronym class="acronym">OASIS</acronym> <acronym class="acronym">XML</acronym> catalog specification
<a class="ulink" href="http://www.oasis-open.org/committees/entity/spec.html" target="_top">http://www.oasis-open.org/committees/entity/spec.html</a>
</p></li></ul></div><p>
</p></div></div></body></html>

688
doc/xmllint.1
View File

@ -1,688 +0,0 @@
'\" t
.\" Title: xmllint
.\" Author: John Fleck <jfleck@inkstain.net>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" 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

191
doc/xmllint.html
View File

@ -1,191 +0,0 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>xmllint</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry"><a name="id1337"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>xmllint &#8212; command line <acronym class="acronym">XML</acronym> tool</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">xmllint</code> [ <code class="option">--version</code> | <code class="option">--debug</code> | <code class="option">--quiet</code> | <code class="option">--shell</code> | <code class="option">--xpath "<em class="replaceable"><code>XPath_expression</code></em>"</code> | <code class="option">--debugent</code> | <code class="option">--copy</code> | <code class="option">--recover</code> | <code class="option">--huge</code> | <code class="option">--nocompact</code> | <code class="option">--nodefdtd</code> | <code class="option">--nodict</code> | <code class="option">--noenc</code> | <code class="option">--noent</code> | <code class="option">--nofixup-base-uris</code> | <code class="option">--noout</code> | <code class="option">--nonet</code> | <code class="option">--path "<em class="replaceable"><code>PATH(S)</code></em>"</code> | <code class="option">--load-trace</code> | <code class="option">--htmlout</code> | <code class="option">--nowrap</code> | <code class="option">--valid</code> | <code class="option">--postvalid</code> | <code class="option">--dtdvalid <em class="replaceable"><code>URL</code></em></code> | <code class="option">--dtdvalidfpi <em class="replaceable"><code>FPI</code></em></code> | <code class="option">--timing</code> | <code class="option">--output <em class="replaceable"><code>FILE</code></em></code> | <code class="option">--repeat</code> | <code class="option">--insert</code> | <code class="option">--compress</code> | <code class="option">--html</code> | <code class="option">--xmlout</code> | <code class="option">--push</code> | <code class="option">--memory</code> | <code class="option">--max-ampl <em class="replaceable"><code>INTEGER</code></em></code> | <code class="option">--maxmem <em class="replaceable"><code>NBBYTES</code></em></code> | <code class="option">--nowarning</code> | <code class="option">--noblanks</code> | <code class="option">--nocdata</code> | <code class="option">--format</code> | <code class="option">--pretty <em class="replaceable"><code>INTEGER</code></em></code> | <code class="option">--encode <em class="replaceable"><code>ENCODING</code></em></code> | <code class="option">--dropdtd</code> | <code class="option">--nsclean</code> | <code class="option">--testIO</code> | <code class="option">--catalogs</code> | <code class="option">--nocatalogs</code> | <code class="option">--auto</code> | <code class="option">--xinclude</code> | <code class="option">--noxincludenode</code> | <code class="option">--loaddtd</code> | <code class="option">--dtdattr</code> | <code class="option">--stream</code> | <code class="option">--walker</code> | <code class="option">--pattern <em class="replaceable"><code>PATTERNVALUE</code></em></code> | <code class="option">--relaxng <em class="replaceable"><code>SCHEMA</code></em></code> | <code class="option">--schema <em class="replaceable"><code>SCHEMA</code></em></code> | <code class="option">--schematron <em class="replaceable"><code>SCHEMA</code></em></code> | <code class="option">--c14n</code> | <code class="option">--c14n11</code> | <code class="option">--exc-c14n</code> | <code class="option">--pedantic</code> | <code class="option">--sax</code> | <code class="option">--sax1</code> | <code class="option">--oldxml10</code> ] { <em class="replaceable"><code>XML-FILE(S)</code></em>... | - }</p></div></div><div class="refsect1"><a name="description"></a><h2>DESCRIPTION</h2><p>
The <span class="command"><strong>xmllint</strong></span> program parses one or more <acronym class="acronym">XML</acronym> files,
specified on the command line as <em class="replaceable"><code>XML-FILE</code></em>
(or the standard input if the filename provided
is <span class="bold"><strong>-</strong></span> ). It prints various types of
output, depending upon the options selected. It is useful for detecting
errors both in <acronym class="acronym">XML</acronym> code and in
the <acronym class="acronym">XML</acronym> parser itself.
</p><p><span class="command"><strong>xmllint</strong></span> is included in <span class="citerefentry"><span class="refentrytitle">libxml</span>(3)</span>.</p></div><div class="refsect1"><a name="options"></a><h2>OPTIONS</h2><p>
<span class="command"><strong>xmllint</strong></span> accepts the following options (in alphabetical order):
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--auto</code></span></dt><dd><p>Generate a small document for testing purposes.</p></dd><dt><span class="term"><code class="option">--catalogs</code></span></dt><dd><p>
Use the <acronym class="acronym">SGML</acronym> catalog(s) from <code class="envar">SGML_CATALOG_FILES</code>.
Otherwise <acronym class="acronym">XML</acronym> catalogs starting
from <code class="filename">/etc/xml/catalog</code> or, more specifically,
<code class="filename">${sysconfdir}/xml/catalog</code> are used by default.
</p></dd><dt><span class="term"><code class="option">--compress</code></span></dt><dd><p>
Turn on <span class="citerefentry"><span class="refentrytitle">gzip</span>(1)</span> compression of output.
</p></dd><dt><span class="term"><code class="option">--copy</code></span></dt><dd><p>Test the internal copy implementation.</p></dd><dt><span class="term"><code class="option">--c14n</code>, </span><span class="term"><code class="option">--c14n11</code>, </span><span class="term"><code class="option">--exc-c14n</code></span></dt><dd><p>
Use the W3C <acronym class="acronym">XML</acronym> Canonicalisation (<acronym class="acronym">C14N</acronym>) to
serialize the result of parsing to <code class="filename">stdout</code>.
It keeps comments in the result.
</p></dd><dt><span class="term"><code class="option">--dtdvalid <em class="replaceable"><code>URL</code></em></code></span></dt><dd><p>
Use the <acronym class="acronym">DTD</acronym> specified by
an <em class="replaceable"><code>URL</code></em> for validation.
</p></dd><dt><span class="term"><code class="option">--dtdvalidfpi <em class="replaceable"><code>FPI</code></em></code></span></dt><dd><p>
Use the <acronym class="acronym">DTD</acronym> specified by a Formal Public
Identifier <em class="replaceable"><code>FPI</code></em> for validation, note that this
will require a catalog exporting that Formal Public Identifier to work.
</p></dd><dt><span class="term"><code class="option">--debug</code></span></dt><dd><p>
Parse a file and output an annotated tree of the
in-memory version of the document.
</p></dd><dt><span class="term"><code class="option">--debugent</code></span></dt><dd><p>Debug the entities defined in the document.</p></dd><dt><span class="term"><code class="option">--dropdtd</code></span></dt><dd><p>Remove <acronym class="acronym">DTD</acronym> from output.</p></dd><dt><span class="term"><code class="option">--dtdattr</code></span></dt><dd><p>
Fetch external <acronym class="acronym">DTD</acronym> and populate the tree with
inherited attributes.
</p></dd><dt><span class="term"><code class="option">--encode <em class="replaceable"><code>ENCODING</code></em></code></span></dt><dd><p>Output in the given encoding. Note that this works for full document not fragments or result from XPath queries.</p></dd><dt><span class="term"><code class="option">--format</code></span></dt><dd><p>
Reformat and reindent the output. The <code class="envar">XMLLINT_INDENT</code>
environment variable controls the indentation. The default value is two
spaces " ").
</p><p>
Especially in the absence of a DTD, this feature has never worked reliably
and is fundamentally broken.
</p></dd><dt><span class="term"><code class="option">--html</code></span></dt><dd><p>Use the <acronym class="acronym">HTML</acronym> parser.</p></dd><dt><span class="term"><code class="option">--htmlout</code></span></dt><dd><p>
Output results as an <acronym class="acronym">HTML</acronym> file. This
causes <span class="command"><strong>xmllint</strong></span> to output the necessary <acronym class="acronym">HTML</acronym>
tags surrounding the result tree output so the results can be
displayed/viewed in a browser.
</p></dd><dt><span class="term"><code class="option">--huge</code></span></dt><dd><p>Ignore some hardcoded parser limits.</p></dd><dt><span class="term"><code class="option">--insert</code></span></dt><dd><p>Test for valid insertions.</p></dd><dt><span class="term"><code class="option">--loaddtd</code></span></dt><dd><p>Fetch an external <acronym class="acronym">DTD</acronym>.</p></dd><dt><span class="term"><code class="option">--load-trace</code></span></dt><dd><p>
Display all the documents loaded during the processing
to <code class="filename">stderr</code>.
</p></dd><dt><span class="term"><code class="option">--max-ampl <em class="replaceable"><code>INTEGER</code></em></code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="option">--maxmem <em class="replaceable"><code>NNBYTES</code></em></code></span></dt><dd><p>
Test the parser memory support. <em class="replaceable"><code>NNBYTES</code></em>
is the maximum number of bytes the library is allowed to allocate.
This can also be used to make sure batch processing
of <acronym class="acronym">XML</acronym> files will not exhaust the virtual memory
of the server running them.
</p></dd><dt><span class="term"><code class="option">--memory</code></span></dt><dd><p>Parse from memory.</p></dd><dt><span class="term"><code class="option">--noblanks</code></span></dt><dd><p>Drop ignorable blank spaces.</p></dd><dt><span class="term"><code class="option">--nocatalogs</code></span></dt><dd><p>Do not use any catalogs.</p></dd><dt><span class="term"><code class="option">--nocdata</code></span></dt><dd><p>Substitute CDATA section by equivalent text nodes.</p></dd><dt><span class="term"><code class="option">--nocompact</code></span></dt><dd><p>
Do not generate compact text nodes (parser option
XML_PARSE_COMPACT). Only for debugging.
</p></dd><dt><span class="term"><code class="option">--nodefdtd</code></span></dt><dd><p>
Do not set default HTML doctype (parser option
HTML_PARSE_NODEFDTD).
</p></dd><dt><span class="term"><code class="option">--nodict</code></span></dt><dd><p>
Don't use dictionaries (parser option XML_PARSE_NODICT).
Only for debugging.
</p></dd><dt><span class="term"><code class="option">--noenc</code></span></dt><dd><p>
Ignore encoding declaration (parser option
XML_PARSE_IGNORE_ENC).
</p></dd><dt><span class="term"><code class="option">--noent</code></span></dt><dd><p>
Substitute entity values for entity references. By default, <span class="command"><strong>xmllint</strong></span>
leaves entity references in place.
</p></dd><dt><span class="term"><code class="option">--nofixup-base-uris</code></span></dt><dd><p>
Don't fix xml:base URIs when processing XIncludes
(parser option XML_PARSE_NOBASEFIX).
</p></dd><dt><span class="term"><code class="option">--nonet</code></span></dt><dd><p>
Do not use the Internet to fetch <acronym class="acronym">DTD</acronym>s or entities.
</p></dd><dt><span class="term"><code class="option">--noout</code></span></dt><dd><p>
Suppress output. By default, <span class="command"><strong>xmllint</strong></span> outputs the result tree.
</p></dd><dt><span class="term"><code class="option">--nowarning</code></span></dt><dd><p>Do not emit warnings from the parser and/or validator.</p></dd><dt><span class="term"><code class="option">--nowrap</code></span></dt><dd><p>Do not output <acronym class="acronym">HTML</acronym> doc wrapper.</p></dd><dt><span class="term"><code class="option">--noxincludenode</code></span></dt><dd><p>
Do XInclude processing but do not generate XInclude start and end nodes.
</p></dd><dt><span class="term"><code class="option">--nsclean</code></span></dt><dd><p>Remove redundant namespace declarations.</p></dd><dt><span class="term"><code class="option">--oldxml10</code></span></dt><dd><p>
Use deprecated parsing rules before XML 1.0,
5th edition.
</p></dd><dt><span class="term"><code class="option">--output <em class="replaceable"><code>FILE</code></em></code></span></dt><dd><p>
Define a file path where <span class="command"><strong>xmllint</strong></span> will save the result of parsing.
Usually the programs build a tree and save it
on <code class="filename">stdout</code>, with this option
the result <acronym class="acronym">XML</acronym> instance will be saved onto a file.
</p></dd><dt><span class="term"><code class="option">--path "<em class="replaceable"><code>PATH(S)</code></em>"</code></span></dt><dd><p>
Use the (space- or colon-separated) list of filesystem paths specified
by <em class="replaceable"><code>PATHS</code></em> to load <acronym class="acronym">DTD</acronym>s or
entities. Enclose space-separated lists by quotation marks.
</p></dd><dt><span class="term"><code class="option">--pattern <em class="replaceable"><code>PATTERNVALUE</code></em></code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="option">--pedantic</code></span></dt><dd><p>Enable additional warnings.</p></dd><dt><span class="term"><code class="option">--postvalid</code></span></dt><dd><p>Validate after parsing has completed.</p></dd><dt><span class="term"><code class="option">--pretty <em class="replaceable"><code>INTEGER</code></em></code></span></dt><dd><p>
Value 0 means no formatting, 1 means XML_SAVE_FORMAT
(same as --format), 2 means XML_SAVE_WSNONSIG.
</p></dd><dt><span class="term"><code class="option">--push</code></span></dt><dd><p>Use the push mode of the parser.</p></dd><dt><span class="term"><code class="option">--quiet</code></span></dt><dd><p>Don't print informational messages to stderr.</p></dd><dt><span class="term"><code class="option">--recover</code></span></dt><dd><p>Output any parsable portions of an invalid document.</p></dd><dt><span class="term"><code class="option">--relaxng <em class="replaceable"><code>SCHEMA</code></em></code></span></dt><dd><p>
Use RelaxNG file named <em class="replaceable"><code>SCHEMA</code></em>
for validation.
</p></dd><dt><span class="term"><code class="option">--repeat</code></span></dt><dd><p>Repeat 100 times, for timing or profiling.</p></dd><dt><span class="term"><code class="option">--sax</code></span></dt><dd><p>Print SAX callbacks (only for debugging).</p></dd><dt><span class="term"><code class="option">--sax1</code></span></dt><dd><p>Use deprecated SAX1 interface (only for debugging).</p></dd><dt><span class="term"><code class="option">--schema <em class="replaceable"><code>SCHEMA</code></em></code></span></dt><dd><p>
Use a W3C <acronym class="acronym">XML</acronym> Schema file
named <em class="replaceable"><code>SCHEMA</code></em> for validation.
</p></dd><dt><span class="term"><code class="option">--schematron <em class="replaceable"><code>SCHEMA</code></em></code></span></dt><dd><p>
Use a Schematron file
named <em class="replaceable"><code>SCHEMA</code></em> for validation.
</p></dd><dt><span class="term"><code class="option">--shell</code></span></dt><dd><p>
Run a navigating shell. Details on available commands in shell mode
are below (see <a class="xref" href="#shell" title="SHELL COMMANDS">the section called &#8220;SHELL COMMANDS&#8221;</a>).
</p></dd><dt><span class="term"><code class="option">--xpath "<em class="replaceable"><code>XPath_expression</code></em>"</code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="option">--stream</code></span></dt><dd><p>
Use streaming <acronym class="acronym">API</acronym> - useful when used in combination
with <code class="option">--relaxng</code> or <code class="option">--valid</code> options
for validation of files that are too large to be held in memory.
</p></dd><dt><span class="term"><code class="option">--testIO</code></span></dt><dd><p>Test user input/output support.</p></dd><dt><span class="term"><code class="option">--timing</code></span></dt><dd><p>
Output information about the time it takes <span class="command"><strong>xmllint</strong></span> to perform the
various steps.
</p></dd><dt><span class="term"><code class="option">--valid</code></span></dt><dd><p>
Determine if the document is a valid instance of the included
Document Type Definition (<acronym class="acronym">DTD</acronym>).
A <acronym class="acronym">DTD</acronym> to be validated against also can be
specified at the command line using the <code class="option">--dtdvalid</code>
option. By default, <span class="command"><strong>xmllint</strong></span> also checks to determine if the
document is well-formed.
</p></dd><dt><span class="term"><code class="option">--version</code></span></dt><dd><p>
Display the version of <span class="citerefentry"><span class="refentrytitle">libxml</span>(3)</span> used.
</p></dd><dt><span class="term"><code class="option">--walker</code></span></dt><dd><p>
Test the walker module, which is a reader interface but for a
document tree, instead of using the reader <acronym class="acronym">API</acronym> on
an unparsed document it works on an existing in-memory tree. Used for
debugging.
</p></dd><dt><span class="term"><code class="option">--xinclude</code></span></dt><dd><p>Do XInclude processing.</p></dd><dt><span class="term"><code class="option">--xmlout</code></span></dt><dd><p>
Used in conjunction with <code class="option">--html</code>. Usually
when <acronym class="acronym">HTML</acronym> is parsed the document is saved with
the <acronym class="acronym">HTML</acronym> serializer. But with this option the
resulting document is saved with the <acronym class="acronym">XML</acronym>
serializer. This is primarily used to
generate <acronym class="acronym">XHTML</acronym> from <acronym class="acronym">HTML</acronym> input.
</p></dd></dl></div></div><div class="refsect1"><a name="shell"></a><h2>SHELL COMMANDS</h2><p>
<span class="command"><strong>xmllint</strong></span> offers an interactive shell mode invoked with
the <code class="option">--shell</code> command. Available commands in shell mode
include (in alphabetical order):
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="command"><strong>base</strong></span></span></dt><dd><p>Display <acronym class="acronym">XML</acronym> base of the node.</p></dd><dt><span class="term"><span class="command"><strong>bye</strong></span></span></dt><dd><p>Leave the shell.</p></dd><dt><span class="term"><span class="command"><strong>cat <em class="replaceable"><code>NODE</code></em></strong></span></span></dt><dd><p>Display the given node or the current one.</p></dd><dt><span class="term"><span class="command"><strong>cd <em class="replaceable"><code>PATH</code></em></strong></span></span></dt><dd><p>
Change the current node to the given path (if unique) or root if no
argument is given.
</p></dd><dt><span class="term"><span class="command"><strong>dir <em class="replaceable"><code>PATH</code></em></strong></span></span></dt><dd><p>
Dumps information about the node (namespace, attributes, content).
</p></dd><dt><span class="term"><span class="command"><strong>du <em class="replaceable"><code>PATH</code></em></strong></span></span></dt><dd><p>
Show the structure of the subtree under the given path or the current node.
</p></dd><dt><span class="term"><span class="command"><strong>exit</strong></span></span></dt><dd><p>Leave the shell.</p></dd><dt><span class="term"><span class="command"><strong>help</strong></span></span></dt><dd><p>Show this help.</p></dd><dt><span class="term"><span class="command"><strong>load <em class="replaceable"><code>FILENAME</code></em></strong></span></span></dt><dd><p>Load a new document with the given filename.</p></dd><dt><span class="term"><span class="command"><strong>ls <em class="replaceable"><code>PATH</code></em></strong></span></span></dt><dd><p>List contents of the given path or the current directory.</p></dd><dt><span class="term"><span class="command"><strong>pwd</strong></span></span></dt><dd><p>Display the path to the current node.</p></dd><dt><span class="term"><span class="command"><strong>quit</strong></span></span></dt><dd><p>Leave the shell.</p></dd><dt><span class="term"><span class="command"><strong>save <em class="replaceable"><code>FILENAME</code></em></strong></span></span></dt><dd><p>
Save the current document to the given filename or to the original name.
</p></dd><dt><span class="term"><code class="option">validate</code></span></dt><dd><p>Check the document for errors.</p></dd><dt><span class="term"><span class="command"><strong>write <em class="replaceable"><code>FILENAME</code></em></strong></span></span></dt><dd><p>Write the current node to the given filename.</p></dd></dl></div></div><div class="refsect1"><a name="environment"></a><h2>ENVIRONMENT</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">SGML_CATALOG_FILES</code></span></dt><dd><p><acronym class="acronym">SGML</acronym> catalog behavior can be changed by redirecting
queries to the user's own set of catalogs. This can be done by setting
the <code class="envar">SGML_CATALOG_FILES</code> environment variable to a list
of catalogs. An empty one should deactivate loading the
default catalog.
</p></dd><dt><span class="term"><code class="envar">XML_CATALOG_FILES</code></span></dt><dd><p><acronym class="acronym">XML</acronym> catalog behavior can be changed by redirecting
queries to the user's own set of catalogs. This can be done by setting
the <code class="envar">XML_CATALOG_FILES</code> 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.
</p></dd><dt><span class="term"><code class="envar">XML_DEBUG_CATALOG</code></span></dt><dd><p>Setting the environment variable <code class="envar">XML_DEBUG_CATALOG</code>
to <em class="parameter"><code>non-zero</code></em> using the <span class="command"><strong>export</strong></span>
command outputs debugging information related to catalog operations.
</p></dd><dt><span class="term"><code class="envar">XMLLINT_INDENT</code></span></dt><dd><p>Setting the environment variable <code class="envar">XMLLINT_INDENT</code>
controls the indentation. The default value is two spaces " ".
</p></dd></dl></div></div><div class="refsect1"><a name="diagnostics"></a><h2>DIAGNOSTICS</h2><p>
<span class="command"><strong>xmllint</strong></span> return codes provide information that can be used when
calling it from scripts.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorcode">0</span></span></dt><dd><p>No error</p></dd><dt><span class="term"><span class="errorcode">1</span></span></dt><dd><p>Unclassified</p></dd><dt><span class="term"><span class="errorcode">2</span></span></dt><dd><p>Error in <acronym class="acronym">DTD</acronym></p></dd><dt><span class="term"><span class="errorcode">3</span></span></dt><dd><p>Validation error</p></dd><dt><span class="term"><span class="errorcode">4</span></span></dt><dd><p>Validation error</p></dd><dt><span class="term"><span class="errorcode">5</span></span></dt><dd><p>Error in schema compilation</p></dd><dt><span class="term"><span class="errorcode">6</span></span></dt><dd><p>Error writing output</p></dd><dt><span class="term"><span class="errorcode">7</span></span></dt><dd><p>
Error in pattern (generated when <code class="option">--pattern</code> option is used)
</p></dd><dt><span class="term"><span class="errorcode">9</span></span></dt><dd><p>Out of memory error</p></dd><dt><span class="term"><span class="errorcode">10</span></span></dt><dd><p>XPath evaluation error</p></dd><dt><span class="term"><span class="errorcode">11</span></span></dt><dd><p>XPath result is empty</p></dd></dl></div></div><div class="refsect1"><a name="seealso"></a><h2>SEE ALSO</h2><p><span class="citerefentry"><span class="refentrytitle">libxml</span>(3)</span>
</p><p>
More information can be found at
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="citerefentry"><span class="refentrytitle">libxml</span>(3)</span> web page <a class="ulink" href="https://gitlab.gnome.org/GNOME/libxml2" target="_top">https://gitlab.gnome.org/GNOME/libxml2</a>
</p></li></ul></div><p>
</p></div></div></body></html>

11
meson.build
View File

@ -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')

41
meson_options.txt
View File

@ -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'