#!/bin/bash

# yelp4kde by Trent W. buck - uploaded to
# <http://angg.twu.net/bin/yelp4kde> with the author's permission.
# Licence: Expat <https://www.debian.org/legal/licenses/mit>.
# Version: 2019sep09

# Goal: KDE and GNOME each have their own help application and their
# own slightly different help formats. —twb, Feb 2017 (#31512)
#
# Rather than installing BOTH help viewers,
# just install the GNOME one (yelp), and
# do all necessary steps to convert KDE documents to work in yelp.
#
# KDE manuals typically come in two forms:
#  * index.docbook, the original sources; &
#  * index.cache.bz2, a pre-rendered HTML version of the above.
#
# We use the former because yelp will not paginate the latter.
#
# By default GNOME apps run "yelp help:foo";
# KDE apps (eventually) run "khelpcenter help:/foo/index.html".
# Our fake khelpcenter must change "/foo/index.html" to "foo".
#
# By default yelp searches /usr/share/help/;
# we must move (or copy, or symlink) the manuals in there.
#
# By default "yelp help:foo" expands to help:foo:index,
# which accesses "<article id='index'>" in GNOME examples.
# But KDE top-level element is <book id='kalgebra'> —
# we must change the id to "index".
#
# By default KDE writes en_US as "en";
# by default GNOME writes en_US as "C".
# We must thus change en -> C.
#
# The index.docbook source relies on &Foo; elements defined in
# kdoctool's /usr/share/kde4/apps/ksgmltools2/customization.
# We must include these in each manual so yelp can find them.

set -eEu -o pipefail
shopt -s failglob
trap 'echo >&2 "$0:${LINENO}: unknown error"' ERR

rm -rf /tmp/prisonpc-yelp4kde
mkdir -p /tmp/prisonpc-yelp4kde/debian/source
cd /tmp/prisonpc-yelp4kde

apt install build-essential dpkg-dev devscripts lintian debhelper fakeroot binutils
apt install debhelper dh-strip-nondeterminism libfile-stripnondeterminism-perl
apt install kdoctools5=5.28.0-1

export NAME='Trent W. Buck' EMAIL=twb@cyber.com.au  # used by dch
dch --create --package prisonpc-yelp4kde -v0~prisonpc1 -Dstable 'Initial release.'
dch -v0~prisonpc4 -Dstable 'Bump kde4libs from 4:4.14.2-5+deb8u1 to 4:4.14.2-5+deb8u2 due to DSA-3849-1.'
dch -v0~prisonpc5 -Dstable 'Update for stretch.'
>debian/compat          echo 10
>debian/source/format   echo '3.0 (native)'
>debian/rules           cat <<'EOF' && chmod +x debian/rules
#!/usr/bin/make -f
%:
	dh $@
# NOTE: this must be done here, rather than in debian/install,
# because the latter helpfully prevents exactly this dirty trick.
override_dh_install: /usr/share/kf5/kdoctools/customization
	dh_install
	mkdir -p debian/prisonpc-yelp4kde/$(<D)
	cp -a $< debian/prisonpc-yelp4kde/$<
EOF
>debian/control         cat <<'EOF'
Source: prisonpc-yelp4kde
Section: kde
Priority: optional
Standards-Version: 3.9.8
Maintainer: Trent W. Buck <twb@cyber.com.au>
Build-Depends: debhelper (>= 10~), kdoctools5 (= 5.28.0-1)
# This package puts two files in the customization/ directory that we embed.
# It also provides .so's, so we can't simply Replace it.
Build-Conflicts: libkf5kdelibs4support-data

Package: prisonpc-yelp4kde
Depends: ${misc:Depends}, yelp, docbook-xml
Architecture: all
# KDE maintainers lie to dpkg, saying some unnecessary libraries are necessary.
# To avoid installing those libraries, we must also lie to dpkg, claiming we provide them.
# See also build-ersatz-packages (prisonpc-ersatz-kde-junk).
Provides:
 kdoctools (= 4:4.14.26-2),
 kdoctools5 (= 5.28.0-1),
 khelpcenter (= 4:16.08.3-1)
Conflicts:
 kdoctools,
 kdoctools5,
 khelpcenter
Replaces:
 kdoctools,
 kdoctools5,
 khelpcenter
