Commit f3e7eedf authored by Peter Hutterer's avatar Peter Hutterer Committed by Pekka Paalanen

doc: replace publican with xmlto

Publican isn't packaged for some distros, xmlto is a lot more common. Most of
what publican provides for us is the stylesheet anyway, so we can just use
xmlto and the publican stylesheet to get roughly the same look.

PDF and XML generation has been dropped, this needs a bit more more effort
than a mere switchover to xmlto.

The top-level directory structure imposed by publican is kept for now
(specifically the Wayland/en-US/html tree). This makes it easier to transition over
for packagers. Note that the list of files inside has changed.

CSS files are taken from publican to keep a uniform look compared to previous
documentations. Stylesheets are licensed under CC0 1.0 Universal license, see
publican/LICENSE:

1.  Files in the datadir/Common_Content directory and its subdirectories are
    licensed under the CC0 1.0 Universal license.

    To the extent possible under law, the developers of Publican waive all
    copyright and related or neighboring rights to the files contained
    in the datadir/Common_Content directory and its subdirectories.
Acked-by: Pekka Paalanen's avatarPekka Paalanen <pekka.paalanen@collabora.co.uk>
parent 472f0c48
......@@ -109,14 +109,10 @@ if test "x$enable_documentation" = "xyes"; then
AC_MSG_ERROR([Documentation build requested but doxygen not found. Install doxygen or disable the documentation using --disable-documentation])
fi
AC_PATH_PROG(PUBLICAN, publican)
AC_PATH_PROG(XMLTO, xmlto)
if test "x$PUBLICAN" != "x"; then
PUBLICAN_VERSION=[`$PUBLICAN -v | sed -e 's/version=v\?\([0-9]*\.[0-9]*\).*/\1/'`]
if test [ 1 -eq `echo "${PUBLICAN_VERSION} < 2.8" | bc` ]; then
AC_MSG_ERROR([Publican version is not supported. Install publican >= 2.8 or disable the documentation using --disable-documentation])
fi
if test "x$XMLTO" = "x"; then
AC_MSG_ERROR([Documentation build requested but xmlto not found. Install xmlto or disable the documentation using --disable-documentation])
fi
AC_CONFIG_FILES([
......@@ -124,7 +120,7 @@ if test "x$enable_documentation" = "xyes"; then
])
fi
AM_CONDITIONAL([HAVE_PUBLICAN], [test "x$PUBLICAN" != "x"])
AM_CONDITIONAL([HAVE_XMLTO], [test "x$XMLTO" != "x"])
AC_CONFIG_FILES([Makefile
cursor/wayland-cursor.pc
......
# Documentation is built with publican
# https://fedorahosted.org/publican/
# Publican takes docbook-style input files and compiles them to various
# output formats.
# Documentation is built with xmlto, but some of the recipes in here are
# leftovers from building with Publican (https://fedorahosted.org/publican/)
#
# How this build works:
# * the main target is Wayland, documentation ends up in $(builddir)/Wayland/
# * hand-written chapters are located in sources
# Publican does not take a source path, so to support out-of-tree builds
# these are copied to $(builddir)/en-US which is the actual directory
# Publican uses.
# * hand-written chapters and CSS files are located in sources. These are
# copied into $(builddir)/en-US/
# * ProtocolSpec.xml is generated from $(top_srcdir)/protocol/wayland.xml,
# changed into docbook via XSLT and saved in $(builddir)/en-US/
# * ProtocolInterfaces.xml, same as above, uses a different XSLT
......@@ -16,7 +12,7 @@
# $(builddir)/en-US
# * WaylandServerAPI.xml is generated from the doxygen output and saved in
# $(builddir)/en-US
# * run Publican on en-US
# * run xmlto on $(builddir)/en-US, output to $(builddir)/Wayland/en-US
publican_sources = \
$(srcdir)/sources/Wayland.ent \
$(srcdir)/sources/Wayland.xml \
......@@ -35,9 +31,36 @@ publican_sources = \
$(srcdir)/sources/images/wayland.png \
$(srcdir)/sources/images/x-architecture.png
if HAVE_PUBLICAN
css_sources = \
$(srcdir)/sources/css/brand.css \
$(srcdir)/sources/css/common.css \
$(srcdir)/sources/css/default.css \
$(srcdir)/sources/css/epub.css \
$(srcdir)/sources/css/print.css
img_sources = \
$(srcdir)/sources/images/icon.svg \
$(srcdir)/sources/images/wayland-architecture.png \
$(srcdir)/sources/images/wayland.png \
$(srcdir)/sources/images/x-architecture.png
if HAVE_XMLTO
if HAVE_XSLTPROC
noinst_DATA = Wayland $(publican_targets)
XMLTO_PARAM = \
--stringparam chunk.section.depth=0 \
--stringparam toc.section.depth=1 \
--stringparam html.stylesheet=css/default.css
html_destdir = $(builddir)/Wayland/en-US/html
Wayland: $(publican_targets)
$(AM_V_GEN)$(MKDIR_P) -p $(html_destdir)/css
$(AM_V_GEN)cp -f $(css_sources) $(html_destdir)/css/
$(AM_V_GEN)$(MKDIR_P) -p $(html_destdir)/images
$(AM_V_GEN)cp -f $(img_sources) $(html_destdir)/images/
$(AM_V_GEN)$(XMLTO) $(XMLTO_PARAM) html en-US/Wayland.xml -o $(html_destdir)
@touch Wayland
pubdir = $(docdir)/Wayland/en-US
publican_targets = $(publican_sources:$(srcdir)/sources%=$(builddir)/en-US%) \
......@@ -85,37 +108,16 @@ $(builddir)/en-US/%: $(srcdir)/sources/% en-US/ProtocolSpec.xml en-US/ProtocolIn
$(AM_V_GEN)cp -f $< $@
$(AM_V_GEN)chmod a+w $@
# Run publican for the builddir on the generated (or copied) source
# The output formats are generated in the Wayland sub directory. Also, we need
# to use a tmp publican.cfg cause 'publican rename' modifies the original.
Wayland: $(publican_targets)
$(AM_V_GEN)cp -f $(srcdir)/publican.cfg $(builddir)/publican-copy.cfg
$(AM_V_GEN)$(PUBLICAN) rename --name Wayland \
--version "$(WAYLAND_VERSION_MAJOR).$(WAYLAND_VERSION_MINOR)" \
--config $(builddir)/publican-copy.cfg
$(AM_V_GEN)$(PUBLICAN) build --quiet --langs en-US --pdftool fop --formats html,pdf \
--config $(builddir)/publican-copy.cfg
@touch Wayland
CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(publican_targets)
clean-local:
$(AM_V_at)rm -fr $(builddir)/en-US
$(AM_V_at)rm -fr $(builddir)/Wayland
$(AM_V_at)rm -fr $(builddir)/publican-copy.cfg
install-data-local:
test -z "$(pubdir)/html/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/Common_Content/css"
test -z "$(pubdir)/html/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/Common_Content/images"
test -z "$(pubdir)/html/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/css"
test -z "$(pubdir)/html/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/images"
test -z "$(pubdir)/html-pdf/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html-pdf/Common_Content/css"
test -z "$(pubdir)/html-pdf/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html-pdf/Common_Content/images"
test -z "$(pubdir)/html-pdf/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html-pdf/images"
test -z "$(pubdir)/pdf" || $(mkdir_p) "$(DESTDIR)$(pubdir)/pdf"
test -z "$(pubdir)/xml/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/Common_Content/css"
test -z "$(pubdir)/xml/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/Common_Content/images"
test -z "$(pubdir)/xml/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/images"
list=`find $(builddir)/Wayland/en-US -type f -not -path '$(builddir)/Wayland/en-US/xml_tmp*'`; \
list=`find $(builddir)/Wayland/en-US -type f`; \
for p in $$list; do \
echo " $(INSTALL_DATA) '$$p' '$(DESTDIR)$(docdir)/$$p'"; \
$(INSTALL_DATA) "$$p" "$(DESTDIR)$(docdir)/$$p"; \
......@@ -132,4 +134,4 @@ uninstall-local:
endif
endif
EXTRA_DIST = $(publican_sources) publican.cfg protocol-to-docbook.xsl protocol-interfaces-to-docbook.xsl doxygen-to-publican.xsl
EXTRA_DIST = $(publican_sources) $(css_sources) $(img_sources) protocol-to-docbook.xsl protocol-interfaces-to-docbook.xsl doxygen-to-publican.xsl
# Config::Simple 4.59
# Fri Feb 24 09:36:50 2012
xml_lang: "en-US"
type: Book
brand: common
tmp_dir: Wayland
toc_section_depth: 1
chunk_section_depth: 0
/*headings*/
h1, h2, h3, h4, h5, h6,
div.producttitle,
div.subtitle,
div.author div.author,
div.translator div.translator,
div.othercredit div.othercredit,
div.editor div.editor,
div.contrib div.contrib,
.title,
.titlepage .edition,
.titlepage .releaseinfo {
color: #336699;
}
This diff is collapsed.
@import url("common.css");
@import url("overrides.css");
@import url("lang.css");
/*headings*/
h1, h2, h3, h4, h5, h6,
div.producttitle,
div.subtitle,
div.author div.author,
div.translator div.translator,
div.othercredit div.othercredit,
div.editor div.editor,
div.contrib div.contrib,
.title,
.titlepage .edition {
}
div.para {
margin-top: 1em;
}
/* inline syntax highlighting */
.perl_Alert {
color: #0000ff;
}
.perl_BaseN {
color: #007f00;
}
.perl_BString {
color: #5C3566;
}
.perl_Char {
color: #ff00ff;
}
.perl_Comment {
color: #888888;
}
.perl_DataType {
color: #0000ff;
}
.perl_DecVal {
color: #00007f;
}
.perl_Error {
color: #ff0000;
}
.perl_Float {
color: #00007f;
}
.perl_Function {
color: #007f00;
}
.perl_IString {
color: #5C3566;
}
.perl_Keyword {
color: #002F5D;
}
.perl_Operator {
color: #ffa500;
}
.perl_Others {
color: #b03060;
}
.perl_RegionMarker {
color: #96b9ff;
}
.perl_Reserved {
color: #9b30ff;
}
.perl_String {
color: #5C3566;
}
.perl_Variable {
color: #0000ff;
}
.perl_Warning {
color: #0000ff;
}
b, strong {
font-weight: bolder;
}
code.command {
font-family: monospace;
font-weight: bolder;
}
@import url("common.css");
@import url("overrides.css");
@import url("lang.css");
#tocframe {
display: none;
}
body.toc_embeded {
margin-left: 30px;
}
.producttitle {
color: #336699;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment