summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 15:53:52 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 15:53:52 +0000
commitefe47381c599b07e4c7bbdb2e91e8090a541c887 (patch)
tree05cf57183f5a23394eca11b00f97a74a5dfdf79d /doc
parentInitial commit. (diff)
downloaddevscripts-upstream.tar.xz
devscripts-upstream.zip
Adding upstream version 2.23.4+deb12u1.upstream/2.23.4+deb12u1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile26
-rw-r--r--doc/devscripts.1.in30
-rw-r--r--doc/devscripts.conf.560
-rw-r--r--doc/edit-patch.143
-rwxr-xr-xdoc/genmanpage.pl30
-rw-r--r--doc/suspicious-source.155
-rw-r--r--doc/what-patch.142
-rw-r--r--doc/wrap-and-sort.1102
8 files changed, 388 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..59d1ae1
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,26 @@
+include ../Makefile.common
+
+all: devscripts.1
+
+clean:
+ rm -f devscripts.1 devscripts.1.tmp.*
+
+# There is a slight chance this gets called twice, once here from here and once
+# from ../po4a/Makefile. Treat files with care.
+PID := $(shell echo $$$$-$$PPID)
+devscripts.1: devscripts.1.in ../README genmanpage.pl
+ cat $< > $@.tmp.$(PID)
+ cat ../README | \
+ awk '/^- annotate-output/,/^ mailing lists./'|sed -e '/^[[:space:]]*$$/d' -e 's/^/ /g' | \
+ perl genmanpage.pl \
+ >> $@.tmp.$(PID)
+ mv $@.tmp.$(PID) $@
+
+install: install_man1 install_man5
+
+install_man1: *.1 devscripts.1
+ install -d "$(DESTDIR)$(MAN1DIR)"
+ install -m0644 -t "$(DESTDIR)$(MAN1DIR)" $^
+install_man5: *.5
+ install -d "$(DESTDIR)$(MAN5DIR)"
+ install -m0644 -t "$(DESTDIR)$(MAN5DIR)" $^
diff --git a/doc/devscripts.1.in b/doc/devscripts.1.in
new file mode 100644
index 0000000..871dc68
--- /dev/null
+++ b/doc/devscripts.1.in
@@ -0,0 +1,30 @@
+.TH DEVSCRIPTS 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
+.SH NAME
+devscripts \- scripts to ease the lives of Debian developers
+.SH DESCRIPTION
+The \fBdevscripts\fR package provides a collection of scripts which
+may be of use to Debian developers and others wishing to build Debian
+packages. For a summary of the available scripts, please see the file
+\fI/usr/share/doc/devscripts/README.gz\fR, and for full details, please
+see the individual manpages. They are contributed by multiple
+developers; for details of the authors, please see the code or
+manpages.
+
+Also, the directory \fI/usr/share/doc/devscripts/examples\fR contains an
+example \fBexim\fR script for sorting mail arriving to Debian mailing
+lists.
+.SH ENVIRONMENT
+Several scripts of the devscripts suite use the following environment
+variables. Check the man pages of individual scripts for more details on how the
+variables are used.
+.IX Header "ENVIRONMENT"
+.IP "\s-1DEBEMAIL\s0" 4
+.IX Item "DEBEMAIL"
+Email of the person acting on a given Debian package via devscripts.
+.IP "\s-1DEBFULLNAME\s0" 4
+.IX Item "DEBFULLNAME"
+Full name (first + family) of the person acting on a given Debian package via
+devscripts.
+.SH SCRIPTS
+Here is the complete list of available devscripts. See their man pages
+for additional documentation.
diff --git a/doc/devscripts.conf.5 b/doc/devscripts.conf.5
new file mode 100644
index 0000000..a605d66
--- /dev/null
+++ b/doc/devscripts.conf.5
@@ -0,0 +1,60 @@
+.TH DEVSCRIPTS.CONF 5 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
+.SH NAME
+devscripts.conf \- configuration file for the devscripts package
+.SH DESCRIPTION
+The \fBdevscripts\fR package provides a collection of scripts which
+may be of use to Debian developers and others wishing to build Debian
+packages. Many of these have options which can be configured on a
+system-wide and per-user basis.
+.PP
+Every script in the \fBdevscripts\fR package which makes use of values
+from these configuration files describes the specific settings
+recognised in its own manpage. (For a list of the scripts, either see
+\fI/usr/share/doc/devscripts/README.gz\fR or look at the output of
+\fIdpkg \-L devscripts | grep /usr/bin\fR.)
+.PP
+The two configuration files are \fI/etc/devscripts.conf\fR for
+system-wide defaults and \fI~/.devscripts\fR for per-user settings.
+They are written with \fBbash\fR(1) syntax, but should only have
+comments and simple variable assignments in them; they are both
+sourced (if present) by many of the \fBdevscripts\fR scripts.
+Variables corresponding to simple switches should have one of the
+values \fIyes\fR and \fIno\fR; any other setting is regarded as
+equivalent to the default setting.
+.PP
+All variable names are written in uppercase, and begin with the script
+name. Package-wide variables begin with "DEVSCRIPTS", and are listed
+below, as well as in the relevant manpages.
+.PP
+For a list of all of the available options variables, along with their
+default settings, see the example configuration file
+\fI/usr/share/doc/devscripts/devscripts.conf.ex\fR. This is copied to
+\fI/etc/devscripts.conf\fR when the \fBdevscripts\fR package is first
+installed. Information about configuration options introduced in
+newer versions of the package will be appended to
+\fI/etc/devscripts.conf\fR when the package is upgraded.
+.PP
+Every script which reads the configuration files can be forced to
+ignore them by using \fB\-\-no-conf\fR as the \fIfirst\fR command-line
+option.
+.SH "PACKAGE-WIDE VARIABLES"
+The currently recognised package-wide variables are:
+.TP
+.BR DEVSCRIPTS_CHECK_DIRNAME_LEVEL ", " DEVSCRIPTS_CHECK_DIRNAME_REGEX
+These variables control scripts which change directory to find a
+\fIdebian/changelog\fR file or suchlike, and some other miscellaneous
+cases. In order to prevent unwanted, even possibly dangerous,
+behaviour, these variables control when actions will be performed.
+The scripts which currently make use of these variables are:
+\fBdebc\fR, \fBdebchange\fR/\fBdch\fR, \fBdebclean\fR, \fBdebi\fR,
+\fBdebrelease\fR, \fBdebuild\fR and \fBuscan\fR, but this list may
+change with time (and I may not remember to update this manpage).
+Please see the manpages of individual scripts for details of the
+specific behaviour for each script.
+.SH "SEE ALSO"
+.BR devscripts (1)
+and
+.IR /usr/share/doc/devscripts/README.gz.
+.SH AUTHOR
+This manpage was written for the \fBdevscripts\fR package by the
+package maintainer Julian Gilbey <jdg@debian.org>.
diff --git a/doc/edit-patch.1 b/doc/edit-patch.1
new file mode 100644
index 0000000..70b0ac9
--- /dev/null
+++ b/doc/edit-patch.1
@@ -0,0 +1,43 @@
+.TH EDIT-PATCH "1" "Debian Utilities" "DEBIAN"
+.SH NAME
+\fBedit-patch\fR, \fBadd-patch\fR \- tool for preparing patches for Debian
+source packages
+
+.SH SYNOPSIS
+\fBedit-patch\fR \fIpath/to/patch\fR
+
+\fBadd-patch\fR \fIpath/to/patch\fR
+
+.SH DESCRIPTION
+\fBedit-patch\fR is a wrapper script around the Quilt, CDBS, and dpatch patch
+systems. It simplifies the process of preparing and editing patches to Debian
+source packages and allows the user to not have to be concerned with which patch
+system is in use.
+Run from inside the root directory of the source package, \fBedit-patch\fR can
+be used to edit existing patches located in \fIdebian/patches\fR.
+
+It can also be used to incorporate new patches.
+If pointed at a patch not already present, it will copy the patch to
+\fIdebian/patches\fR in the correct format for the patch system in use.
+Next, the patch is applied and a subshell is opened in order to edit the patch.
+Typing \fBexit\fR or pressing Ctrl-d will close the subshell and launch an editor
+to record the \fIdebian/changelog\fR entry.
+
+\fBedit-patch\fR is integrated with the Bazaar and Git version control systems.
+The patch will be automatically added to the tree, and the \fIdebian/changelog\fR
+entry will be used as the commit message.
+
+If no patch system is present, the patch is applied inline,
+and a copy is stored in \fIdebian/patches-applied\fR.
+
+\fBadd-patch\fR is the non-interactive version of \fBedit-patch\fR.
+The patch will be incorporated but no editor or subshell will be
+spawned.
+
+.SH AUTHORS
+\fBedit-patch\fR was written by Daniel Holbach <daniel.holbach@canonical.com>,
+Michael Vogt <michael.vogt@canonical.com>, and David Futcher <bobbo@ubuntu.com>.
+
+This manual page was written by Andrew Starr-Bochicchio <a.starr.b@gmail.com>.
+.PP
+Both are released under the terms of the GNU General Public License, version 3.
diff --git a/doc/genmanpage.pl b/doc/genmanpage.pl
new file mode 100755
index 0000000..9d33c15
--- /dev/null
+++ b/doc/genmanpage.pl
@@ -0,0 +1,30 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+# Define item leadin/leadout for man output
+my $ITEM_LEADIN = '.IP "\fI';
+my $ITEM_LEADOUT = '\fR(1)"';
+
+my $package;
+my $description;
+
+
+# Parse the shortened README file
+while (<>) {
+ chomp;
+ # A line starting with ' -' indicates a script
+ if (/^ - ([^:]*): (.*)/) {
+ if ($package and $description) {
+ # If we get here, then we need to output the man code
+ print $ITEM_LEADIN . $package . $ITEM_LEADOUT . "\n";
+ print $description . "\n";
+ }
+ $package = $1;
+ $description = $2;
+ } else {
+ s/^ //;
+ $description .= $_;
+ }
+}
diff --git a/doc/suspicious-source.1 b/doc/suspicious-source.1
new file mode 100644
index 0000000..045a0c6
--- /dev/null
+++ b/doc/suspicious-source.1
@@ -0,0 +1,55 @@
+.\" Copyright (c) 2010, Benjamin Drung <bdrung@debian.org>
+.\"
+.\" Permission to use, copy, modify, and/or distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.TH SUSPICIOUS\-SOURCE 1 "Debian Utilities" "DEBIAN"
+
+.SH NAME
+suspicious\-source \- search for files that do not meet the GPL's
+definition of "source" for a work
+
+.SH SYNOPSIS
+\fBsuspicious\-source\fP [\fIoptions\fR]
+
+.SH DESCRIPTION
+\fBsuspicious\-source\fP outputs a list of files which are probably not
+the source form of a work.
+This should be run in the root of a source tree to find files which
+might not be, in the definition from the GNU GPL, the "preferred form
+of the work for making modifications to it".
+.PP
+The files inside version control system directories (like
+\fI.bzr/\fR or \fICVS/\fR) are not considered.
+
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show this help message and exit.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Print more information.
+.TP
+\fB\-d \fIdirectory\fR, \fB\-\-directory=\fIdirectory\fR
+Check the files in the specified \fIdirectory\fR instead of the current directory.
+.TP
+\fB\-m \fImimetype\fR, \fB\-\-mimetype=\fImimetype\fR
+Add \fImimetype\fR to list of white-listed MIME types.
+.TP
+\fB\-e \fIextension\fR, \fB\-\-extension=\fIextension\fR
+Add \fIextension\fR to list of white-listed extensions.
+
+.SH AUTHORS
+\fBsuspicious\-source\fP and this manpage have been written by
+Benjamin Drung <bdrung@debian.org>.
+.PP
+Both are released under the ISC license.
diff --git a/doc/what-patch.1 b/doc/what-patch.1
new file mode 100644
index 0000000..4e127d0
--- /dev/null
+++ b/doc/what-patch.1
@@ -0,0 +1,42 @@
+.TH WHAT\-PATCH "1" "Debian Utilities" "DEBIAN"
+.SH NAME
+what\-patch \- detect which patch system a Debian package uses
+
+.SH SYNOPSIS
+.B what\-patch\fR [\fIoptions\fR]
+
+.SH DESCRIPTION
+\fBwhat\-patch\fR examines the \fIdebian/rules\fR file to determine which patch
+system the Debian package is using.
+.PP
+\fBwhat\-patch\fR should be run from the root directory of the Debian source
+package.
+
+.SH OPTIONS
+Listed below are the command line options for \fBwhat\-patch\fR:
+.TP
+.BR \-h ", " \-\-help
+Display a help message and exit.
+.TP
+.B \-v
+Enable verbose mode.
+This will include the listing of any files modified outside or the \fIdebian/\fR
+directory and report any additional details about the patch system if
+available.
+
+.SH AUTHORS
+\fBwhat\-patch\fR was written by Kees Cook <kees@ubuntu.com>,
+Siegfried-A. Gevatter <rainct@ubuntu.com>, and Daniel Hahler
+<ubuntu@thequod.de>, among others.
+This manual page was written by Jonathan Patrick Davies <jpds@ubuntu.com>.
+.PP
+Both are released under the GNU General Public License, version 3 or later.
+
+.SH SEE ALSO
+The Ubuntu MOTU team has some documentation about patch systems at the Ubuntu
+wiki: \fIhttps://wiki.ubuntu.com/PackagingGuide/PatchSystems\fR
+
+.PP
+.BR cdbs\-edit\-patch (1),
+.BR dbs\-edit\-patch (1),
+.BR dpatch\-edit\-patch (1)
diff --git a/doc/wrap-and-sort.1 b/doc/wrap-and-sort.1
new file mode 100644
index 0000000..fe60902
--- /dev/null
+++ b/doc/wrap-and-sort.1
@@ -0,0 +1,102 @@
+.\" Copyright (c) 2010, Benjamin Drung <bdrung@debian.org>
+.\"
+.\" Permission to use, copy, modify, and/or distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.TH WRAP\-AND\-SORT 1 "Debian Utilities" "DEBIAN"
+.SH NAME
+wrap-and-sort \- wrap long lines and sort items in Debian packaging files
+.SH SYNOPSIS
+.B wrap-and-sort
+[\fIoptions\fR]
+
+.SH DESCRIPTION
+\fBwrap\-and\-sort\fP wraps the package lists in Debian control files. By
+default the lists will only split into multiple lines if the entries are longer
+than the maximum line length limit of 79 characters. \fBwrap\-and\-sort\fP sorts
+the package lists in Debian control files and all \fI.dirs\fR, \fI.docs\fR,
+\fI.examples\fR, \fI.info\fR, \fI.install\fR, \fI.links\fR, \fI.maintscript\fR,
+and \fI.manpages\fR files. Beside that \fBwrap\-and\-sort\fP removes trailing
+spaces in these files.
+.PP
+This script should be run in the root of a Debian package tree. It searches for
+\fIcontrol\fR, \fIcontrol*.in\fR, \fIcopyright\fR, \fIcopyright.in\fR,
+\fIinstall\fR, and \fI*.install\fR in the \fIdebian\fR directory.
+
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show this help message and exit.
+.TP
+\fB\-a\fR, \fB\-\-wrap\-always\fR
+Wrap all package lists in the Debian \fIcontrol\fR file
+even if they do not exceed the line length limit and could fit in one line.
+.TP
+\fB\-s\fR, \fB\-\-short\-indent\fR
+Only indent wrapped lines by one space (default is in\-line with the
+field name).
+.TP
+\fB\-b\fR, \fB\-\-sort\-binary\-packages\fR
+Sort binary package paragraphs by name.
+.TP
+\fB\-k\fR, \fB\-\-keep\-first\fR
+When sorting binary package paragraphs, leave the first one at the top.
+
+Unqualified
+.BR debhelper (7)
+configuration files are applied to the first package.
+.TP
+\fB\-n\fR, \fB\-\-no\-cleanup\fR
+Do not remove trailing whitespaces.
+.TP
+\fB\-t\fR, \fB\-\-trailing-comma\fR
+Add a trailing comma at the end of the sorted fields.
+This minimizes future differences in the VCS commits when additional
+dependencies are appended or removed.
+.TP
+\fB\-d \fIpath\fR, \fB\-\-debian\-directory=\fIpath\fR
+Location of the \fIdebian\fR directory (default: \fI./debian\fR).
+.TP
+\fB\-f \fIfile\fR, \fB\-\-file=\fIfile\fR
+Wrap and sort only the specified \fIfile\fR.
+You can specify this parameter multiple times.
+All supported files will be processed if no files are specified.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Print all files that are touched.
+.TP
+\fB\-\-max\-line\-length=\fImax_line_length\fR
+Set the maximum allowed line length. Package lists in the Debian \fIcontrol\fR
+file that exceed this length limit will be wrapped.
+
+The default maximum line length is 79 characters.
+.TP
+\fB\-N\fR, \fB\-\-dry\-run\fR
+Do not modify any file, instead only print the files that would be modified.
+
+.TP
+\fB\-\-experimental\-rts\-parser\fR
+Enable the experimental round\-trip safe parser. When enabled, most comments
+in deb822 control will be preserved.
+
+The option is a temporary means to enable users to opt-in to this new experimental
+feature. The option will be removed once the new parser is mature enough and is
+ready to unconditionally replace the previous parser.
+
+This option requires python\-debian version 0.1.43 or later to work. However, some
+features will require 0.1.44 or later.
+
+.SH AUTHORS
+\fBwrap\-and\-sort\fP and this manpage have been written by
+Benjamin Drung <bdrung@debian.org>.
+.PP
+Both are released under the ISC license.