Description: convert KDE manuals to work in yelp
 KDE and GNOME each have their own help application and their
 own slightly different help formats.
 Rather than installing BOTH help viewers,
 just install the GNOME one (yelp), and
 do all necessary steps to convert KDE documents to work in yelp.
EOF
>debian/install         cat <<'EOF'
# Steal from kdoctools at boot time,
# so we don't need to install all of kdoctools' dependencies (~50MB) at install time.
# UPDATE: done in debian/rules because doesn't work here.
#/usr/share/kf5/kdoctools/customization   usr/share/kf5/kdoctools/
# This is our fake khelpcenter that fixes the URL then runs yelp.
khelpcenter   usr/bin/
# These are necessary for klauncher(?) to find our khelpcenter script,
# since khelpcenter package isn't installed.
khelpcenter.desktop   usr/share/kservices5/
khelpcenter.desktop   usr/share/kde4/services/
EOF
>debian/triggers        cat <<'EOF'
interest-noawait /usr/share/doc/HTML
EOF
>khelpcenter            cat <<'EOF' && chmod +x khelpcenter
#!/bin/sh
if [ 1 = $# ]
then
    case $1 in
        help:/*/index.html)
            x=help:${1#help:/};
            x=${x%/index.html};
            exec yelp "$x";;
    esac
fi

# Default case (probably never happens).
exec yelp "$@"
EOF
>khelpcenter.desktop    cat <<'EOF'
[Desktop Entry]
Name=KHelpCenter
Comment=The KDE Help Center
Icon=help-browser
X-DocPath=khelpcenter/index.html
Type=Service
Terminal=false
Exec=khelpcenter %u
X-KDE-StartupNotify=true
EOF
>debian/postinst        cat <<'EOF'
#!/bin/sh
set -e

# NOTE: for now, we only support install, not remove/purge.
if [ "$1" = triggered ] || [ "$1" = configure ]
then
    # As at Debian 9, KDE manuals are installed in two places:
    # /usr/share/doc/kde/HTML/en  (145 documents)
    # /usr/share/doc/HTML/en      (220 documents)
    #
    # The latter seems to be the KDE5 standard.
    # It's a pain to support both paths at once in the "yelpizing" code below,
    # so instead simply replace /usr/share/doc/kde with a symlink. —twb, Jan 2018
    #
    # NOTE: we can't simply "mv /usr/share/doc/kde/HTML /usr/share/doc/",
    #       because by the time this script runs,
    #       there might already be a /usr/share/doc/HTML!
    #       Just cheat and use tar (we don't have rsync).
    if [ -d /usr/share/doc/kde -a ! -L /usr/share/doc/kde ]
    then
        tar -c -C /usr/share/doc/kde --remove-files HTML |
        tar -x -C /usr/share/doc
        rmdir /usr/share/doc/kde
        # FIXME: I was going to create a backcompat symlink, but
        #        that breaks bootstrap's "delete links to pruned files" code.
        #ln -s . /usr/share/doc/kde
    fi

    [ ! -d /usr/share/doc/HTML/ ] ||
    find /usr/share/doc/HTML/ -name index.docbook |
    while read -r path
    do
        lang=${path#/*/*/*/*/} lang=${lang%%/*} newlang=$lang
        [ "$newlang" != en ] || newlang=C  # KDE en becomes GNOME C
        name=${path#/*/*/*/*/*/} name=${name%/index.docbook}
        newpath=/usr/share/help/"$newlang"/"$name"

        [ ! -e "$newpath" ] || continue

        echo >&2 "Converting $path..."
        mkdir -p "${newpath%/*}"
        ln -sT "${path%/*}" "$newpath"
        ln -st "$newpath" /usr/share/kf5/kdoctools/customization/dtd
        ln -st "$newpath" /usr/share/kf5/kdoctools/customization/entities
        ln -st "$newpath" /usr/share/kf5/kdoctools/customization/"$lang"

        # NOTE: using regexp replacement on XML is morally wrong!
        # NOTE: no ^ because marble & kalzium have leading whitespace.
	# FIXME: use python or xslt or something instead?
        sed -i 's/<book id="[^"]*"/<book id="index"/' "$newpath/index.docbook"
    done

    # The pre-rendered versions are no longer needed.
    [ ! -d /usr/share/doc/HTML/ ] ||
    find /usr/share/doc/HTML/ '(' -name index.cache.bz2 -o -name '*.html' -o -name '*.css' ')' -delete
fi

#DEBHELPER#
EOF
debuild -uc -us