Skip to content
Commits on Source (28)
Expand all Hide whitespace changes
Inline Side-by-side
ChangeLog deleted 100644 → 0
View file @ 8c79bbb4
This diff is collapsed.
INSTALL deleted 100644 → 0
View file @ 8c79bbb4
Installation Instructions
*************************
Copyright (C) 1994-1996, 1999-2002, 2004-2016 Free Software
Foundation, Inc.
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. This file is offered as-is,
without warranty of any kind.
Basic Installation
==================
Briefly, the shell command './configure && make && make install'
should configure, build, and install this package. The following
more-detailed instructions are generic; see the 'README' file for
instructions specific to this package. Some packages provide this
'INSTALL' file but do not implement all of the features documented
below. The lack of an optional feature in a given package is not
necessarily a bug. More recommendations for GNU packages can be found
in *note Makefile Conventions: (standards)Makefile Conventions.
The 'configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation. It uses
those values to create a 'Makefile' in each directory of the package.
It may also create one or more '.h' files containing system-dependent
definitions. Finally, it creates a shell script 'config.status' that
you can run in the future to recreate the current configuration, and a
file 'config.log' containing compiler output (useful mainly for
debugging 'configure').
It can also use an optional file (typically called 'config.cache' and
enabled with '--cache-file=config.cache' or simply '-C') that saves the
results of its tests to speed up reconfiguring. Caching is disabled by
default to prevent problems with accidental use of stale cache files.
If you need to do unusual things to compile the package, please try
to figure out how 'configure' could check whether to do them, and mail
diffs or instructions to the address given in the 'README' so they can
be considered for the next release. If you are using the cache, and at
some point 'config.cache' contains results you don't want to keep, you
may remove or edit it.
The file 'configure.ac' (or 'configure.in') is used to create
'configure' by a program called 'autoconf'. You need 'configure.ac' if
you want to change it or regenerate 'configure' using a newer version of
'autoconf'.
The simplest way to compile this package is:
1. 'cd' to the directory containing the package's source code and type
'./configure' to configure the package for your system.
Running 'configure' might take a while. While running, it prints
some messages telling which features it is checking for.
2. Type 'make' to compile the package.
3. Optionally, type 'make check' to run any self-tests that come with
the package, generally using the just-built uninstalled binaries.
4. Type 'make install' to install the programs and any data files and
documentation. When installing into a prefix owned by root, it is
recommended that the package be configured and built as a regular
user, and only the 'make install' phase executed with root
privileges.
5. Optionally, type 'make installcheck' to repeat any self-tests, but
this time using the binaries in their final installed location.
This target does not install anything. Running this target as a
regular user, particularly if the prior 'make install' required
root privileges, verifies that the installation completed
correctly.
6. You can remove the program binaries and object files from the
source code directory by typing 'make clean'. To also remove the
files that 'configure' created (so you can compile the package for
a different kind of computer), type 'make distclean'. There is
also a 'make maintainer-clean' target, but that is intended mainly
for the package's developers. If you use it, you may have to get
all sorts of other programs in order to regenerate files that came
with the distribution.
7. Often, you can also type 'make uninstall' to remove the installed
files again. In practice, not all packages have tested that
uninstallation works correctly, even though it is required by the
GNU Coding Standards.
8. Some packages, particularly those that use Automake, provide 'make
distcheck', which can by used by developers to test that all other
targets like 'make install' and 'make uninstall' work correctly.
This target is generally not run by end users.
Compilers and Options
=====================
Some systems require unusual options for compilation or linking that
the 'configure' script does not know about. Run './configure --help'
for details on some of the pertinent environment variables.
You can give 'configure' initial values for configuration parameters
by setting variables in the command line or in the environment. Here is
an example:
./configure CC=c99 CFLAGS=-g LIBS=-lposix
*Note Defining Variables::, for more details.
Compiling For Multiple Architectures
====================================
You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. To do this, you can use GNU 'make'. 'cd' to the
directory where you want the object files and executables to go and run
the 'configure' script. 'configure' automatically checks for the source
code in the directory that 'configure' is in and in '..'. This is known
as a "VPATH" build.
With a non-GNU 'make', it is safer to compile the package for one
architecture at a time in the source code directory. After you have
installed the package for one architecture, use 'make distclean' before
reconfiguring for another architecture.
On MacOS X 10.5 and later systems, you can create libraries and
executables that work on multiple system types--known as "fat" or
"universal" binaries--by specifying multiple '-arch' options to the
compiler but only a single '-arch' option to the preprocessor. Like
this:
./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
CPP="gcc -E" CXXCPP="g++ -E"
This is not guaranteed to produce working output in all cases, you
may have to build one architecture at a time and combine the results
using the 'lipo' tool if you have problems.
Installation Names
==================
By default, 'make install' installs the package's commands under
'/usr/local/bin', include files under '/usr/local/include', etc. You
can specify an installation prefix other than '/usr/local' by giving
'configure' the option '--prefix=PREFIX', where PREFIX must be an
absolute file name.
You can specify separate installation prefixes for
architecture-specific files and architecture-independent files. If you
pass the option '--exec-prefix=PREFIX' to 'configure', the package uses
PREFIX as the prefix for installing programs and libraries.
Documentation and other data files still use the regular prefix.
In addition, if you use an unusual directory layout you can give
options like '--bindir=DIR' to specify different values for particular
kinds of files. Run 'configure --help' for a list of the directories
you can set and what kinds of files go in them. In general, the default
for these options is expressed in terms of '${prefix}', so that
specifying just '--prefix' will affect all of the other directory
specifications that were not explicitly provided.
The most portable way to affect installation locations is to pass the
correct locations to 'configure'; however, many packages provide one or
both of the following shortcuts of passing variable assignments to the
'make install' command line to change installation locations without
having to reconfigure or recompile.
The first method involves providing an override variable for each
affected directory. For example, 'make install
prefix=/alternate/directory' will choose an alternate location for all
directory configuration variables that were expressed in terms of
'${prefix}'. Any directories that were specified during 'configure',
but not in terms of '${prefix}', must each be overridden at install time
for the entire installation to be relocated. The approach of makefile
variable overrides for each directory variable is required by the GNU
Coding Standards, and ideally causes no recompilation. However, some
platforms have known limitations with the semantics of shared libraries
that end up requiring recompilation when using this method, particularly
noticeable in packages that use GNU Libtool.
The second method involves providing the 'DESTDIR' variable. For
example, 'make install DESTDIR=/alternate/directory' will prepend
'/alternate/directory' before all installation names. The approach of
'DESTDIR' overrides is not required by the GNU Coding Standards, and
does not work on platforms that have drive letters. On the other hand,
it does better at avoiding recompilation issues, and works well even
when some directory options were not specified in terms of '${prefix}'
at 'configure' time.
Optional Features
=================
If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving 'configure' the
option '--program-prefix=PREFIX' or '--program-suffix=SUFFIX'.
Some packages pay attention to '--enable-FEATURE' options to
'configure', where FEATURE indicates an optional part of the package.
They may also pay attention to '--with-PACKAGE' options, where PACKAGE
is something like 'gnu-as' or 'x' (for the X Window System). The
'README' should mention any '--enable-' and '--with-' options that the
package recognizes.
For packages that use the X Window System, 'configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the 'configure' options '--x-includes=DIR' and
'--x-libraries=DIR' to specify their locations.
Some packages offer the ability to configure how verbose the
execution of 'make' will be. For these packages, running './configure
--enable-silent-rules' sets the default to minimal output, which can be
overridden with 'make V=1'; while running './configure
--disable-silent-rules' sets the default to verbose, which can be
overridden with 'make V=0'.
Particular systems
==================
On HP-UX, the default C compiler is not ANSI C compatible. If GNU CC
is not installed, it is recommended to use the following options in
order to use an ANSI C compiler:
./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
and if that doesn't work, install pre-built binaries of GCC for HP-UX.
HP-UX 'make' updates targets which have the same time stamps as their
prerequisites, which makes it generally unusable when shipped generated
files such as 'configure' are involved. Use GNU 'make' instead.
On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
parse its '<wchar.h>' header file. The option '-nodtk' can be used as a
workaround. If GNU CC is not installed, it is therefore recommended to
try
./configure CC="cc"
and if that doesn't work, try
./configure CC="cc -nodtk"
On Solaris, don't put '/usr/ucb' early in your 'PATH'. This
directory contains several dysfunctional programs; working variants of
these programs are available in '/usr/bin'. So, if you need '/usr/ucb'
in your 'PATH', put it _after_ '/usr/bin'.
On Haiku, software installed for all users goes in '/boot/common',
not '/usr/local'. It is recommended to use the following options:
./configure --prefix=/boot/common
Specifying the System Type
==========================
There may be some features 'configure' cannot figure out
automatically, but needs to determine by the type of machine the package
will run on. Usually, assuming the package is built to be run on the
_same_ architectures, 'configure' can figure that out, but if it prints
a message saying it cannot guess the machine type, give it the
'--build=TYPE' option. TYPE can either be a short name for the system
type, such as 'sun4', or a canonical name which has the form:
CPU-COMPANY-SYSTEM
where SYSTEM can have one of these forms:
OS
KERNEL-OS
See the file 'config.sub' for the possible values of each field. If
'config.sub' isn't included in this package, then this package doesn't
need to know the machine type.
If you are _building_ compiler tools for cross-compiling, you should
use the option '--target=TYPE' to select the type of system they will
produce code for.
If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with '--host=TYPE'.
Sharing Defaults
================
If you want to set default values for 'configure' scripts to share,
you can create a site shell script called 'config.site' that gives
default values for variables like 'CC', 'cache_file', and 'prefix'.
'configure' looks for 'PREFIX/share/config.site' if it exists, then
'PREFIX/etc/config.site' if it exists. Or, you can set the
'CONFIG_SITE' environment variable to the location of the site script.
A warning: not all 'configure' scripts look for a site script.
Defining Variables
==================
Variables not defined in a site shell script can be set in the
environment passed to 'configure'. However, some packages may run
configure again during the build, and the customized values of these
variables may be lost. In order to avoid this problem, you should set
them in the 'configure' command line, using 'VAR=value'. For example:
./configure CC=/usr/local2/bin/gcc
causes the specified 'gcc' to be used as the C compiler (unless it is
overridden in the site shell script).
Unfortunately, this technique does not work for 'CONFIG_SHELL' due to an
Autoconf limitation. Until the limitation is lifted, you can use this
workaround:
CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash
'configure' Invocation
======================
'configure' recognizes the following options to control how it
operates.
'--help'
'-h'
Print a summary of all of the options to 'configure', and exit.
'--help=short'
'--help=recursive'
Print a summary of the options unique to this package's
'configure', and exit. The 'short' variant lists options used only
in the top level, while the 'recursive' variant lists options also
present in any nested packages.
'--version'
'-V'
Print the version of Autoconf used to generate the 'configure'
script, and exit.
'--cache-file=FILE'
Enable the cache: use and save the results of the tests in FILE,
traditionally 'config.cache'. FILE defaults to '/dev/null' to
disable caching.
'--config-cache'
'-C'
Alias for '--cache-file=config.cache'.
'--quiet'
'--silent'
'-q'
Do not print messages saying which checks are being made. To
suppress all normal output, redirect it to '/dev/null' (any error
messages will still be shown).
'--srcdir=DIR'
Look for the package's source code in directory DIR. Usually
'configure' can determine that directory automatically.
'--prefix=DIR'
Use DIR as the installation prefix. *note Installation Names:: for
more details, including other options available for fine-tuning the
installation locations.
'--no-create'
'-n'
Run the configure checks, but stop before creating any output
files.
'configure' also accepts some other, not widely useful, options. Run
'configure --help' for more details.
MAINTAINERS 0 → 100644
View file @ 24bc2b64
# Primary Maintainer:
Shaun McCance
E-mail: shaunm@gnome.org
Userid: shaunm
Makefile.am deleted 100644 → 0
View file @ 8c79bbb4
SUBDIRS = templates tools xslt
EXTRA_DIST = COPYING.GPL
ChangeLog:
@if test -f $(top_srcdir)/.git/HEAD; then \
git log --stat > $@; \
fi
dist: ChangeLog
.PHONY: ChangeLog
Makefile.in deleted 100644 → 0
View file @ 8c79bbb4
This diff is collapsed.
NEWS
View file @ 24bc2b64
41.beta
=======
* Updates documentation (Andre Klapper)
* Updates to build files (Jan Tojnar)
40.0
====
* Stable release. No updates since 40.rc.
40.rc
=====
* Removed comment about revision version attrs from templates
* Use /usr/bin/python3 as shebang
40.beta
=======
* Added --skip option to skip files in yelp-check
* Custom checkers in yelp-check return 1 on failure
40.alpha
========
* First release using the meson build system
* Converted yelp-build, yelp-check, and yelp-new to python
* New and improved templates for yelp-new
* Support for .yelp-tools.cfg config file
* Config file can specify custom checkers, like Schematron but easier
* yelp-check hrefs takes a configurable allow list
3.38.0
======
* Stable release. No changes since 3.37.90
......
README
View file @ 24bc2b64
......@@ -8,6 +8,9 @@ wraps things up in a developer-friendly way.
ORGANIZATION
============
templates/
The templates directory contains page templates used by yelp-new.
tools/
The tools directory contains scripts like yelp-build and yelp-check,
as well as the yelp.m4 file that provides autotools integration.
......
aclocal.m4 deleted 100644 → 0
View file @ 8c79bbb4
This diff is collapsed.
configure deleted 100755 → 0
View file @ 8c79bbb4
This diff is collapsed.
configure.ac deleted 100644 → 0
View file @ 8c79bbb4
AC_INIT([yelp-tools], [3.38.0],
[http://bugzilla.gnome.org/enter_bug.cgi?product=yelp-tools])
AM_INIT_AUTOMAKE([1.9 no-dist-gzip dist-bzip2])
dnl In the interest of portability, we don't use GNU awk extensions,
dnl even though they rule. To prevent accidental use and subsequent
dnl bug reports after busted tarballs were shipped, we use -W compat
dnl whenever our awk is gawk.
AC_PROG_AWK
if test x$AWK = xgawk; then
GDU_AWK='gawk -W compat';
else
GDU_AWK=$AWK;
fi
AC_SUBST(GDU_AWK)
AC_PROG_LN_S
AC_CHECK_PROG(XMLLINT, xmllint, xmllint)
if test x"$XMLLINT" = x; then
AC_MSG_ERROR([xmllint not found])
fi
if test `$XMLLINT --version 2>&1 | head -n1 | cut -d' ' -f5` -lt 20612 ; then
AC_MSG_ERROR([xmllint too old; 2.6.12 required])
fi
AC_CHECK_PROG(XSLTPROC, xsltproc, xsltproc)
if test x"$XSLTPROC" = x; then
AC_MSG_ERROR([xsltproc not found])
fi
if test `$XSLTPROC --version 2>&1 | head -n1 | cut -d' ' -f5` -lt 10108 ; then
AC_MSG_ERROR([xsltproc too old; 1.1.8 required])
fi
AC_CHECK_PROG(ITSTOOL, itstool, itstool)
if test x"$ITSTOOL" = x; then
AC_MSG_ERROR([itstool not found])
fi
PKG_CHECK_MODULES(YELP_XSL,
[
yelp-xsl >= 3.17.3
])
XSL_PATH="`$PKG_CONFIG --variable=xsltdir yelp-xsl`"
DATADIR=`(
case $prefix in
NONE) prefix=$ac_default_prefix ;;
*) ;;
esac
eval echo $(eval echo $datadir)/yelp-tools
)`
AC_SUBST([DATADIR])
XSL_MAL_CACHE="$XSL_PATH""/mallard/cache/mal-cache.xsl"
AC_SUBST(XSL_MAL_CACHE)
XSL_MAL_LINK="$XSL_PATH""/mallard/common/mal-link.xsl"
AC_SUBST(XSL_MAL_LINK)
XSL_MAL_SORT="$XSL_PATH""/mallard/common/mal-sort.xsl"
AC_SUBST(XSL_MAL_SORT)
XSL_DB2HTML="`$PKG_CONFIG --variable=db2html yelp-xsl`"
AC_SUBST(XSL_DB2HTML)
XSL_DB2XHTML="`$PKG_CONFIG --variable=db2xhtml yelp-xsl`"
AC_SUBST(XSL_DB2XHTML)
XSL_MAL2HTML="`$PKG_CONFIG --variable=mal2html yelp-xsl`"
AC_SUBST(XSL_MAL2HTML)
XSL_MAL2XHTML="`$PKG_CONFIG --variable=mal2xhtml yelp-xsl`"
AC_SUBST(XSL_MAL2XHTML)
YELP_ICON_DIR="`$PKG_CONFIG --variable=icondir yelp-xsl`"/hicolor/24x24/status
AC_SUBST(YELP_ICON_DIR)
YELP_JS_DIR="`$PKG_CONFIG --variable=jsdir yelp-xsl`"
AC_SUBST(YELP_JS_DIR)
YELP_TMPL_DIR=`(
case $prefix in
NONE) prefix=$ac_default_prefix ;;
*) ;;
esac
eval echo $(eval echo $datadir)/yelp-tools/templates/
)`
AC_SUBST(YELP_TMPL_DIR)
AC_CONFIG_FILES([
Makefile
templates/Makefile
tools/Makefile
tools/yelp-build
tools/yelp-check
tools/yelp-new
xslt/Makefile
xslt/mal-ncx.xsl
xslt/mal-opf.xsl
])
AC_OUTPUT
help/C/index.page 0 → 100644
View file @ 24bc2b64
<page xmlns="http://projectmallard.org/1.0/"
type="guide"
id="index">
<info>
</info>
<title>Yelp Tools</title>
<p>The <sys>yelp-tools</sys> package contains small programs that help you
create, edit, manage, and publish your
<link href="http://projectmallard.org/">Mallard</link> or
<link href="http://docbook.org/">DocBook</link> documentation.</p>
</page>
help/C/yelp-build.page 0 → 100644
View file @ 24bc2b64
<page xmlns="http://projectmallard.org/1.0/"
id="yelp-build">
<info>
<link type="guide" xref="index"/>
<desc>Create HTML, EPUB, and other files from source documents.</desc>
</info>
<title><cmd>yelp-build</cmd></title>
<table>
<thead>
<tr>
<td><p>Command</p></td>
<td><p>Mallard</p></td>
<td><p>DocBook 4</p></td>
<td><p>DocBook 5</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p><cmd xref="#cache">yelp-build cache</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#epub">yelp-build epub</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#html">yelp-build html</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#html">yelp-build xhtml</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
</tbody>
</table>
<section id="cache">
<title><cmd>yelp-build cache</cmd></title>
<p>Create a <link href="http://projectmallard.org/cache/1.0/">Mallard cache
file</link> from a Mallard document. A cache file is necessary to build
other formats from Mallard documents. The other build commands generate a
cache file automatically, but sometimes it's useful to provide a cache file
explicitly. For example, if you only want to output the HTML for one page,
you might run:</p>
<screen>yelp-build html foo.page</screen>
<p>But then <cmd>yelp-build</cmd> will assume that <file>foo.page</file> is
the entirety of the document, and will create a cache file for just that page.
If you have a cache file with the cache for all pages, say <file>index.cache</file>,
you can instead run:</p>
<screen>yelp-build html -c index.cache foo.page</screen>
<p>You can pass <cmd>yelp-build cache</cmd> a list of page files, or just pass
it a directory to have it cache all page files in that directory.</p>
<screen>yelp-build cache *.page
yelp-build cache .</screen>
<p>By default, the output cache file name is index.cache. Use the <cmd>-o</cmd>
option to output a different file name.</p>
<screen>yelp-build cache -o foo.cache .</screen>
</section>
<section id="epub">
<title><cmd>yelp-build epub</cmd></title>
<p>Output an <link href="http://idpf.org/epub">EPUB</link> file, currently for
Mallard documents only. An EPUB file is a special zip file containing XHTML files,
stylesheets and other supporting files, and EPUB-specific files that specify the
document structure. You can pass <cmd>yelp-build epub</cmd> a list of page files,
or just pass it a directory to have it use all page files in that directory.</p>
<p>Just as for <cmd>yelp-build html</cmd> or <cmd>yelp-build xhtml</cmd>, you can
pass a custom cache file with the <cmd>-c</cmd> option, a customization stylesheet
with the <cmd>-x</cmd> option, a path for external files with the <cmd>-p</cmd>
option, and the option to ignore missing media files with <cmd>-i</cmd>. See the
documentation for <cmd>yelp-build html</cmd> for more information. Note that
setting URL roots for JavaScript, CSS, and icon files is usually not a good idea
for EPUB, because <cmd>yelp-build epub</cmd> places those files in a fixed
location inside the zip file.</p>
<p>By default, the output file name is <file>index.epub</file>. Use the <cmd>-o</cmd>
option to specify a different output file.</p>
</section>
<section id="html">
<title><cmd>yelp-build html</cmd></title>
<p>Output HTML files from a Mallard or DocBook document. The output file
names are taken from the IDs in the XML, regardless of the input file names.
For Mallard, you can pass <cmd>yelp-build html</cmd> a list of page files,
or just pass it a directory to have it create HTML for all page files in
that directory. For DocBook, pass the top-level XML file.</p>
<screen>
yelp-build html index.page foo.page bar.page
yelp-build html .
yelp-build html index.docbook
</screen>
<p>By default, files are output to the current working directory. Use the
<cmd>-o</cmd> option to specify an output directory.</p>
<screen>
mkdir html_out
yelp-build html -o html_out .
</screen>
<p>If you use the <cmd>-o</cmd> option, <cmd>yelp-build html</cmd> will also
copy media files to the output directory and create the appropriate directory
structure under the output directory. It will look inside the XML for tags
like <code>media</code> and <code>imagedata</code> to find media files to copy.</p>
<p>Sometimes, some media files and external resources are not under the same
path. This happens, for example, when you generate translated files in another
directory but don't create copies of untranslated files. Pass a path of other
base directories to use for files lookups with the <cmd>-p</cmd> option to
resolve these files.</p>
<p>If a referenced media file does not exist (potentially anywhere within the
path), <cmd>yelp-build</cmd> will still attempt to copy it, which will produce
warnings on stderr. To make <cmd>yelp-build</cmd> check for the file's existence
before copying, use the <cmd>-i</cmd> option. Be careful: without the warnings,
you could easily end up with broken images in your document.</p>
<p>For Mallard documents, a cache file is created for you by default from the
pages you pass on the command line. You can also pass a cache file explicitly
with the <cmd>-c</cmd> option. This is useful if you only want to rebuild a
few pages, but you want <cmd>yelp-build</cmd> to know about all the pages in
the document for linking purposes. See <cmd>yelp-build cache</cmd> above.</p>
<p>When creating HTML, <cmd>yelp-build</cmd> also outputs CSS and JavaScript
files, as well as PNG files for icons and watermarks. What it outputs depends
on what's in your document. For JavaScript, a static set of files are copied,
as well as additional JavaScript files for syntax highlighting. Which files
are copied depends on what syntaxes you use in program listings and code
blocks. For CSS, <cmd>yelp-build</cmd> creates a separate CSS file for each
top-level language. For icons and watermarks, which images are copied depends
on what types of admonitions and other elements you use.</p>
<p>The stylesheets that do the conversion to HTML are flexible and customizable.
You can add customizations to affect the layout and presentation. You can pass
a customization stylesheet to yelp-build html using the <cmd>-x</cmd> option.</p>
<screen>yelp-build html -x custom.xsl .</screen>
<p>The customization stylesheet should not include or import the Yelp stylesheets.
The <cmd>yelp-build</cmd> command will automatically create a wrapper stylesheet
that includes the customization and imports the Yelp stylesheets.</p>
<!--
For information
about the extension points and how to customize the stylesheets, see ?Yelp XSL.
-->
<p>The stylesheets allow you to specify URL roots for CSS, JavaScript, and icon
files. By default, it's the same directory as the output HTML files. You can
override these by setting parameters in a customization stylesheet, but
<cmd>yelp-build html</cmd> does not change where it outputs those files. If you
set these parameters to use common files on your web site, you must manage those
files manually.</p>
</section>
<section id="xhtml">
<title><cmd>yelp-build xhtml</cmd></title>
<p>Output XHTML files from a Mallard or DocBook document. This works exaclty
like the <cmd>yelp-build html</cmd> command and allows the same options, but
it serializes the files as XML. See the documentation for
<cmd>yelp-build html</cmd> for details.</p>
</section>
</page>
help/C/yelp-check.page 0 → 100644
View file @ 24bc2b64
<page xmlns="http://projectmallard.org/1.0/"
id="yelp-check">
<info>
<link type="guide" xref="index"/>
<desc>Validate documents, check link integrity, find orphaned
pages, and perform various other checks.</desc>
</info>
<title><cmd>yelp-check</cmd></title>
<table>
<thead>
<tr>
<td><p>Command</p></td>
<td><p>Mallard</p></td>
<td><p>DocBook 4</p></td>
<td><p>DocBook 5</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p><cmd xref="#comments">yelp-check comments</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#hrefs">yelp-check hrefs</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#ids">yelp-check ids</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#license">yelp-check license</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#links">yelp-check links</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#media">yelp-check media</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#orphans">yelp-check orphans</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#status">yelp-check status</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#validate">yelp-check validate</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
</tbody>
</table>
<section id="comments">
<title><cmd>yelp-check comments</cmd></title>
<p>Print the editorial comments in a Mallard or DocBook document. Both
Mallard and DocBook allow editors to embed remarks in a document that
are not normally shown when formatting the document. (These remarks
are displayed by Yelp when using the <cmd>--editor-mode</cmd> option.)
Mallard uses the <code>comment</code> element, and DocBook uses the
<code>remark</code> element.</p>
<p>For Mallard documents, you can pass <cmd>yelp-check comments</cmd>
a list of page files, or you can pass it a directory to process all
page files in that directory. For DocBook, you can pass any DocBook
file, including any well-formed files that are included in a top-level
file.</p>
<p>Mallard comments are printed with the enclosing page and section ID,
the author of the comment, and the date the comment was made. Mallard
comments allow any block content, but <cmd>yelp-check comments</cmd>
cannot format all block content in plain text. Any content that is not
in a <code>p</code> element currently results in a FIXME statement.</p>
<p>DocBook comments are printed with the closest enclosing ID and the
value of the <code>revisionflag</code> attribute.</p>
</section>
<section id="hrefs">
<title><cmd>yelp-check hrefs</cmd></title>
<p>Check the target of all external links in a Mallard or DocBook
document. For Mallard documents, <cmd>yelp-check hrefs</cmd> uses
all <code>href</code> attributes in the document. For DocBook
documents, it uses the <code>url</code> attribute of all
<code>ulink</code> elements as well as all <code>xlink:href</code>
attributes in the document. In both cases, <sys>mailto:</sys>
links are excluded.</p>
<p>For Mallard documents, you can pass <cmd>yelp-check hrefs</cmd>
a list of page files, or you can pass it a directory to process all
page files in that directory. For DocBook, you can pass any DocBook
file, including any well-formed files that are included in a top-level
file.</p>
<p>If a URL is relative, <cmd>yelp-check hrefs</cmd> checks for the
file locally. If a URL is absolute, it uses <cmd>curl</cmd> to check
the HTTP status of the resource.</p>
</section>
<section id="ids">
<title><cmd>yelp-check ids</cmd></title>
<p>Check if the <code>id</code> attributes of pages match the base
file name (without the <file>.page</file> extension) of the page
files they're defined in. It is not mandatory for them to match in
Mallard, but it's generally considered a best practice.</p>
</section>
<section id="license">
<title><cmd>yelp-check license</cmd></title>
<p>Report the license of Mallard page files, taken from the
<code>license</code> element. The license is reported based on
the <code>href</code> attribute. The block content of the
license element is not used at all. For certain known licenses
(such as those from GNU and Creative Commons), a shortened
identifier is shown instead of the full URL. If a license
element does not have an <code>href</code> attribute, it is
listed as unknown.</p>
<p>Pages may have multiple <code>license</code> elements. If
they do, the license identifiers will all be reported, joined
with a comma. If a page has no license element, it is reported
as none.</p>
<p>You can restrict which licenses are shown using the following
options:</p>
<terms>
<item>
<title><cmd>--only <var>LICENSES</var></cmd></title>
<p>Only show pages that have a license from the space-separated
list <var>LICENSES</var>.</p>
</item>
<item>
<title><cmd>--except <var>LICENSES</var></cmd></title>
<p>Only show pages that do not any license in the
space-separated list <var>LICENSES</var>.</p>
</item>
</terms>
<p>You can also get a summary of which licenses are in a document:</p>
<terms>
<item>
<title><cmd>--totals</cmd></title>
<p>Instead of the normal output of <output>"page: license"</output>,
print a list of licenses along with the number of pages that have
each license. All of the options above can still be used to filter
the pages that are used to calculate the totals.</p>
</item>
</terms>
</section>
<section id="media">
<title><cmd>yelp-check media</cmd></title>
<p>Check for references to external media files that do not exist. For
Mallard, <code>media</code>, <code>ui:thumb</code>, <code>uix:thumb</code>,
and <code>e:mouseover</code> elements are used. For DocBook, <code>audiodata</code>,
<code>imagedata</code>, and <code>videodata</code> elements are used.</p>
</section>
<section id="links">
<title><cmd>yelp-check links</cmd></title>
<p>Check the target of all internal links. For Mallard, all <code>xref</code>
attributes are used. For DocBook, all <code>linkend</code> attributes
are used. If the value does not correspond to an actual ID in the
document, <cmd>yelp-check links</cmd> prints the source and target
of the link.</p>
<p>For Mallard documents, you can pass <cmd>yelp-check links</cmd> a
list of page files, or you can pass it a directory to process all
page files in that directory. If you pass only a set of pages,
<code>yelp-check links</code> will only know about those pages,
and will report links as broken if they point to pages you did
not pass. However, you can create a cache file with
<cmd>yelp-build cache</cmd> that contains all the pages in the
document and pass this to <cmd>yelp-check</cmd> links with the
<cmd>-c</cmd> option.</p>
<p>Mallard allows links to provide both an <code>xref</code> and
an <code>href</code> attribute, and defines implementations to use
the <code>href</code> when the <code>xref</code> is not understood.
Use the <cmd>-i</cmd> option to ignore unknown <code>xref</code>
attributes when an <code>href</code> attribute is also present.</p>
<p>For DocBook, you can pass any DocBook file, including any
well-formed files that are included in a top-level file. However,
if you only check a file that is meant to be included in another
file, links will be reported as broken if they point to targets
outside that file or the files it includes.</p>
</section>
<section id="orphans">
<title><cmd>yelp-check orphans</cmd></title>
<p>Check for Mallard pages that cannot be reached by topic links.
You may still be able to reach the page by other links, but they
do not appear in the primary topic navigation of the document.</p>
<p>You can pass <cmd>yelp-check orphans</cmd> a list of page files,
or you can pass it a directory to process all page files in that
directory. If you pass only a set of pages, <cmd>yelp-check
orphans</cmd> will only know about those pages, and will probably
report many false positives. However, you can create a cache file
with <cmd>yelp-build cache</cmd> that contains all the pages in
the document and pass this to <cmd>yelp-check orphans</cmd> with
the <cmd>-c</cmd> option.</p>
</section>
<section id="status">
<title><cmd>yelp-check status</cmd></title>
<p>Report the status of Mallard page files, taken from the status
attribute of the revision elements for each page. You can pass a
list of page files, or pass a directory to process all page files
in that directory.</p>
<p>A page may have more than one revision element. When this happens,
<cmd>yelp-check status</cmd> filters the elements based on the
<code>version</code>, <code>docversion</code>, <code>pkgversion</code>,
and <code>date</code> attributes, depending on the arguments below.
It then sorts the <code>revision</code> elements primarily descending
by the <code>date</code> attribute, then by document order, and uses
the <code>status</code> attribute from the first. If the selected
<code>revision</code> element has no <code>status</code> attribute,
or if there are no matching revision elements, the status is
<code>"none"</code>.</p>
<terms>
<item>
<title><cmd>--version <var>VERSIONS</var></cmd></title>
<title><cmd>--docversion <var>VERSIONS</var></cmd></title>
<title><cmd>--pkgversion <var>VERSIONS</var></cmd></title>
<p>Only consider revision elements with a matching
<code>version</code>, <code>docversion</code>, or <code>pkgversion</code>
attribute, respectively. These options can be combined, and they
must all match. In all cases, <var>VERSIONS</var> can be a list
of versions separated by spaces or commas. The option matches if
any version matches the corresponding attribute.</p>
</item>
<item>
<title><cmd>--older <var>DATE</var></cmd></title>
<title><cmd>--newer <var>DATE</var></cmd></title>
<p>Only consider revision elements with a <code>date</code>
attribute that comes before (<cmd>--older</cmd>) or after
(<cmd>--newer</cmd>) the specified date. Dates are expected
to be in the form <sys>YYYY-MM-DD</sys>. These options may be
combined to specify a range the revision dates must fall in.</p>
</item>
</terms>
<p>There are also options that change what is output.</p>
<terms>
<item>
<title><cmd>--only <var>STATUSES</var></cmd></title>
<title><cmd>--except <var>STATUSES</var></cmd></title>
<p>After the status is determined as above, only print those
pages whose status matches (<cmd>--only</cmd>) or does not
match (<cmd>--except</cmd>) the specified statuses. In both
cases, <var>STATUSES</var> can be a list of statuses separated
by spaces or commas.</p>
</item>
<item>
<title><cmd>--totals</cmd></title>
<p>Instead of the normal output of <output>"page: status"</output>,
print a list of statuses along with the number of pages that
have each status. All of the options above can still be used
to filter the revision elements and to limit which statuses
the report on.</p>
</item>
</terms>
</section>
<section id="validate">
<title><cmd>yelp-check validate</cmd></title>
<p>Validate files against a DTD or RNG schema.</p>
<p>For Mallard documents, <cmd>yelp-check validate</cmd> implements
<link href="http://projectmallard.org/1.0/mal_attr_version">automatic
schema merging</link> based on the <code>version</code> attribute. If
there is no <code>version</code> attribute on a page, it is assumed
to be <code>"1.0"</code>, and the base Mallard 1.0 schema is used.</p>
<p>The Mallard schema allows elements and attributes from unknown
namespaces in many places, where the list of known namespaces is
built from the merged schemas. You can pass the <cmd>--strict</cmd>
option to disallow elements and attributes from unknown namespaces.
This is useful if you want to prevent unknown extensions.</p>
<terms>
<item>
<title><cmd>--strict</cmd></title>
<p>Disallow elements and attributes from namespaces that aren't
explicitly defined by the schemas imported based on the
<code>version</code> attribute.</p>
</item>
<item>
<title><cmd>--allow <var>NAMESPACE</var></cmd></title>
<p>When using strict validation, explicitly allow elements and
attributes from the namespace <var>NAMESPACE</var> in places
where any external-namespace nodes would normally be allowed.
You can pass the <cmd>--allow</cmd> option multiple times to
provide multiple namespaces that should be allowed.</p>
</item>
</terms>
<p>For DocBook 4, <cmd>yelp-check validate</cmd> uses the DTD set
by the <sys>DOCTYPE</sys>. If a document appears to be DocBook 4
but does not contain a DOCTYPE, the 4.5 DTD is used.</p>
<p>For DocBook 5, <cmd>yelp-check validate</cmd> selects an RNG
schema based on the <code>version</code> attribute.</p>
</section>
</page>
help/C/yelp-new.page 0 → 100644
View file @ 24bc2b64
<page xmlns="http://projectmallard.org/1.0/"
id="yelp-new">
<info>
<link type="guide" xref="index"/>
<desc>Easily create new documents and pages from template files.</desc>
</info>
<title><cmd>yelp-new</cmd></title>
<p>Create a new file from a template. You can quickly create a new
page or other file from a template. This is useful when many of your
pages have a common layout or structure. You must pass at least two
arguments: the identifier of the template, and the ID of the file to
create. The second argument is used both for the base file name of
the new file and for the id attribute. You can optionally pass a page
title as the third argument.</p>
<p>Template files can be installed with <cmd>yelp-new</cmd> or they
can be kept locally in the same directory. Local templates are useful
if you have common page styles that are specific to your project. To
get a list of available templates, run <cmd>yelp-new --help</cmd>.</p>
<p>You can create your own template files. Just create a file with the
<file>.tmpl</file> extension appended. You can also use the <cmd>--tmpl</cmd>
option on yelp-new to copy an existing template to the current directory
without substituting, allowing you to build off of it for your own template.</p>
<p>Output files are created by substituting special markers in the template.</p>
<terms>
<item>
<title><code>@ID@</code></title>
<p>The ID value passed as the second argument to yelp-new, which is
the same as the base file name of the output file.</p>
</item>
<item>
<title><code>@DATE@</code></title>
<p>The current date in the format <sys>YYYY-MM-DD</sys>.</p>
</item>
<item>
<title><code>@YEAR@</code></title>
<p>The current year in the format <sys>YYYY</sys>.</p>
</item>
<item>
<title><code>@NAME@</code></title>
<p>The name of the person running the command. This value may come
from either <cmd>git</cmd> or <cmd>bzr</cmd>. Failing that, the
value <code>"YOUR NAME"</code> is used.</p>
</item>
<item>
<title><code>@EMAIL@</code></title>
<p>The email address of the person running the command. This value
may come from either <cmd>git</cmd> or <cmd>bzr</cmd>. Failing that,
the value <code>"YOUR EMAIL ADDRESS"</code> is used.</p>
</item>
<item>
<title><code>@TITLE@</code></title>
<p>The title as passed as the third argument to <code>yelp-new</code>.
If you do not pass a title, the value <code>"TITLE"</code> is used.</p>
</item>
</terms>
<p>You can also pass the <cmd>--stub</cmd> option to create a
<file>.page.stub</file> file instead of a regular <file>.page</file> file.</p>
</page>
help/C/yelp.m4.page 0 → 100644
View file @ 24bc2b64
<page xmlns="http://projectmallard.org/1.0/"
xmlns:e="http://projectmallard.org/experimental/"
id="yelp.m4">
<info>
<link type="guide" xref="index"/>
<desc>Automatically manage documentation in an autotools+make
build environment.</desc>
</info>
<title><file>yelp.m4</file></title>
<p>The <sys>yelp-tools</sys> package contains build utilities that help you build
and install your help files according to the
<link href="http://www.freedesktop.org/wiki/Specifications/help-spec/">freedesktop.org
help specification</link>. The freedesktop.org help specification was jointly
created by GNOME and KDE developers to create a single help system that all
desktop environments use. To date, Yelp is the only implementation.</p>
<p>The build utilities are contained in a single file, <file>yelp.m4</file>.
To use it, add the following to your <file>configure.ac</file> file:</p>
<code>YELP_HELP_INIT</code>
<p>You can also pass a space-separated list of options as the first argument
to <code>YELP_HELP_INIT</code>:</p>
<code>YELP_HELP_INIT([<var>options...</var>])</code>
<p>The following options are currently recognized:</p>
<terms>
<item>
<title><code>no-lc-media-links</code></title>
<p>Normally, the build utilies create symlinks for localized media
files when translators have not provided an actual localization.
This means that copies of media files always exist in each locale's
directory, even if there is no translation. Passing the
<code>no-lc-media-links</code> option suppresses these symlinks.</p>
<p>For normal images and videos, Yelp is able to look up files
according to a document search path, so the symlinks are actually
unnecessary. This has been true since at least Yelp 3.0. If you are
only installing images and videos that are embedded in pages, use
this option. If you use HELP_MEDIA for other types of files, such
as source code or other files that get linked to, only use this
option if you have verified that it works in production.</p>
<p><e:hi>Added in 3.12</e:hi></p>
</item>
<item>
<title><code>no-lc-dist</code></title>
<p>Normally, the build utilities dist the generated translated files,
including the localized copies of <code>HELP_FILES</code> output by
<cmd>itstool</cmd> and the stamp file used for tracking when the
localized files were built. Using the <code>no-lc-dist</code> option
makes these generated files not be included in the tarball. This
reduces the size of the tarball, but increases the time it takes
to build from the tarball.</p>
<note>
<p>Note that currently, help.gnome.org does not use any sort of
build system, and only uses files found in tarballs. If you use
<code>no-lc-dist</code>, translations of your documents will not
show up correctly on help.gnome.org or any other site that uses
the same code.</p>
</note>
<p><e:hi>Added in 3.12</e:hi></p>
</item>
</terms>
<p>By default, the help directory is <file><var>$PREFIX</var>/help</file>,
and each language is installed to
<file><var>$PREFIX</var>/help/<var>$LANG</var>/<var>$HELP_ID</var>/</file>.
The build utilities automatically provide a configure option
<cmd>--with-help-dir</cmd>, allowing users to override the help directory.</p>
<p>The build utilities expect a layout that looks something like this:</p>
<tree>
<item>
<file>help/</file>
<item><file>Makefile.am</file></item>
<item>
<file>C/</file>
<item><var>help files...</var></item>
<item>
<file>media/</file>
<item><var>help media files...</var></item>
</item>
</item>
<item>
<file>ll/</file>
<item><file>ll.po</file></item>
<item>
<file>media/</file>
<item><var>help media files for ll...</var></item>
</item>
</item>
</item>
</tree>
<p>There is a single <file>Makefile.am</file> file in the help directory
that manages all translations. The help directory can have any name, or
be arbitrarily deep. For projects with a single help document, it's common
to simply use a top-level help directory.</p>
<p>The source files are expected to be in a directory called <file>C</file>.
It's common to put images, videos, and other non-XML files in a subdirectory
called <file>media</file> or <file>figures</file>. The actual name of the
subdirectory doesn't matter, but examples on this page will use <file>media</file>.</p>
<p>Each translation has its own directory named according to the locale.
That directory contains a PO file also named according to the locale.
The name of the directory must match the base name of the PO file. For
media files (those not translated using the PO files), translators add
localized files using the same names and directory layout as the source
files. If a media file does not need to be localized, you do not need to
copy it. The build utilities take care of this automatically.</p>
<p>The Makefile.am file must start with the following line:</p>
<code>@YELP_HELP_RULES@</code>
<p>You can set the following variables:</p>
<terms>
<item>
<title><code>HELP_ID</code></title>
<p>The ID of the help document. This determines the install location,
and will be referenced in the <sys>help:</sys> URIs used in your
application. This variable is required.</p>
</item>
<item>
<title><code>HELP_POT</code></title>
<p>A file name for a POT file to create when running <cmd>make pot</cmd>.
This variable is optional. It defaults to <file><var>${HELP_ID}</var>.pot</file>.
Note that <cmd>make pot</cmd> is not run as part of <cmd>make</cmd>. This
is useful for Mallard page sets that are designed to merge into another
document with the same <code>HELP_ID</code>. If <cmd>make pot</cmd> is
used to generate a POT file for an external translation tool, that tool
may expect POT file names to be globally unique.</p>
</item>
<item>
<title><code>HELP_FILES</code></title>
<p>A space-separated list of the primary XML files. These files will be
translated using the PO files and localized versions will be output when
running <cmd>make</cmd>. This variable is appropriate for Mallard page
files, top-level DocBook files, and any XML files that are included with
XInclude. All files listed in <code>HELP_FILES</code> must be well-formed
XML. List all files relative to the C directory.</p>
<note>
<p>Because of the way <file>yelp.m4</file> calls <cmd>itstool</cmd>,
currently files in HELP_FILES must be directly in the <file>C</file>
directory, not a subdirectory. If you use a subdirectory, the directory
structure will not be reproduced in translations. See
<link href="https://gitlab.gnome.org/GNOME/yelp-tools/-/issues/7">bug 7</link>.</p>
</note>
</item>
<item>
<title><code>HELP_EXTRA</code></title>
<p>A space-separated list of files that are disted and installed for
<file>C</file>, but are not in any way localized. This variable is
appropriate for XML files that are included with <code>SYSTEM</code>
entities and text files included with XInclude. These types of files
are merged by default by <cmd>itstool</cmd> when creating PO files,
so they are redundant in localizations. List all files relative to
the <file>C</file> directory.</p>
</item>
<item>
<title><code>HELP_MEDIA</code></title>
<p>A space-separated list of files that are disted and installed for
<file>C</file>, and which translators may create localized copies of.
If translators do not create localized copies, the build utilities
automatically create symlinks to the <file>C</file> files on <cmd>make
install</cmd>, unless you pass the <code>no-lc-media-links</code>
option to <code>YELP_HELP_INIT</code>. This variable is appropriate
for images, videos, and any external files that are linked to within
the help. List all files relative to the <file>C</file> directory.</p>
</item>
<item>
<title><code>HELP_LINGUAS</code></title>
<p>A space-separated list of locales that are enabled. The build
utilities will only use translations listed in this variable.</p>
</item>
</terms>
<p>The build utilities automatically handle <cmd>make</cmd>, <cmd>make
install</cmd>, <cmd>make uninstall</cmd>, and <cmd>make dist</cmd>.
Additionally, the following make targets are handled:</p>
<terms>
<item>
<title><cmd>make check</cmd></title>
<p>When running the standard <cmd>make check</cmd> target, all
files in <code>HELP_FILES</code> are checked for well-formedness
using <cmd>xmllint</cmd>. Note that <cmd>make check</cmd> does
not automatically do validation against schemas.</p>
</item>
<item>
<title><cmd>make pot</cmd></title>
<p>Create POT file using <cmd>itstool</cmd> from the files in
<code>HELP_FILES</code>. The name of the POT file can be specified
by the <code>HELP_POT</code> variable, and defaults to
<file><var>${HELP_ID}</var>.pot</file>. This is not called as part
of <cmd>make all</cmd>. However, some projects store the POT file
in version control, even though it's auto-generated, so that it
can easily be picked up by online translation tools. If you do
this, it's a good idea to make the all target depends on
<cmd>pot</cmd>.</p>
</item>
<item>
<title><cmd>make repo</cmd></title>
<p>Updates all the languages' PO files using the latest sources.
This is not called as part of <cmd>make all</cmd>.</p>
</item>
</terms>
</page>
help/meson.build 0 → 100644
View file @ 24bc2b64
yelp_tools_help_sources = [
'index.page',
'yelp-build.page',
'yelp-check.page',
'yelp-new.page',
'yelp.m4.page',
]
gnome.yelp(
package_name,
sources: yelp_tools_help_sources,
)
\ No newline at end of file
install-sh deleted 100755 → 0
View file @ 8c79bbb4
#!/bin/sh
# install - install a program, script, or datafile
scriptversion=2018-03-11.20; # UTC
# This originates from X11R5 (mit/util/scripts/install.sh), which was
# later released in X11R6 (xc/config/util/install.sh) with the
# following copyright and license.
#
# Copyright (C) 1994 X Consortium
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
# AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNEC-
# TION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the name of the X Consortium shall not
# be used in advertising or otherwise to promote the sale, use or other deal-
# ings in this Software without prior written authorization from the X Consor-
# tium.
#
#
# FSF changes to this file are in the public domain.
#
# Calling this script install-sh is preferred over install.sh, to prevent
# 'make' implicit rules from creating a file called install from it
# when there is no Makefile.
#
# This script is compatible with the BSD install script, but was written
# from scratch.
tab=' '
nl='
'
IFS=" $tab$nl"
# Set DOITPROG to "echo" to test this script.
doit=${DOITPROG-}
doit_exec=${doit:-exec}
# Put in absolute file names if you don't have them in your path;
# or use environment vars.
chgrpprog=${CHGRPPROG-chgrp}
chmodprog=${CHMODPROG-chmod}
chownprog=${CHOWNPROG-chown}
cmpprog=${CMPPROG-cmp}
cpprog=${CPPROG-cp}
mkdirprog=${MKDIRPROG-mkdir}
mvprog=${MVPROG-mv}
rmprog=${RMPROG-rm}
stripprog=${STRIPPROG-strip}
posix_mkdir=
# Desired mode of installed file.
mode=0755
chgrpcmd=
chmodcmd=$chmodprog
chowncmd=
mvcmd=$mvprog
rmcmd="$rmprog -f"
stripcmd=
src=
dst=
dir_arg=
dst_arg=
copy_on_change=false
is_target_a_directory=possibly
usage="\
Usage: $0 [OPTION]... [-T] SRCFILE DSTFILE
or: $0 [OPTION]... SRCFILES... DIRECTORY
or: $0 [OPTION]... -t DIRECTORY SRCFILES...
or: $0 [OPTION]... -d DIRECTORIES...
In the 1st form, copy SRCFILE to DSTFILE.
In the 2nd and 3rd, copy all SRCFILES to DIRECTORY.
In the 4th, create DIRECTORIES.
Options:
--help display this help and exit.
--version display version info and exit.
-c (ignored)
-C install only if different (preserve the last data modification time)
-d create directories instead of installing files.
-g GROUP $chgrpprog installed files to GROUP.
-m MODE $chmodprog installed files to MODE.
-o USER $chownprog installed files to USER.
-s $stripprog installed files.
-t DIRECTORY install into DIRECTORY.
-T report an error if DSTFILE is a directory.
Environment variables override the default commands:
CHGRPPROG CHMODPROG CHOWNPROG CMPPROG CPPROG MKDIRPROG MVPROG
RMPROG STRIPPROG
"
while test $# -ne 0; do
case $1 in
-c) ;;
-C) copy_on_change=true;;
-d) dir_arg=true;;
-g) chgrpcmd="$chgrpprog $2"
shift;;
--help) echo "$usage"; exit $?;;
-m) mode=$2
case $mode in
*' '* | *"$tab"* | *"$nl"* | *'*'* | *'?'* | *'['*)
echo "$0: invalid mode: $mode" >&2
exit 1;;
esac
shift;;
-o) chowncmd="$chownprog $2"
shift;;
-s) stripcmd=$stripprog;;
-t)
is_target_a_directory=always
dst_arg=$2
# Protect names problematic for 'test' and other utilities.
case $dst_arg in
-* | [=\(\)!]) dst_arg=./$dst_arg;;
esac
shift;;
-T) is_target_a_directory=never;;
--version) echo "$0 $scriptversion"; exit $?;;
--) shift
break;;
-*) echo "$0: invalid option: $1" >&2
exit 1;;
*) break;;
esac
shift
done
# We allow the use of options -d and -T together, by making -d
# take the precedence; this is for compatibility with GNU install.
if test -n "$dir_arg"; then
if test -n "$dst_arg"; then
echo "$0: target directory not allowed when installing a directory." >&2
exit 1
fi
fi
if test $# -ne 0 && test -z "$dir_arg$dst_arg"; then
# When -d is used, all remaining arguments are directories to create.
# When -t is used, the destination is already specified.
# Otherwise, the last argument is the destination. Remove it from $@.
for arg
do
if test -n "$dst_arg"; then
# $@ is not empty: it contains at least $arg.
set fnord "$@" "$dst_arg"
shift # fnord
fi
shift # arg
dst_arg=$arg
# Protect names problematic for 'test' and other utilities.
case $dst_arg in
-* | [=\(\)!]) dst_arg=./$dst_arg;;
esac
done
fi
if test $# -eq 0; then
if test -z "$dir_arg"; then
echo "$0: no input file specified." >&2
exit 1
fi
# It's OK to call 'install-sh -d' without argument.
# This can happen when creating conditional directories.
exit 0
fi
if test -z "$dir_arg"; then
if test $# -gt 1 || test "$is_target_a_directory" = always; then
if test ! -d "$dst_arg"; then
echo "$0: $dst_arg: Is not a directory." >&2
exit 1
fi
fi
fi
if test -z "$dir_arg"; then
do_exit='(exit $ret); exit $ret'
trap "ret=129; $do_exit" 1
trap "ret=130; $do_exit" 2
trap "ret=141; $do_exit" 13
trap "ret=143; $do_exit" 15
# Set umask so as not to create temps with too-generous modes.
# However, 'strip' requires both read and write access to temps.
case $mode in
# Optimize common cases.
*644) cp_umask=133;;
*755) cp_umask=22;;
*[0-7])
if test -z "$stripcmd"; then
u_plus_rw=
else
u_plus_rw='% 200'
fi
cp_umask=`expr '(' 777 - $mode % 1000 ')' $u_plus_rw`;;
*)
if test -z "$stripcmd"; then
u_plus_rw=
else
u_plus_rw=,u+rw
fi
cp_umask=$mode$u_plus_rw;;
esac
fi
for src
do
# Protect names problematic for 'test' and other utilities.
case $src in
-* | [=\(\)!]) src=./$src;;
esac
if test -n "$dir_arg"; then
dst=$src
dstdir=$dst
test -d "$dstdir"
dstdir_status=$?
else
# Waiting for this to be detected by the "$cpprog $src $dsttmp" command
# might cause directories to be created, which would be especially bad
# if $src (and thus $dsttmp) contains '*'.
if test ! -f "$src" && test ! -d "$src"; then
echo "$0: $src does not exist." >&2
exit 1
fi
if test -z "$dst_arg"; then
echo "$0: no destination specified." >&2
exit 1
fi
dst=$dst_arg
# If destination is a directory, append the input filename.
if test -d "$dst"; then
if test "$is_target_a_directory" = never; then
echo "$0: $dst_arg: Is a directory" >&2
exit 1
fi
dstdir=$dst
dstbase=`basename "$src"`
case $dst in
*/) dst=$dst$dstbase;;
*) dst=$dst/$dstbase;;
esac
dstdir_status=0
else
dstdir=`dirname "$dst"`
test -d "$dstdir"
dstdir_status=$?
fi
fi
case $dstdir in
*/) dstdirslash=$dstdir;;
*) dstdirslash=$dstdir/;;
esac
obsolete_mkdir_used=false
if test $dstdir_status != 0; then
case $posix_mkdir in
'')
# Create intermediate dirs using mode 755 as modified by the umask.
# This is like FreeBSD 'install' as of 1997-10-28.
umask=`umask`
case $stripcmd.$umask in
# Optimize common cases.
*[2367][2367]) mkdir_umask=$umask;;
.*0[02][02] | .[02][02] | .[02]) mkdir_umask=22;;
*[0-7])
mkdir_umask=`expr $umask + 22 \
- $umask % 100 % 40 + $umask % 20 \
- $umask % 10 % 4 + $umask % 2
`;;
*) mkdir_umask=$umask,go-w;;
esac
# With -d, create the new directory with the user-specified mode.
# Otherwise, rely on $mkdir_umask.
if test -n "$dir_arg"; then
mkdir_mode=-m$mode
else
mkdir_mode=
fi
posix_mkdir=false
case $umask in
*[123567][0-7][0-7])
# POSIX mkdir -p sets u+wx bits regardless of umask, which
# is incompatible with FreeBSD 'install' when (umask & 300) != 0.
;;
*)
# Note that $RANDOM variable is not portable (e.g. dash); Use it
# here however when possible just to lower collision chance.
tmpdir=${TMPDIR-/tmp}/ins$RANDOM-$$
trap 'ret=$?; rmdir "$tmpdir/a/b" "$tmpdir/a" "$tmpdir" 2>/dev/null; exit $ret' 0
# Because "mkdir -p" follows existing symlinks and we likely work
# directly in world-writeable /tmp, make sure that the '$tmpdir'
# directory is successfully created first before we actually test
# 'mkdir -p' feature.
if (umask $mkdir_umask &&
$mkdirprog $mkdir_mode "$tmpdir" &&
exec $mkdirprog $mkdir_mode -p -- "$tmpdir/a/b") >/dev/null 2>&1
then
if test -z "$dir_arg" || {
# Check for POSIX incompatibilities with -m.
# HP-UX 11.23 and IRIX 6.5 mkdir -m -p sets group- or
# other-writable bit of parent directory when it shouldn't.
# FreeBSD 6.1 mkdir -m -p sets mode of existing directory.
test_tmpdir="$tmpdir/a"
ls_ld_tmpdir=`ls -ld "$test_tmpdir"`
case $ls_ld_tmpdir in
d????-?r-*) different_mode=700;;
d????-?--*) different_mode=755;;
*) false;;
esac &&
$mkdirprog -m$different_mode -p -- "$test_tmpdir" && {
ls_ld_tmpdir_1=`ls -ld "$test_tmpdir"`
test "$ls_ld_tmpdir" = "$ls_ld_tmpdir_1"
}
}
then posix_mkdir=:
fi
rmdir "$tmpdir/a/b" "$tmpdir/a" "$tmpdir"
else
# Remove any dirs left behind by ancient mkdir implementations.
rmdir ./$mkdir_mode ./-p ./-- "$tmpdir" 2>/dev/null
fi
trap '' 0;;
esac;;
esac
if
$posix_mkdir && (
umask $mkdir_umask &&
$doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir"
)
then :
else
# The umask is ridiculous, or mkdir does not conform to POSIX,
# or it failed possibly due to a race condition. Create the
# directory the slow way, step by step, checking for races as we go.
case $dstdir in
/*) prefix='/';;
[-=\(\)!]*) prefix='./';;
*) prefix='';;
esac
oIFS=$IFS
IFS=/
set -f
set fnord $dstdir
shift
set +f
IFS=$oIFS
prefixes=
for d
do
test X"$d" = X && continue
prefix=$prefix$d
if test -d "$prefix"; then
prefixes=
else
if $posix_mkdir; then
(umask=$mkdir_umask &&
$doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir") && break
# Don't fail if two instances are running concurrently.
test -d "$prefix" || exit 1
else
case $prefix in
*\'*) qprefix=`echo "$prefix" | sed "s/'/'\\\\\\\\''/g"`;;
*) qprefix=$prefix;;
esac
prefixes="$prefixes '$qprefix'"
fi
fi
prefix=$prefix/
done
if test -n "$prefixes"; then
# Don't fail if two instances are running concurrently.
(umask $mkdir_umask &&
eval "\$doit_exec \$mkdirprog $prefixes") ||
test -d "$dstdir" || exit 1
obsolete_mkdir_used=true
fi
fi
fi
if test -n "$dir_arg"; then
{ test -z "$chowncmd" || $doit $chowncmd "$dst"; } &&
{ test -z "$chgrpcmd" || $doit $chgrpcmd "$dst"; } &&
{ test "$obsolete_mkdir_used$chowncmd$chgrpcmd" = false ||
test -z "$chmodcmd" || $doit $chmodcmd $mode "$dst"; } || exit 1
else
# Make a couple of temp file names in the proper directory.
dsttmp=${dstdirslash}_inst.$$_
rmtmp=${dstdirslash}_rm.$$_
# Trap to clean up those temp files at exit.
trap 'ret=$?; rm -f "$dsttmp" "$rmtmp" && exit $ret' 0
# Copy the file name to the temp name.
(umask $cp_umask && $doit_exec $cpprog "$src" "$dsttmp") &&
# and set any options; do chmod last to preserve setuid bits.
#
# If any of these fail, we abort the whole thing. If we want to
# ignore errors from any of these, just make sure not to ignore
# errors from the above "$doit $cpprog $src $dsttmp" command.
#
{ test -z "$chowncmd" || $doit $chowncmd "$dsttmp"; } &&
{ test -z "$chgrpcmd" || $doit $chgrpcmd "$dsttmp"; } &&
{ test -z "$stripcmd" || $doit $stripcmd "$dsttmp"; } &&
{ test -z "$chmodcmd" || $doit $chmodcmd $mode "$dsttmp"; } &&
# If -C, don't bother to copy if it wouldn't change the file.
if $copy_on_change &&
old=`LC_ALL=C ls -dlL "$dst" 2>/dev/null` &&
new=`LC_ALL=C ls -dlL "$dsttmp" 2>/dev/null` &&
set -f &&
set X $old && old=:$2:$4:$5:$6 &&
set X $new && new=:$2:$4:$5:$6 &&
set +f &&
test "$old" = "$new" &&
$cmpprog "$dst" "$dsttmp" >/dev/null 2>&1
then
rm -f "$dsttmp"
else
# Rename the file to the real destination.
$doit $mvcmd -f "$dsttmp" "$dst" 2>/dev/null ||
# The rename failed, perhaps because mv can't rename something else
# to itself, or perhaps because mv is so ancient that it does not
# support -f.
{
# Now remove or move aside any old file at destination location.
# We try this two ways since rm can't unlink itself on some
# systems and the destination file might be busy for other
# reasons. In this case, the final cleanup might fail but the new
# file should still install successfully.
{
test ! -f "$dst" ||
$doit $rmcmd -f "$dst" 2>/dev/null ||
{ $doit $mvcmd -f "$dst" "$rmtmp" 2>/dev/null &&
{ $doit $rmcmd -f "$rmtmp" 2>/dev/null; :; }
} ||
{ echo "$0: cannot unlink or rename $dst" >&2
(exit 1); exit 1
}
} &&
# Now rename the file to the real destination.
$doit $mvcmd "$dsttmp" "$dst"
}
fi || exit 1
trap '' 0
fi
done
# Local variables:
# eval: (add-hook 'before-save-hook 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End:
meson.build 0 → 100644
View file @ 24bc2b64
project('yelp-tools',
version: '41.beta',
license: 'GPL-2.0-or-later',
meson_version: '>= 0.51.0',
)
gnome = import('gnome')
python = import('python')
pyinst = python.find_installation('python3', required: true, modules: ['lxml'])
package_name = meson.project_name()
# Paths
prefix = get_option('prefix')
bindir = join_paths(prefix, get_option('bindir'))
datadir = join_paths(prefix, get_option('datadir'))
autoconfdatadir = join_paths(datadir, 'aclocal')
pkgdir = join_paths(datadir, package_name)
pkgtemplatesdir = join_paths(pkgdir, 'templates')
pkgxsltdir = join_paths(pkgdir, 'xslt')
# Dependencies
yelp_xsl_req = '>= 3.38.0'
yelp_xsl_dep = dependency('yelp-xsl', version: yelp_xsl_req)
xmllint_prg = find_program('xmllint', required: true)
xsltproc_prg = find_program('xsltproc', required: true)
itstool_prg = find_program('itstool', required: true)
yelp_db2html_path = yelp_xsl_dep.get_pkgconfig_variable('db2html')
yelp_db2xhtml_path = yelp_xsl_dep.get_pkgconfig_variable('db2xhtml')
yelp_mal2html_path = yelp_xsl_dep.get_pkgconfig_variable('mal2html')
yelp_mal2xhtml_path = yelp_xsl_dep.get_pkgconfig_variable('mal2xhtml')
yelp_xslt_dir = yelp_xsl_dep.get_pkgconfig_variable('xsltdir')
yelp_js_dir = yelp_xsl_dep.get_pkgconfig_variable('jsdir')
yelp_templates_dir = pkgtemplatesdir
yelp_icons_dir = join_paths(
yelp_xsl_dep.get_pkgconfig_variable('icondir'),
'hicolor', '24x24', 'status',
)
subdir('xslt')
subdir('templates')
subdir('tools')
if get_option('help') == true
subdir('help')
endif
summary = [
'',
'------',
'yelp-tools @0@'.format(meson.project_version()),
'',
' yelp.m4: @0@'.format(get_option('yelpm4')),
' help: @0@'.format(get_option('help')),
'',
'Directories:',
' prefix: @0@'.format(prefix),
' datadir: @0@'.format(datadir),
'------',
]
message('\n'.join(summary))
meson_options.txt 0 → 100644
View file @ 24bc2b64
option('yelpm4',
type: 'boolean', value: true,
description: 'Install autotools macros')
option('help',
type: 'boolean', value: false,
description: 'Install help files')
missing deleted 100755 → 0
View file @ 8c79bbb4
#! /bin/sh
# Common wrapper for a few potentially missing GNU programs.
scriptversion=2018-03-07.03; # UTC
# Copyright (C) 1996-2018 Free Software Foundation, Inc.
# Originally written by Fran,cois Pinard <pinard@iro.umontreal.ca>, 1996.
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
# As a special exception to the GNU General Public License, if you
# distribute this file as part of a program that contains a
# configuration script generated by Autoconf, you may include it under
# the same distribution terms that you use for the rest of that program.
if test $# -eq 0; then
echo 1>&2 "Try '$0 --help' for more information"
exit 1
fi
case $1 in
--is-lightweight)
# Used by our autoconf macros to check whether the available missing
# script is modern enough.
exit 0
;;
--run)
# Back-compat with the calling convention used by older automake.
shift
;;
-h|--h|--he|--hel|--help)
echo "\
$0 [OPTION]... PROGRAM [ARGUMENT]...
Run 'PROGRAM [ARGUMENT]...', returning a proper advice when this fails due
to PROGRAM being missing or too old.
Options:
-h, --help display this help and exit
-v, --version output version information and exit
Supported PROGRAM values:
aclocal autoconf autoheader autom4te automake makeinfo
bison yacc flex lex help2man
Version suffixes to PROGRAM as well as the prefixes 'gnu-', 'gnu', and
'g' are ignored when checking the name.
Send bug reports to <bug-automake@gnu.org>."
exit $?
;;
-v|--v|--ve|--ver|--vers|--versi|--versio|--version)
echo "missing $scriptversion (GNU Automake)"
exit $?
;;
-*)
echo 1>&2 "$0: unknown '$1' option"
echo 1>&2 "Try '$0 --help' for more information"
exit 1
;;
esac
# Run the given program, remember its exit status.
"$@"; st=$?
# If it succeeded, we are done.
test $st -eq 0 && exit 0
# Also exit now if we it failed (or wasn't found), and '--version' was
# passed; such an option is passed most likely to detect whether the
# program is present and works.
case $2 in --version|--help) exit $st;; esac
# Exit code 63 means version mismatch. This often happens when the user
# tries to use an ancient version of a tool on a file that requires a
# minimum version.
if test $st -eq 63; then
msg="probably too old"
elif test $st -eq 127; then
# Program was missing.
msg="missing on your system"
else
# Program was found and executed, but failed. Give up.
exit $st
fi
perl_URL=https://www.perl.org/
flex_URL=https://github.com/westes/flex
gnu_software_URL=https://www.gnu.org/software
program_details ()
{
case $1 in
aclocal|automake)
echo "The '$1' program is part of the GNU Automake package:"
echo "<$gnu_software_URL/automake>"
echo "It also requires GNU Autoconf, GNU m4 and Perl in order to run:"
echo "<$gnu_software_URL/autoconf>"
echo "<$gnu_software_URL/m4/>"
echo "<$perl_URL>"
;;
autoconf|autom4te|autoheader)
echo "The '$1' program is part of the GNU Autoconf package:"
echo "<$gnu_software_URL/autoconf/>"
echo "It also requires GNU m4 and Perl in order to run:"
echo "<$gnu_software_URL/m4/>"
echo "<$perl_URL>"
;;
esac
}
give_advice ()
{
# Normalize program name to check for.
normalized_program=`echo "$1" | sed '
s/^gnu-//; t
s/^gnu//; t
s/^g//; t'`
printf '%s\n' "'$1' is $msg."
configure_deps="'configure.ac' or m4 files included by 'configure.ac'"
case $normalized_program in
autoconf*)
echo "You should only need it if you modified 'configure.ac',"
echo "or m4 files included by it."
program_details 'autoconf'
;;
autoheader*)
echo "You should only need it if you modified 'acconfig.h' or"
echo "$configure_deps."
program_details 'autoheader'
;;
automake*)
echo "You should only need it if you modified 'Makefile.am' or"
echo "$configure_deps."
program_details 'automake'
;;
aclocal*)
echo "You should only need it if you modified 'acinclude.m4' or"
echo "$configure_deps."
program_details 'aclocal'
;;
autom4te*)
echo "You might have modified some maintainer files that require"
echo "the 'autom4te' program to be rebuilt."
program_details 'autom4te'
;;
bison*|yacc*)
echo "You should only need it if you modified a '.y' file."
echo "You may want to install the GNU Bison package:"
echo "<$gnu_software_URL/bison/>"
;;
lex*|flex*)
echo "You should only need it if you modified a '.l' file."
echo "You may want to install the Fast Lexical Analyzer package:"
echo "<$flex_URL>"
;;
help2man*)
echo "You should only need it if you modified a dependency" \
"of a man page."
echo "You may want to install the GNU Help2man package:"
echo "<$gnu_software_URL/help2man/>"
;;
makeinfo*)
echo "You should only need it if you modified a '.texi' file, or"
echo "any other file indirectly affecting the aspect of the manual."
echo "You might want to install the Texinfo package:"
echo "<$gnu_software_URL/texinfo/>"
echo "The spurious makeinfo call might also be the consequence of"
echo "using a buggy 'make' (AIX, DU, IRIX), in which case you might"
echo "want to install GNU make:"
echo "<$gnu_software_URL/make/>"
;;
*)
echo "You might have modified some files without having the proper"
echo "tools for further handling them. Check the 'README' file, it"
echo "often tells you about the needed prerequisites for installing"
echo "this package. You may also peek at any GNU archive site, in"
echo "case some other package contains this missing '$1' program."
;;
esac
}
give_advice "$1" | sed -e '1s/^/WARNING: /' \
-e '2,$s/^/ /' >&2
# Propagate the correct exit status (expected to be 127 for a program
# not found, 63 for a program that failed due to version mismatch).
exit $st
# Local variables:
# eval: (add-hook 'before-save-hook 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End: