diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 26 | ||||
| -rw-r--r-- | doc/devscripts.1.in | 30 | ||||
| -rw-r--r-- | doc/devscripts.conf.5 | 60 | ||||
| -rw-r--r-- | doc/edit-patch.1 | 43 | ||||
| -rw-r--r-- | doc/genmanpage.pl | 30 | ||||
| -rw-r--r-- | doc/suspicious-source.1 | 55 | ||||
| -rw-r--r-- | doc/what-patch.1 | 42 | ||||
| -rw-r--r-- | doc/wrap-and-sort.1 | 90 |
8 files changed, 376 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..8d34397 --- /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 +examples of \fBprocmail\fR and \fBexim\fR scripts 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 100644 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..926384f --- /dev/null +++ b/doc/wrap-and-sort.1 @@ -0,0 +1,90 @@ +.\" 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. + +.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. |