.\" (C) Copyright 2011-2024 Software Freedom Conservancy, Inc.
.\" 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 3 of the License, or
.\" (at your option) any later version.
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..

.TH "DH\-EXEC\-ILLITERATE" "1" "2024-02-27" "" "dh-exec"
.ad l
.nh
.SH "NAME"
dh\-exec\-illiterate \- Write literate debhelper config files!
.SH "SYNOPSIS
.Vb 3
\fB#! /usr/bin/dh\-exec \-\-with=illiterate,subst,install\fR
Greetings, my dear reader, and welcome to the awesome world of
literate programming!

Today, we're going to explore how to write a debhelper install file in
a literate manner. Trust me, it's going to be lots and lots of fun!

So, what exactly are we trying to accomplish? We're going to try
installing a file from `src/this\-file' in the source tree, to a
multi\-arched path in the binary file. Lets say, to
`/usr/lib/foo/${DEB_HOST_MULTIARCH}/'.

Of course, ${DEB_HOST_MULTIARCH} is a variable, and will be expanded
later in the dh\-exec pipeline. It'll be something like
x86_64\-linux\-gnu.

Furthermore, we want to install all files from the 'usr/lib' directory
under debian/tmp. If we were writing an illiteral install file, we'd
write this rule as:

    usr/lib

But the above description is much easier to understand, isn't it?

We're almost finished! One thing left to do, is to install a script
named \`rename\-me', to \`/usr/share/foo/new\-name' \- we renamed it
in the process!
.Ve

.SH "DESCRIPTION"
The dh\-exec\-illiterate sub\-command, unlike the others, does not
serve any particular case, except to serve as a warning to all, that
things can be taken to an extreme, even with dh\-exec. On the other
hand, it is just like the other sub\-commands in that it must not be
called directly, but through \fIdh\-exec\fR(1), which automatically
runs all available sub\-commands if run bare; or explicitly with
\fBdh\-exec \-\-with=illiterate\fR.

It is a program that will translate its input from pretty much
free-form text into something that resembles an install file. At
least, that's the only supported output format for now.

Everything that's not recognised, will be ignored, and not
printed. The recognised constructs are:

.IP "\fB`source'\fR \fI...\fR \fB`destination'\fR"
The first string between a backtick and a single quote will be treated
as the source file, the next such string will be the destination. If
the destination ends with a slash, dh\-exec\-illiterate will consider
it a directory, otherwise it will output a construct that
dh\-exec\-install can recognise as a rename operation.

.IP "\fB'source'\fR"
A string, without whitespace, between two single quotes is treated as
a source, whose destination is unspecified, and is left up to
\fIdh_install\fR(1) to figure out.

.SH "ENVIRONMENT"
.PP
\fIDH_EXEC_SCRIPTDIR\fR
.RS 4
Indicates which directory the command\-specific scripts should be
sought for. If not specified, scripts will be searched for in
\fI/usr/share/dh\-exec/\fR.
.RE

.SH "FILES"
.PP
\fI$DH_EXEC_SCRIPTDIR/dh\-exec\-illiterate\-*\fR
.RS 4
The various scripts for the higher\-level program.
.RE

.SH "VERSIONS"

The sub\-command was introduced in dh\-exec version \fI0.1\fR.

.SH SEE ALSO
.BR dh\-exec (1),
.BR debhelper (7)