From 6595309086760c3e671484092d01363b1eeb0447 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:26:28 +0000 Subject: [PATCH] * Done chapter 10 now Author: jdg Date: 2001/05/08 00:21:13 * Done chapter 10 now * debiandoc-sgml version 1.1.47 fixes most of the issues, so Text.pm can be removed again * Versioned build-depends for this * Merged changes to LaTeX.pm git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-121 --- DebianDoc_SGML/Format/Text.pm | 593 ----------------- debian/control | 2 +- policy.sgml | 1180 ++++++++++++++++++--------------- 3 files changed, 644 insertions(+), 1131 deletions(-) delete mode 100644 DebianDoc_SGML/Format/Text.pm diff --git a/DebianDoc_SGML/Format/Text.pm b/DebianDoc_SGML/Format/Text.pm deleted file mode 100644 index 1567033..0000000 --- a/DebianDoc_SGML/Format/Text.pm +++ /dev/null @@ -1,593 +0,0 @@ -## -*- perl -*- -## ---------------------------------------------------------------------- -## DebianDoc_SGML/Format/Text: SGML conversion specification for plain text output format -## ---------------------------------------------------------------------- -## Copyright (C) 1998-2001 Ardo van Rangelrooij -## Copyright (C) 1996 Ian Jackson -## -## This is free software; see the GNU General Public Licence -## version 2 or later for copying conditions. There is NO warranty. -## ---------------------------------------------------------------------- - -## ---------------------------------------------------------------------- -## package interface definition -package DebianDoc_SGML::Format::Text; -use strict; -use vars qw( @ISA @EXPORT ); -use Exporter; -@ISA = ( 'Exporter' ); -@EXPORT = qw (); - -## ---------------------------------------------------------------------- -## import packages -use SGMLS::Output; -use Text::Format; - -## ---------------------------------------------------------------------- -## layout definitions -my $perindent = 5; -my $linewidth = 79; -my $textwidth = 75; -my $unbreakbackoff = 20; -$DebianDoc_SGML::Format::Driver::indent_level = 1; -my $text = new Text::Format; -$text->columns( $linewidth ); -$text->leftMargin( $perindent - 1 ); -$text->rightMargin( $perindent - 1 ); -$text->extraSpace( 1 ); -$text->firstIndent( 0 ); - -## ---------------------------------------------------------------------- -## global variables -use vars qw( $blanklinedone $paralhindents $paralhtag @stylestack @b @u ); -use vars qw( @footnotes @comments @comment_editors ); - -## ---------------------------------------------------------------------- -## book output subroutines -## ---------------------------------------------------------------------- -sub _output_start_book -{ -} -sub _output_end_book -{ - _output_footnotes() if ( @footnotes ); - _output_comments() if ( @comments ); - output( "\n" ); - output( "\n" ); - output( ( "-" x $linewidth ) . "\n" ); - output( "\n" ); - output( "\n" ); - _para_new(); - output( $DebianDoc_SGML::Format::Driver::title ); - _para_end( 1 ); - output( "\n" ); - foreach ( @DebianDoc_SGML::Format::Driver::authors ) - { - _para_new(); - output( $_ ); - _para_end( 1 ); - } - output( "\n" ); - _para_new(); - output( $DebianDoc_SGML::Format::Driver::version ) - if length( $DebianDoc_SGML::Format::Driver::version ); - _para_end( 1 ); - output( "\n" ); -} - -## ---------------------------------------------------------------------- -## title page output subroutines -## ---------------------------------------------------------------------- -sub _output_titlepag -{ - output( "\n" ); - _para_new(); - output( $DebianDoc_SGML::Format::Driver::title ); - _para_end( 0, 'centre-underdash' ); - foreach ( @DebianDoc_SGML::Format::Driver::authors ) - { - output( "\n" ); - _para_new(); - output( $_ ); - _para_end( 0, 'centre' ); - } - if ( length( $DebianDoc_SGML::Format::Driver::version ) ) - { - output( "\n" ); - _para_new(); - output( $DebianDoc_SGML::Format::Driver::version ); - _para_end( 0, 'centre' ); - } - output( "\n" ); - output( "\n" ); - output( ( "-" x $linewidth ) . "\n" ); - if ( length( $DebianDoc_SGML::Format::Driver::abstract ) ) - { - _output_heading( $DebianDoc_SGML::Format::Driver::i18n{ 'abstract' } ); - output( $DebianDoc_SGML::Format::Driver::abstract ); - } - if ( length ( $DebianDoc_SGML::Format::Driver::copyright ) ) - { - _output_heading( $DebianDoc_SGML::Format::Driver::i18n{ 'copyright notice' } ); - output( $DebianDoc_SGML::Format::Driver::copyright ); - } -} -sub _output_copyrightsummaries -{ - output( "\n" ); - foreach ( @_ ) - { - _para_new(); - output( $_ ); - _para_end( $DebianDoc_SGML::Format::Driver::indent_level ); - } -} - -## ---------------------------------------------------------------------- -## table of contents output subroutines -## ---------------------------------------------------------------------- -sub _output_toc -{ - _output_heading( $DebianDoc_SGML::Format::Driver::i18n{ 'contents' }, -1 ); - output( $_[0] ); -} -sub _output_tocentry -{ - return if $_[1] > $DebianDoc_SGML::Format::Driver::toc_detail; - output( "\n" ) if $_[1] == -1; - _para_lhtag( "$_[2]." ); - _para_lhtag( '' ); - _para_lhtag( '' ) if $_[1] > 0; - _para_new(); - output( $_[0] ); - _para_end( $_[1] > 0 ? 4 : 3 ); -} - -## ---------------------------------------------------------------------- -## section output subroutines -## ---------------------------------------------------------------------- -sub _output_chapter -{ - output( $_[0] ); -} -sub _output_appendix -{ - output( $_[0] ); -} -sub _output_heading -{ - _output_footnotes() if ( @footnotes ); - _output_comments() if ( @comments ); - output( "\n" ); - if ( $_[1] < 0 ) - { - output( "\n" ); - output( ( "-" x $linewidth ) . "\n" ); - output( "\n" ); - } - output( "\n" ) if $_[1] <= 0; - _para_new(); - output( "$_[2]. " ) if length( $_[2] ); - output( "$_[0]" ); - _para_end( 0, 'underdash' ); -} - -## ---------------------------------------------------------------------- -## paragraph output subroutines -## ---------------------------------------------------------------------- -sub _output_p -{ - if ( length( $_[0] ) ) - { - _insert_blankline(); - $blanklinedone = 0; - my $indent = 0; - if ( length( $paralhtag ) ) - { - output( " " - x ( $perindent - * ( $DebianDoc_SGML::Format::Driver::indent_level - - $paralhindents ) ) ); - output( _emph_string( $paralhtag ) ); - $indent = ( $DebianDoc_SGML::Format::Driver::indent_level ) - * $perindent; - $paralhtag = ''; - $paralhindents = 0; - } - $text->leftMargin( $DebianDoc_SGML::Format::Driver::indent_level - * $perindent ); - my $para = $text->format( $_[0] ); - output( substr( $para, $indent ) ); - } - else - { - output( "\n" ) - if ( $DebianDoc_SGML::Format::Driver::is_special - && ! $DebianDoc_SGML::Format::Driver::is_compact - && $DebianDoc_SGML::Format::Driver::will_be_compact ); - } -} -sub _insert_blankline -{ - if ( ! $DebianDoc_SGML::Format::Driver::is_compact - && ! $DebianDoc_SGML::Format::Driver::was_compact - && ! $blanklinedone ) - { - output( "\n" ); - $blanklinedone = 1; - } -} -sub _para_lhtag -{ - $paralhindents++; - $paralhtag .= $_[0]; - $paralhtag .= ' ' x ( $paralhindents * $perindent - length( $paralhtag ) ); -} -sub _para_new -{ - @stylestack = (); - push_output( 'string' ); -} -sub _para_end -{ - my ( $inum, $fmt, $lhtagdefer ) = @_; - # fmt is one of undef,'centre','centre-underdash','underdash' - # lhtagdefer is 1 if we can safely defer a paralhtag til later - my $pd = pop_output(); - @b = @u = ( 0 ); - my ( $here, $maxwidth, $evstr, $pis, $pil, $npis, $av, $ls_pis, $ls_pil ); - my ( $nobreak, $code, $reducedwidth, $indentdone, $lhs ); - my $centre = ( $fmt eq 'centre' || $fmt eq 'centre-underdash' ); - my $udash = ( $fmt eq 'underdash' || $fmt eq 'centre-underdash' ); - $maxwidth = 0; - return if $pd !~ m/\S/ && ( $lhtagdefer || ! length( $paralhtag ) ); - if ( length( $paralhtag ) ) - { - output( " " x ( $perindent * ( $inum - $paralhindents ) ) ); - output( _emph_string( $paralhtag ) ); - $reducedwidth = length( $paralhtag ) - ( $perindent * $paralhindents ); - $reducedwidth = 0 if $reducedwidth < 0; - $paralhtag = ''; - $indentdone = 1; - $paralhindents = 0; - } - outer: - while ( length( $pd ) ) - { - next if ! $nobreak && $pd =~ s/^\s+//; - $pil = 0; - $av = $textwidth - $perindent * $inum - $reducedwidth; - $pis = 0; - $reducedwidth = 0; - $ls_pis = -1; - while ( $pis < length( $pd ) && ( $nobreak || $pil <= $av ) ) - { - $here = substr( $pd, $pis, 1 ); - if ( $here eq "\0" ) - { - $code = substr( $pd, $pis + 1, 2 ); - if ( $code eq '=o' ) - { - last if $pis; - $nobreak = 1; - $lhs = 0; - } - elsif ( $code eq '=l' ) - { - last if $pis || $indentdone; - $nobreak = 1; - $lhs = 1; - } - elsif ( $code eq '=c' ) - { - last if $pis; - $nobreak = 0; - $lhs = 0; - } - elsif ( $code eq '=n' ) - { - $pis += 4; - last; - } - else - { - $pis += 4; - next; - } - $pd = substr( $pd, 4 ); - next outer; - } - if ( ! $nobreak && $here =~ m/^\s$/ ) - { - $here = substr( $pd, $pis ); - $here =~ s/^\s+/ /; - $pd = substr( $pd, 0, $pis ) . $here; - $ls_pis = $pis; - $ls_pil = $pil; - } - if ( $ls_pis < 0 && $pil >= $av - $unbreakbackoff ) - { - $ls_pis = $pis; - $ls_pil = $pil; - } - $pis++; - $pil++; - } - if ( ! $nobreak && $pil > $av ) - { - $pis = $ls_pis; - $ls_pil = $pil; - } - $maxwidth = $pil if $pil > $maxwidth; - output( ' ' x ( ( $centre ? ( $textwidth - $pil ) / 2 : 0 ) - + ( $lhs ? 0 : ( $inum + $nobreak ) * $perindent ) ) ) - if ! $indentdone; - output( _emph_string( substr( $pd, 0, $pis ) ) ); - output( "\n" ); - $indentdone = 0; - $pd = substr( $pd, $pis ); - } - if ( $udash ) - { - output( ' ' x ( ( $centre ? ( $textwidth - $maxwidth ) / 2 : 0 ) - + ( $inum * $perindent ) ) ); - output( ( $b[0] ? "--" : "-" ) x $maxwidth . "\n" ); - } - $blanklinedone = 0; -} -sub _emph_string -{ - my ( $string ) = @_; - my ( $i, $here, $ar, $sv, $es ); - for ( $i = 0; $i < length( $string ); $i++ ) - { - $here = substr( $string, $i, 1 ); - if ( $here eq "\0" ) - { - $ar = substr( $string, $i + 1, 1 ); - $sv = substr( $string, $i + 2, 1 ); - if ( $sv eq '-' ) - { - $es = "shift(\@$ar);1;"; - eval $es || die "$@ / $es"; - } - elsif ( $sv ne '=' ) - { - $es = "unshift(\@$ar,\$sv);1;"; - eval $es || die "$@ / $es"; - } - $i += 3; - next; - } - if ( $b[0] ) - { - output( "$here" ); - } - elsif ( $u[0] ) - { - output( "_" ); - } - output( $here ); - } - return; -} - -## ---------------------------------------------------------------------- -## example output subroutines -## ---------------------------------------------------------------------- -sub _output_example -{ - $_[0] =~ s/[ \t]+\n/\n/g; - $_[0] =~ s/^\n+//; - my @el = split( /\n/, $_[0] ); - my @ec = @el; - grep( s/\0..\0//g, @ec ); - my @toolong = grep( length( $_ ) - + ( $perindent - * ( $DebianDoc_SGML::Format::Driver::indent_level - + 1 ) ) - > $linewidth, @ec ); - _insert_blankline(); - push_output( 'string' ); - output( @toolong ? "\0=l\0" : "\0=o\0" ); - output( join( "\0=n\0", @el ) ); - output( "\0=c\0" ); - _para_new(); - output( pop_output() ); - _para_end( $DebianDoc_SGML::Format::Driver::indent_level ); -} - -## ---------------------------------------------------------------------- -## footnote output subroutines -## ---------------------------------------------------------------------- -sub _output_footnotes -{ - my $footnoteref = 1; - foreach my $footnote ( @footnotes ) - { - _insert_blankline(); - _para_lhtag( "[$footnoteref]" ); - _para_new(); - output( $footnote ); - _para_end( $DebianDoc_SGML::Format::Driver::indent_level ); - $blanklinedone = 0; - $footnoteref++; - } - @footnotes = (); -} -sub _output_footnote -{ - push( @footnotes, $_[0] ); - output( "[" . scalar( @footnotes ) . "]" ); -} - -## ---------------------------------------------------------------------- -## comment output subroutines -## ---------------------------------------------------------------------- -sub _output_comments -{ - my $commentref = 1; - foreach my $comment ( @comments ) - { - _insert_blankline(); - _para_lhtag( "[c$commentref]" ); - my $editor = $comment_editors[$commentref - 1]; - _para_lhtag( "($editor) " ) if length( $editor); - _para_new(); - output( $comment ); - _para_end( $DebianDoc_SGML::Format::Driver::indent_level ); - $blanklinedone = 0; - $commentref++; - } - @comments = (); - @comment_editors = (); -} -sub _output_comment -{ - push( @comments, $_[0] ); - push( @comment_editors, $_[1] ); - output( "[c" . scalar( @comments ) . "]" ); -} - -## ---------------------------------------------------------------------- -## list output subroutines -## ---------------------------------------------------------------------- -sub _output_list -{ - output( $_[0] ); -} -sub _output_enumlist -{ - output( $_[0] ); -} -sub _output_taglist -{ - output( $_[0] ); -} -sub _output_list_tag -{ - _para_lhtag( ( ' ' x ( $perindent - 2 ) ) . '*' ); -} -sub _output_enumlist_tag -{ - _para_lhtag( $DebianDoc_SGML::Format::Driver::item_counter++ . '.' ); -} -sub _output_taglist_tag -{ -} -sub _output_list_item -{ - output( $_[0] ); -} -sub _output_enumlist_item -{ - output( $_[0] ); -} -sub _output_taglist_item -{ - $_[0] =~ s/^\n+//; - _insert_blankline(); - foreach ( @{$_[1]} ) - { - _para_new(); - output( $_ ); - _para_end( $DebianDoc_SGML::Format::Driver::indent_level - 1 ); - } - output( $_[0] ); -} - -## ---------------------------------------------------------------------- -## emph output subroutines -## ---------------------------------------------------------------------- -sub _output_em -{ - output( "_$_[0]_" ); -} -sub _output_strong -{ - output( "_$_[0]_" ); -} -sub _output_var -{ - output( "<$_[0]>" ); -} -sub _output_package -{ - output( "`$_[0]'" ); -} -sub _output_prgn -{ - output( "`$_[0]'" ); -} -sub _output_file -{ - output( "`$_[0]'" ); -} -sub _output_tt -{ - output( "`$_[0]'" ); -} -sub _output_qref -{ - output( $_[0] ); -} - -## ---------------------------------------------------------------------- -## xref output subroutines -## ---------------------------------------------------------------------- -sub _output_ref -{ - my ( $name, $number ) = split( / /, $_[1], 2 ); - output( "$DebianDoc_SGML::Format::Driver::i18n{$name} $number, `$_[0]'" ); -} -sub _output_manref -{ - output( "$_[0]($_[1])" ); -} -sub _output_email -{ - output( ' ' ) if $DebianDoc_SGML::Format::Driver::in_author; - output( "<$_[0]>" ); -} -sub _output_ftpsite -{ - output( $_[0] ); -} -sub _output_ftppath -{ - output( $_[1] ); -} -sub _output_httpsite -{ - output( $_[0] ); -} -sub _output_httppath -{ - output( $_[1] ); -} -sub _output_url -{ - output( $_[1] ) if $_[1] ne ''; - output( ' (' ) if $_[1] ne ''; - output( $_[0] ); - output( ')' ) if $_[1] ne ''; -} - -## ---------------------------------------------------------------------- -## data output subroutines -## ---------------------------------------------------------------------- -sub _cdata -{ - output( $_[0] ); -} -sub _sdata -{ - output( $DebianDoc_SGML::Format::Driver::sdata_mapping{ $_[0] } ) - if defined( $DebianDoc_SGML::Format::Driver::sdata_mapping{ $_[0] } ); -} - -## ---------------------------------------------------------------------- -## don't forget this -1; - -## ---------------------------------------------------------------------- diff --git a/debian/control b/debian/control index f878a4e..e657f4e 100644 --- a/debian/control +++ b/debian/control @@ -3,7 +3,7 @@ Section: doc Priority: optional Maintainer: Debian Policy List Standards-Version: ${debian-policy:Version} -Build-Depends-Indep: links, debiandoc-sgml, sp, liburi-perl, libpaperg, tetex-bin, tetex-extra, latex2html, libi18n-langtags-perl, groff, bsdmainutils, pstoedit, tidy, jade, docbook-xml +Build-Depends-Indep: links, debiandoc-sgml (>= 1.1.47), sp, liburi-perl, libpaperg, tetex-bin, tetex-extra, latex2html, libi18n-langtags-perl, groff, bsdmainutils, pstoedit, tidy, jade, docbook-xml Package: debian-policy Architecture: all diff --git a/policy.sgml b/policy.sgml index 1539895..432861e 100644 --- a/policy.sgml +++ b/policy.sgml @@ -236,7 +236,7 @@ - + The Debian Archive

The Debian GNU/Linux system is maintained and distributed as a @@ -1088,16 +1088,17 @@

2.5% of Debian packages [see ] - currently use debconf to prompt - the user at install time, and this number is growing - daily. The benefits of using debconf are briefly - explained at ; - they include preconfiguration, (mostly) - noninteractive installation, elimination of - redundant prompting, consistency of user interface, - etc. + id="http://kitenet.net/programs/debconf/stats/" + name="Debconf stats">] currently use + debconf to prompt the user at + install time, and this number is growing daily. The + benefits of using debconf are briefly explained at + ; they include + preconfiguration, (mostly) noninteractive + installation, elimination of redundant prompting, + consistency of user interface, etc.

With this increasing number of packages using @@ -1146,15 +1147,15 @@

- It also means that an upgrade should not ask the same - questions again, unless the user has used dpkg - --purge to remove the package's configuration. The - answers to configuration questions should be stored in an - appropriate place in /etc so that the user can - modify them, and how this has been done should be - documented.

+ It also means that an upgrade should not ask the same + questions again, unless the user has used dpkg + --purge to remove the package's configuration. The + answers to configuration questions should be stored in an + appropriate place in /etc so that the user can + modify them, and how this has been done should be + documented.

-

+

If a package has a vitally important piece of information to pass to the user (such as "don't run me as I am, you must edit the following configuration files @@ -1169,18 +1170,18 @@ should be in on-line documentation, where all the users can see them).

-

- Any necessary prompting should almost always be confined - to the config or postinst - script. If it is done in the postinst, it - should be protected with a conditional so that unnecessary - prompting doesn't happen if a package's installation fails - and the postinst is called with - abort-upgrade, abort-remove or - abort-deconfigure.

- +

+ Any necessary prompting should almost always be confined + to the config or postinst + script. If it is done in the postinst, it + should be protected with a conditional so that + unnecessary prompting doesn't happen if a package's + installation fails and the postinst is + called with abort-upgrade, + abort-remove or abort-deconfigure.

+ Source packages @@ -1629,7 +1630,7 @@ Package: libc6 frozen

- From time to time, the frozen + From time to time, the testing distribution enters a state of `code-freeze' in anticipation of release as a stable version. During this period of testing only @@ -1683,9 +1684,7 @@ Package: libc6

The version number format is: - -&lsqbepoch:]upstream_version[-debian_revision] - + &lsqbepoch:]upstream_version[-debian_revision]

@@ -2498,8 +2497,8 @@ Package: libc6

- These scripts are the files preinst, - postinst, prerm and postrm in the + These scripts are the files preinst, + postinst, prerm and postrm in the control area of the package. They must be proper executable files; if they are scripts (which is recommended), they must start with the usual #! convention. They should be @@ -3058,13 +3057,13 @@ Package: libc6

- All the maintainer scripts except the postrm + All the maintainer scripts except the postrm are removed.

If we aren't purging the package we stop here. Note - that packages which have no postrm and no + that packages which have no postrm and no conffiles are automatically purged when removed, as there is no difference except for the dpkg status.

@@ -4151,26 +4150,29 @@ libbar 1 bar1 (>= 1.0-1) - The Operating System + The Operating System - File system hierarchy + Filesystem hierarchy - Linux File system Structure + Filesystem Structure

The location of all installed files and directories must - comply with the Linux File system Hierarchy Standard - (FHS). The latest version of this document can be found - alongside this manual or on - . + comply with the Filesystem Hierarchy Standard (FHS), + version 2.1. This can be found in the + debian-policy package or on alongside this manual or on . Specific questions about following the standard may be - asked on debian-devel, or referred to Daniel - Quinlan, the FHS coordinator, at - quinlan@pathname.com.

 - + asked on the debian-devel mailing list, or + referred to Daniel Quinlan, the FHS coordinator, at + quinlan@pathname.com. +

+ Site-specific programs @@ -4179,66 +4181,85 @@ libbar 1 bar1 (>= 1.0-1) As mandated by the FHS, packages must not place any files in /usr/local, either by putting them in the file system archive to be unpacked by dpkg - or by manipulating them in their maintainer scripts.

+ or by manipulating them in their maintainer scripts. +

However, the package may create empty directories below /usr/local so that the system administrator knows - where to place site-specific files. These directories + where to place site-specific files. These directories should be removed on package removal if they are - empty.

+ empty. +

Note, that this applies only to directories below - /usr/local, not in - /usr/local. Packages must not create sub-directories - in the directory /usr/local itself, except those listed in - FHS, section 4.5. However, you may create directories - below them as you wish. You must not remove any of the - directories listed in 4.5, even if you created them.

+ /usr/local, not in /usr/local. + Packages must not create sub-directories in the directory + /usr/local itself, except those listed in FHS, + section 4.5. However, you may create directories below + them as you wish. You must not remove any of the + directories listed in 4.5, even if you created them. +

Since /usr/local can be mounted read-only from a remote server, these directories must be created and - removed by the postinst and prerm - maintainer scripts. These scripts must not fail if either - of these operations fail. (In the future, it will be - possible to tell dpkg not to unpack files - matching certain patterns, so that the directories can be - included in the .deb packages and system - administrators who do not wish these directories in - /usr/local do not need to have them.)

+ removed by the postinst and prerm + maintainer scripts and not be included in the + .deb archive. These scripts must not fail if + either of these operations fail. + +

+ In the future, it may be possible to tell + dpkg not to unpack files matching certain + patterns, so that the directories can be included in + the .deb packages and system administrators + who do not wish these directories in + /usr/local do not need to have them.) +

+ +

- For example, the emacs package will contain + For example, the emacsen-common package could + contain something like -mkdir -p /usr/local/lib/emacs/site-lisp || true +mkdir -p /usr/local/share/emacs/site-lisp || true - in the postinst script, and + in its postinst script, and -rmdir /usr/local/lib/emacs/site-lisp || true -rmdir /usr/local/lib/emacs || true +rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true +rmdir /usr/local/share/emacs 2>/dev/null || true - in the prerm script.

+ in the prerm script. (Note that this form is + used to ensure that if the script is interrupted, the + directory /usr/local/share/emacs will still be + removed.) +

If you do create a directory in /usr/local for local additions to a package, you should ensure that settings in /usr/local take precedence over the - equivalents in /usr.

+ equivalents in /usr. +

- However, because '/usr/local' and its contents are for - exclusive use of the local administrator, a package must - not rely on the presence or absence of files or - directories in '/usr/local' for normal operation.

+ However, because /usr/local and its contents are + for exclusive use of the local administrator, a package + must not rely on the presence or absence of files or + directories in /usr/local for normal operation. +

The /usr/local directory itself and all the subdirectories created by the package should (by default) have permissions 2775 (group-writable and set-group-id) and be - owned by root.staff.

+ owned by root.staff. +

+ The system-wide mail directory

@@ -4255,139 +4276,159 @@ rmdir /usr/local/lib/emacs || true versions of either one of these packages.

- - - Users and groups -

- The Debian system can be configured to use either plain or - shadow passwords.

- -

- Some user ids (UIDs) and group ids (GIDs) are reserved - globally for use by certain packages. Because some packages - need to include files which are owned by these users or - groups, or need the ids compiled into binaries, these ids - must be used on any Debian system only for the purpose for - which they are allocated. This is a serious restriction, and - we should avoid getting in the way of local administration - policies. In particular, many sites allocate users and/or - local system groups starting at 100.

- -

- Apart from this we should have dynamically allocated ids, - which should by default be arranged in some sensible - order, but the behavior should be configurable.

- -

- Packages other than base-passwd must not modify - /etc/passwd, /etc/shadow, - /etc/group or /etc/gshadow.

+ + Introduction +

+ The Debian system can be configured to use either plain or + shadow passwords. +

-

- The UID and GID ranges are as follows: - - 0-99: - -

- Globally allocated by the Debian project, the - same on every Debian system. These ids will appear in - the passwd and group files of all - Debian systems, new ids in this range being added - automatically as the base-passwd package is - updated.

+

+ Some user ids (UIDs) and group ids (GIDs) are reserved + globally for use by certain packages. Because some + packages need to include files which are owned by these + users or groups, or need the ids compiled into binaries, + these ids must be used on any Debian system only for the + purpose for which they are allocated. This is a serious + restriction, and we should avoid getting in the way of + local administration policies. In particular, many sites + allocate users and/or local system groups starting at 100. +

-

- Packages which need a single statically allocated uid - or gid should use one of these; their maintainers - should ask the base-passwd maintainer for - ids.

- +

+ Apart from this we should have dynamically allocated ids, + which should by default be arranged in some sensible + order, but the behavior should be configurable. +

- 100-999: - -

- Dynamically allocated system users and groups. - Packages which need a user or group, but can have this - user or group allocated dynamically and differently on - each system, should use `adduser --system' to - create the group and/or user. adduser - will check for the existence of the user or group, and - if necessary choose an unused id based on the ranges - specified in adduser.conf.

 +

+ Packages other than base-passwd must not modify + /etc/passwd, /etc/shadow, + /etc/group or /etc/gshadow. +

+ + + UID and GID classes +

+ The UID and GID numbers are divided into classes as + follows: + + 0-99: + +

+ Globally allocated by the Debian project, the same + on every Debian system. These ids will appear in + the passwd and group files of all + Debian systems, new ids in this range being added + automatically as the base-passwd package is + updated. +

- 1000-29999: - -

- Dynamically allocated user accounts. By default - adduser will choose UIDs and GIDs for - user accounts in this range, though - adduser.conf may be used to modify this - behavior.

- +

+ Packages which need a single statically allocated + uid or gid should use one of these; their + maintainers should ask the base-passwd + maintainer for ids. +

+ - 30000-59999: - -

Reserved.

 + 100-999: + +

+ Dynamically allocated system users and groups. + Packages which need a user or group, but can have + this user or group allocated dynamically and + differently on each system, should use adduser + --system to create the group and/or user. + adduser will check for the existence of + the user or group, and if necessary choose an unused + id based on the ranges specified in + adduser.conf. +

+ + 1000-29999: + +

+ Dynamically allocated user accounts. By default + adduser will choose UIDs and GIDs for + user accounts in this range, though + adduser.conf may be used to modify this + behavior. +

+ - 60000-64999: - -

- Globally allocated by the Debian project, but only - created on demand. The ids are allocated centrally and - statically, but the actual accounts are only created - on users' systems on demand.

+ 30000-59999: + +

Reserved.

+ -

- These ids are for packages which are obscure or which - require many statically-allocated ids. These packages - should check for and create the accounts in - /etc/passwd or /etc/group (using - adduser if it has this facility) if - necessary. Packages which are likely to require - further allocations should have a `hole' left after - them in the allocation, to give them room to - grow.

 - - - 65000-65533: - -

Reserved.

 + 60000-64999: + +

+ Globally allocated by the Debian project, but only + created on demand. The ids are allocated centrally + and statically, but the actual accounts are only + created on users' systems on demand. +

+

+ These ids are for packages which are obscure or + which require many statically-allocated ids. These + packages should check for and create the accounts in + /etc/passwd or /etc/group (using + adduser if it has this facility) if + necessary. Packages which are likely to require + further allocations should have a `hole' left after + them in the allocation, to give them room to + grow. +

+ - 65534: - -

User `nobody.' The corresponding gid refers - to the group `nogroup.'

 + 65000-65533: + +

Reserved.

+ + 65534: + +

+ User nobody. The corresponding gid refers + to the group nogroup. +

+ - 65535: - -

- (uid_t)(-1) == (gid_t)(-1). NOT TO BE USED, - because it is the error return sentinel value.

- - -

+ 65535: + +

+ (uid_t)(-1) == (gid_t)(-1) must + not be used, because it is the error return + sentinel value. +

+ + +

+ - - System run levels + + System run levels and init.d scripts Introduction

The /etc/init.d directory contains the scripts - executed by init at boot time and when init - state (or `runlevel') is changed (see ).

+ executed by init at boot time and when the + init state (or `runlevel') is changed (see ). +

There are at least two different, yet functionally @@ -4396,20 +4437,23 @@ rmdir /usr/local/lib/emacs || true link method. However, it must not be assumed by maintainer scripts that this method is being used, and any automated manipulation of the various runlevel behaviours by - maintainer scripts must be performed using `update-rc.d' - as described below and not by manually installing or - removing symlinks. For information on the - implementation details of the other method, implemented in - the file-rc package, please refer to the - documentation of that package.

+ maintainer scripts must be performed using + update-rc.d as described below and not by + manually installing or removing symlinks. For information + on the implementation details of the other method, + implemented in the file-rc package, please refer + to the documentation of that package. +

- These scripts are referenced by symbolic links in - the /etc/rcn.d directories. When - changing runlevels, init looks in the - directory /etc/rcn.d for the scripts - it should execute, where n is the runlevel that - is being changed to, or `S' for the boot-up scripts.

+ These scripts are referenced by symbolic links in the + /etc/rcn.d directories. When changing + runlevels, init looks in the directory + /etc/rcn.d for the scripts it should + execute, where n is the runlevel that + is being changed to, or S for the boot-up + scripts. +

The names of the links all have the form @@ -4417,44 +4461,65 @@ rmdir /usr/local/lib/emacs || true Kmmscript where mm is a two-digit number and script is the name of the script (this should be the same as the - name of the actual script in /etc/init.d.

+ name of the actual script in /etc/init.d). +

When init changes runlevel first the targets - of the links whose names starting with a K are + of the links whose names start with a K are executed, each with the single argument stop, followed by the scripts prefixed with an S, each - with the single argument start. The K - links are responsible for killing services and the - S link for starting services upon entering the - runlevel.

+ with the single argument start. (The links are + those in the /etc/rcn.d directory + corresponding to the new runlevel.) The K links + are responsible for killing services and the S + link for starting services upon entering the runlevel. +

For example, if we are changing from runlevel 2 to runlevel 3, init will first execute all of the K prefixed scripts it finds in /etc/rc3.d, and then - all of the S prefixed scripts. The links - starting with K will cause the referred-to file - to be executed with an argument of stop, and the - S links with an argument of start.

- -

- The two-digit number mm is used to decide which - order to start and stop things in: low-numbered links have - their scripts run first. For example, the K20 - scripts will be executed before the K30 scripts. - This is used when a certain service must be started before - another. For example, the name server bind - might need to be started before the news server - inn so that inn can set up its - access lists. In this case, the script that starts - bind would have a lower number than the - script that starts inn so that it runs first: + all of the S prefixed scripts in that directory. + The links starting with K will cause the + referred-to file to be executed with an argument of + stop, and the S links with an argument + of start. +

+ +

+ The two-digit number mm is used to determine + the order in which to run the scripts: low-numbered links + have their scripts run first. For example, the + K20 scripts will be executed before the + K30 scripts. This is used when a certain service + must be started before another. For example, the name + server bind might need to be started before + the news server inn so that inn + can set up its access lists. In this case, the script + that starts bind would have a lower number + than the script that starts inn so that it + runs first: /etc/rc2.d/S17bind /etc/rc2.d/S70inn

+ +

+ The two runlevels 0 (halt) and 6 (reboot) are slightly + different. In these runlevels, the links with an + S prefix are still called after those with a + K prefix, but they too are called with the single + argument stop. +

+ +

+ Also, if the script name ends .sh, the script + will be sourced in runlevel S rather that being + run in a forked subprocess, but will be explicitly run by + sh in all other runlevels. +

@@ -4508,70 +4573,91 @@ rmdir /usr/local/lib/emacs || true should behave as if the configuration has been reloaded successfully.

+

+ The /etc/init.d scripts should be treated as + configuration files, either by marking them as + conffiles or managing them correctly in the + maintainer scripts (see ). This is + important since we want to give the local system + administrator the chance to adapt the scripts to the local + system, e.g., to disable a service without de-installing + the package, or to specify some special command line + options when starting a service, while making sure her + changes aren't lost during the next package upgrade. +

+

These scripts should not fail obscurely when the configuration files remain but the package has been removed, as configuration files remain on the system after - the package has been removed. Only when dpkg + the package has been removed. Only when dpkg is executed with the --purge option will - configuration files be removed. In particular, the init - script itself is usually a configuration file (see - ), and will remain on the system if - the package is removed but not purged. Therefore, you + configuration files be removed. In particular, as the + /etc/init.d/package script itself is + usually a conffile, it will remain on the system + if the package is removed but not purged. Therefore, you should include a test statement at the top of the script, like this: test -f program-executed-later-in-script || exit 0 -

+ +

- Often there are some values in the `init.d' - scripts that a system administrator will frequently want - to change. While the scripts are frequently conffiles, - modifying them requires that the administrator merge in - their changes each time the package is upgraded and the - conffile changes. To ease the burden on the system - administrator, such configurable values should not be - placed directly in the script. Instead, they should be - placed in a file in `/etc/default', which - typically will have the same base name as the - `init.d' script. This extra file can be sourced - by the script when the script runs. It must contain only - variable settings and comments. + Often there are some variables in the init.d + scripts whose values control the bahaviour of the scripts, + and which a system administrator is likely to want to + change. As the scripts themselves are frequently + conffiles, modifying them requires that the + administrator merge in their changes each time the package + is upgraded and the conffile changes. To ease + the burden on the system administrator, such configurable + values should not be placed directly in the script. + Instead, they should be placed in a file in + /etc/default, which typically will have the same + base name as the init.d script. This extra file + should be sourced by the script when the script runs. It + must contain only variable settings and comments in POSIX + sh format. It should not be a + conffile, but a configuration file maintained by + the package maintainer scripts. See for more details.

To ensure that vital configurable values are always - available, the `init.d' script should set default - values for each of the shell variables it uses before - sourcing the /etc/default/ file. Also, since the - `/etc/default/' file is often a conffile, the - `init.d' script must behave sensibly without - failing if it is deleted. + available, the init.d script should set default + values for each of the shell variables it uses, either + before sourcing the /etc/default/ file or + afterwards using something like the : + ${VAR:=default} syntax. Also, the init.d + script must behave sensibly and not fail if the + /etc/default file is deleted.

- Managing the links

- The program update-rc.d is provided to make - it easier for package maintainers to arrange for the - proper creation and removal of - /etc/rcn.d symbolic links, or their - functional equivalent if another method is being used. - This may be used by maintainers in their packages' - postinst and postrm scripts.

+ The program update-rc.d is provided for + package maintainers to arrange for the proper creation and + removal of /etc/rcn.d symbolic links, + or their functional equivalent if another method is being + used. This may be used by maintainers in their packages' + postinst and postrm scripts.

- You must use this script to make changes to - /etc/rcn.d and never either - include any /etc/rcn.d symbolic links - in the actual archive or manually create or remove the - symbolic links in maintainer scripts. (The latter will - fail if an alternative method of maintaining runlevel - information is being used.)

+ You must not include any /etc/rcn.d + symbolic links in the actual archive or manually create or + remove the symbolic links in maintainer scripts; you must + use the update-rc.d program instead. (The + former will fail if an alternative method of maintaining + runlevel information is being used.) You must not include + the /etc/rcn.d directories themselves + in the archive either. (Only the sysvinit + package may do so.) +

By default update-rc.d will start services in @@ -4579,37 +4665,41 @@ test -f program-executed-later-in-script || exit 0 and stop them in the halt runlevel (0), the single-user runlevel (1) and the reboot runlevel (6). The system administrator will have the opportunity to customize - runlevels by either running update-rc.d, by - simply adding, moving, or removing the symbolic links in - /etc/rcn.d if symbolic links are being - used, or by modifying /etc/runlevel.conf if the - file-rc method is being used.

+ runlevels by simply adding, moving, or removing the + symbolic links in /etc/rcn.d if + symbolic links are being used, or by modifying + /etc/runlevel.conf if the file-rc method + is being used. +

To get the default behavior for your package, put in your - postinst script + postinst script update-rc.d package defaults >/dev/null - and in your postrm + and in your postrm -if [ purge = "$1" ]; then +if [ "$1" = purge ]; then update-rc.d package remove >/dev/null fi

This will use a default sequence number of 20. If it does - not matter when or in which order the script is run, use - this default. If it does, then you should talk to the - maintainer of the sysvinit package or post to - debian-devel, and they will help you choose a - number.

+ not matter when or in which order the init.d + script is run, use this default. If it does, then you + should talk to the maintainer of the sysvinit + package or post to debian-devel, and they will + help you choose a number. +

For more information about using update-rc.d, please consult its manpage .

 + section="8">. +

+ @@ -4623,33 +4713,6 @@ fi described in . Packages must not place files in /etc/rc.boot.

- - Notes - -

- Do not include the - /etc/rcn.d/* symbolic links in the - .deb file system archive! This will cause - problems! You must create them with - update-rc.d, as above.

- -

- Do not include the - /etc/rcn.d/* symbolic links in - dpkg's conffiles list! This will cause - problems! You should, however, treat the - /etc/init.d scripts as configuration files, - either by marking them as conffiles or managing them - correctly in the maintainer scripts (see - ). (This is important since we want - to give the local system administrator the chance to adapt - the scripts to the local system, e.g., to disable a - service without de-installing the package, or to specify - some special command line options when starting a - service, while making sure her changes aren't lost during - the next package upgrade.)

- - Example @@ -4661,11 +4724,12 @@ fi appropriately bind. As you can see, the script interprets the argument reload to send the nameserver a HUP signal (causing it to reload its - configuration); this way the user can say + configuration); this way the system administrator can say /etc/init.d/bind reload to reload the name server. The script has one configurable value, which can be used to pass parameters to the named program at - startup. + startup; this value is read from + /etc/default/bind (see below).

@@ -4722,11 +4786,12 @@ exit 0

- Complementing the above init script is a file - '/etc/default/bind', which contains configurable - parameters used by the script. -

-

+ Complementing the above init script is a configuration + file /etc/default/bind, which contains + configurable parameters used by the script. This would be + created by the postinst script if it was not + already present, and removed on purge by the + postrm script. # Specified parameters to pass to named. See named(8). # You may uncomment the following line, and edit to taste. @@ -4735,118 +4800,77 @@ exit 0

- Another example on which to base your /etc/init.d - scripts is in /etc/init.d/skeleton.

+ Another example on which you can base your + /etc/init.d scripts is found in + /etc/init.d/skeleton. +

If this package is happy with the default setup from update-rc.d, namely an ordering number of 20 and having named running in all runlevels, it can say in - its postinst: + its postinst: update-rc.d bind defaults >/dev/null - And in its postrm, to remove the links when the + And in its postrm, to remove the links when the package is purged: -if [ purge = "$1" ]; then +if [ "$1" = purge ]; then update-rc.d bind remove >/dev/null fi -

- - - - Cron jobs - -

- Packages must not modify the configuration file - /etc/crontab, and they must not modify the files in - /var/spool/cron/crontabs.

- -

- If a package wants to install a job that has to be executed - via cron, it should place a file with the name of the - package in one of the following directories: - -/etc/cron.daily -/etc/cron.weekly -/etc/cron.monthly - - As these directory names imply, the files within them are - executed on a daily, weekly, or monthly basis, - respectively. The exact times are listed in - /etc/crontab.

- -

- All files installed in any of these directories must be - scripts (shell scripts, Perl scripts, etc.) so that they can - easily be modified by the local system administrator. In - addition, they should be treated as configuration files.

- -

- If a certain job has to be executed more frequently than - daily, the package should install a file - /etc/cron.d/package. This file uses - the same syntax as /etc/crontab and is processed by - cron automatically. The file must also be - treated as a configuration file. (Note, that entries in the - /etc/cron.d directory are not handled by - anacron. Thus, you should only use this - directory for jobs which may be skipped if the system is not - running.)

- -

- The scripts or crontab entries in these directories should - check if all necessary programs are installed before they - try to execute them. Otherwise, problems will arise when a - package was removed but not purged since configuration files - are kept on the system in this situation.

+ +

+ - Console messages + Console messages from init.d scripts

- This section describes different formats for messages + This section describes the formats to be used for messages written to standard output by the /etc/init.d - scripts. The intent is to improve the consistency of - Debian's startup and shutdown look and feel.

- -

- Please look very careful at the details. We want to get the - messages to look exactly the same way concerning spaces, - punctuation, and case of letters.

+ scripts. The intent is to improve the consistency of + Debian's startup and shutdown look and feel. For this + reason, please look very carefully at the details. We want + the messages to have the same format in terms of wording, + spaces, punctuation and case of letters. +

Here is a list of overall rules that you should use when you - create output messages. They can be useful if you have a - non-standard message that isn't covered in the sections - below.

+ create output messages. They can be useful if you have a + non-standard message that is not covered specifically in the + sections below. +

- Every message should cover one line, start with a - capital letter and end with a period `.'.

- + Every message should fit in one line (fewer than 80 + characters), start with a capital letter and end with + a period (.) and line feed ("\n"). +

+

If you want to express that the computer is working on - something (performing a specific task, not starting or - stopping a program), we use an ``ellipsis'', namely - three dots `...'. Note that we don't insert spaces in - front of or behind the dots. If the task has been - completed we write `done.' and a line feed.

 - + something (that is, performing a specific task, not + starting or stopping a program), we use an "ellipsis" + (three dots: ...). Note that we don't insert + spaces before or after the dots. If the task has been + completed we write done. and a line feed. +

+

Design your messages as if the computer is telling you - what he is doing (let him be polite :-) but don't - mention ``him'' directly. For example, if you think - of saying + what he is doing (let him be polite :-), but don't + mention "him" directly. For example, if you think of + saying I'm starting network daemons: nfsd mountd. @@ -4860,37 +4884,43 @@ Starting network daemons: nfsd mountd.

- The following formats should be used

+ There are standard message formats for the following + situations. They should be used by the init.d + scripts. +

-

when daemons get started.

+

When daemons are started

- Use this format if your script starts one or more - daemons. The output should look like this (a single - line, no leading spaces): + If your script starts one or more daemons, the output + should look like this (a single line, no leading + spaces): -Starting <description>: <daemon-1> ... <daemon-n>. +Starting description: daemon-1 ... daemon-n. - The <description> should describe the subsystem - the daemon or set of daemons are part of, while - <daemon-1> up to <daemon-n> denote each - daemon's name (typically the file name of the - program).

+ The description should describe the + subsystem the daemon or set of daemons are part of, + while daemon-1 up to daemon-n + denote each daemon's name (typically the file name of + the program). +

- For example, the output of /etc/init.d/lpd would look like: + For example, the output of /etc/init.d/lpd + would look like: Starting printer spooler: lpd. -

+ +

This can be achieved by saying echo -n "Starting printer spooler: lpd" -start-stop-daemon --start --quiet lpd +start-stop-daemon --start --quiet --exec /usr/sbin/lpd echo "." in the script. If you have more than one daemon to @@ -4903,8 +4933,8 @@ echo -n " ugidd"; start-stop-daemon --start --quiet ugidd echo "." This makes it possible for the user to see what takes - so long and when the final daemon has been - started. You should be careful where to put spaces: In the + so long and when the final daemon has been started. + You should be careful where to put spaces: in the example above the system administrator can easily comment out a line if he don't wants to start a specific daemon, while the displayed message still @@ -4913,57 +4943,65 @@ echo "." -

when something needs to be configured.

+

When a system parameter is being set

- If you have to set up different parameters of the - system upon boot up, you should use this format: + If you have to set up different system parameters + during the system boot, you should use this format: -Setting <parameter> to `<value>'. +Setting parameter to `value'.

- You can use the following echo statement to get the quotes right: + You can use a statement such as the following to get + the quotes right: -echo "Setting DNS domainname to \`"value"'." +echo "Setting DNS domainname to \`$domainname'."

- Note that the left quotation mark (`) is different - from the right ('). + Note that the left quotation mark (`) is + different from the right one (').

-

when a daemon is stopped.

+

When a daemon is stopped or restarted

- When you stop a daemon you should issue a message - similar to the startup message, except that `Starting' - is replaced with `Stopping'.

+ When you stop or restart a daemon, you should issue a + message identical to the startup message, except that + Starting is replaced with Stopping + or Restarting respectively. +

- So stopping the printer daemon will like like this: + For example, stopping the printer daemon will like + like this: Stopping printer spooler: lpd. -

+ +

+ -

when something is executed.

+

When something is executed

There are several examples where you have to run a program at system startup or shutdown to perform a - specific task. For example, setting the system's clock - via `netdate' or killing all processes when the system - comes down. Your message should like this: + specific task, for example, setting the system's clock + using netdate or killing all processes + when the system shuts down. Your message should look + like this: Doing something very useful...done. - You should print the `done.' right after the job has been completed, - so that the user gets informed why he has to wait. You can get this + You should print the done. immediately after + the job has been completed, so that the user is + informed why she has to wait. You can get this behavior by saying echo -n "Doing something very useful..." @@ -4975,48 +5013,91 @@ echo "done." -

when the configuration is reloaded.

+

When the configuration is reloaded

When a daemon is forced to reload its configuration files you should use the following format: -Reloading <daemon's-name> configuration...done. +Reloading description configuration...done. + where description is the same as in the + daemon starting message.

+ +

+ - -

when none of the above rules apply.

+ + Cron jobs -

- If you have to print a message that doesn't fit into - the styles described above, you can use something - appropriate, but please have a look at the overall - rules listed above. -

- - +

+ Packages must not modify the configuration file + /etc/crontab, and they must not modify the files in + /var/spool/cron/crontabs.

+ +

+ If a package wants to install a job that has to be executed + via cron, it should place a file with the name of the + package in one or more of the following directories: + +/etc/cron.daily +/etc/cron.weekly +/etc/cron.monthly + + As these directory names imply, the files within them are + executed on a daily, weekly, or monthly basis, + respectively. The exact times are listed in + /etc/crontab.

+ +

+ All files installed in any of these directories must be + scripts (e.g., shell scripts or Perl scripts) so that they + can easily be modified by the local system administrator. + In addition, they should be treated as configuration + files.

+ +

+ If a certain job has to be executed more frequently than + daily, the package should install a file + /etc/cron.d/package. This file uses the + same syntax as /etc/crontab and is processed by + cron automatically. The file must also be + treated as a configuration file. (Note that entries in the + /etc/cron.d directory are not handled by + anacron. Thus, you should only use this + directory for jobs which may be skipped if the system is not + running.)

+ +

+ The scripts or crontab entries in these directories should + check if all necessary programs are installed before they + try to execute them. Otherwise, problems will arise when a + package was removed but not purged since configuration files + are kept on the system in this situation.

 Menus

- Menu entries should follow the current menu policy as - defined in the file ftp.debian.org in - /debian/doc/package-developer/menu-policy.txt.gz - or your local mirror. In addition, it is included in the - debian-policy package. + Menu entries should follow the current menu policy found in + the menu-policy files in the debian-policy + package. It may also be found on the Debian FTP site + ftp.debian.org as the file + /debian/doc/package-developer/menu-policy.txt.gz, + or in the equivalent location on your local mirror.

- The Debian menu packages provides a unique + The Debian menu package provides a standard interface between packages providing applications and documents, and menu programs (either X window - managers or text-based menu programs as - pdmenu).

+ managers or text-based menu programs such as + pdmenu). +

All packages that provide applications that need not be @@ -5027,31 +5108,33 @@ Reloading <daemon's-name> configuration...done. managers, as well in shells like pdmenu.

- Please refer to the Debian Menu System document - that comes with the menu package for information - about how to register your applications and web - documents.

+ Please also refer to the Debian Menu System + documentation that comes with the menu package for + information about how to register your applications and web + documents. +

- Multimedia handlers

Packages which provide the ability to view/show/play, compose, edit or print MIME types should register themselves - as such following the current MIME support policy as defined - in the file found on ftp.debian.org in - /debian/doc/package-developer/mime-policy.txt.gz - or your local mirror. In addition, it is included in the - debian-policy package. + as such following the current MIME support policy found in + the mime-policy files in the debian-policy + package. It may also be found on the Debian FTP site + ftp.debian.org as the file + /debian/doc/package-developer/mime-policy.txt.gz, + or in the equivalent location on your local mirror.

- MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a - mechanism for encoding files and data streams and providing - meta-information about them, in particular their type (e.g. - audio or video) and format (e.g. PNG, HTML, MP3). + MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) + is a mechanism for encoding files and data streams and + providing meta-information about them, in particular their + type (e.g. audio or video) and format (e.g. PNG, HTML, + MP3).

@@ -5066,13 +5149,14 @@ Reloading <daemon's-name> configuration...done. Keyboard configuration

- To achieve a consistent keyboard configuration (i.e., all - applications interpret a keyboard event the same way) all + To achieve a consistent keyboard configuration so that all + applications interpret a keyboard event the same way, all programs in the Debian distribution must be configured to - comply with the following guidelines.

+ comply with the following guidelines. +

- Here is a list that contains certain keys and their interpretation: + The following keys must have the specified interpretations: <-- @@ -5085,117 +5169,137 @@ Reloading <daemon's-name> configuration...done.

emacs: the help prefix

- The interpretation of any keyboard events should be independent - of the terminal that's used, be it a virtual console, an X - terminal emulator, an rlogin/telnet session, etc.

+ The interpretation of any keyboard events should be + independent of the terminal that is used, be it a virtual + console, an X terminal emulator, an rlogin/telnet session, + etc. +

The following list explains how the different programs - should be set up to achieve this:

+ should be set up to achieve this: +

-

`<--' generates KB_Backspace in - X.

+

<-- generates KB_Backspace + in X.

 -

`Delete' generates KB_Delete in X.

 +

Delete generates KB_Delete in + X.

- X translations are set up to make KB_Backspace - generate ASCII DEL, and to make KB_Delete generate - ESC [ 3 ~ (this is the vt220 escape code for - the `delete character' key). This must be done by - loading the resources using xrdb on all local X - displays, not using the application defaults, so that - the translation resources used correspond to the - xmodmap settings.

 + X translations are set up to make + KB_Backspace generate ASCII DEL, and to make + KB_Delete generate ESC [ 3 ~ (this + is the vt220 escape code for the `delete character' + key). This must be done by loading the X resources + using xrdb on all local X displays, not + using the application defaults, so that the + translation resources used correspond to the + xmodmap settings.

The Linux console is configured to make - `<--' generate DEL, and `Delete' generate - ESC [ 3 ~ (this is the case at the - moment).

 + <-- generate DEL, and Delete + generate ESC [ 3 ~.

-

- X applications are configured so that Backspace - deletes left, and Delete deletes right. Motif + +

+ X applications are configured so that < + deletes left, and Delete deletes right. Motif applications already work like this.

 -

stty erase ^? .

 +

Terminals should have stty erase ^? .

 -

- The `xterm' terminfo entry should have ESC [ 3 - ~ for kdch1, just like TERM=linux and - TERM=vt220.

 + +

+ The xterm terminfo entry should have ESC + [ 3 ~ for kdch1, just as for + TERM=linux and TERM=vt220.

 + + +

+ Emacs is programmed to map KB_Backspace or + the stty erase character to + delete-backward-char, and KB_Delete + or kdch1 to delete-forward-char, and + ^H to help as always.

 -

- Emacs is programmed to map KB_Backspace or the `stty - erase' character to delete-backward-char, and - KB_Delete or kdch1 to delete-forward-char, and - ^H to help as always.

 + +

+ Other applications use the stty erase + character and kdch1 for the two delete keys, + with ASCII DEL being `delete previous character' and + kdch1 being `delete character under + cursor'.

 -

- Other applications use the `stty erase' character and - kdch1 for the two delete keys, with ASCII DEL being - `delete previous character' and kdch1 being `delete - character under cursor'.

 -

+ +

- This will solve the problem except for:

+ This will solve the problem except for the following + cases: +

-

+ +

Some terminals have a <-- key that cannot be made to produce anything except ^H. On these terminals Emacs help will be unavailable on - ^H (assuming that the `stty erase' character - takes precedence in Emacs, and has been set - correctly). M-x help or F1 (if available) can be used - instead.

- -

- Some operating systems use ^H for stty erase. - However, modern telnet versions and all rlogin - versions propagate stty settings, and almost all UNIX - versions honour stty erase. Where the stty settings - are not propagated correctly things can be made to - work by using stty manually.

 - -

+ ^H (assuming that the stty erase + character takes precedence in Emacs, and has been set + correctly). M-x help or F1 (if + available) can be used instead.

 + + +

+ Some operating systems use ^H for stty + erase. However, modern telnet versions and all + rlogin versions propagate stty settings, and + almost all UNIX versions honour stty erase. + Where the stty settings are not propagated + correctly, things can be made to work by using + stty manually.

 + + +

Some systems (including previous Debian versions) use - xmodmap to arrange for both <-- and Delete - to generate KB_Delete. We can change the behavior - of their X clients via the same X resources that we - use to do it for our own, or have our clients be - configured via their resources when things are the - other way around. On displays configured like this - Delete will not work, but <-- + xmodmap to arrange for both + <-- and Delete to generate + KB_Delete. We can change the behavior of + their X clients using the same X resources that we use + to do it for our own clients, or configure our clients + using their resources when things are the other way + around. On displays configured like this + Delete will not work, but <-- will.

 -

- Some operating systems have different kdch1 settings - in their terminfo for xterm and others. On these - systems the Delete key will not work correctly when - you log in from a system conforming to our policy, but + +

+ Some operating systems have different kdch1 + settings in their terminfo database for + xterm and others. On these systems the + Delete key will not work correctly when you + log in from a system conforming to our policy, but <-- will.

- Environment variables

A program must not depend on environment variables to get - reasonable defaults. (That's because these environment + reasonable defaults. (That's because these environment variables would have to be set in a system-wide - configuration file like /etc/profile, which is not supported - by all shells.)

+ configuration file like /etc/profile, which is not + supported by all shells.)

If a program usually depends on environment variables for its @@ -5215,7 +5319,8 @@ Reloading <daemon's-name> configuration...done. BAR=${BAR:-/var/lib/fubar} export BAR exec /usr/lib/foo/foo "$@" -

+ +

Furthermore, as /etc/profile is a configuration @@ -5224,7 +5329,8 @@ exec /usr/lib/foo/foo "$@" file.

 - + + Files @@ -5645,12 +5751,12 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

If a package needs any special device files that are not included in the base system, it must call - MAKEDEV in the postinst script, + MAKEDEV in the postinst script, after asking the user for permission to do so.

Packages must not remove any device files in the - postrm or any other script. This is left to the + postrm or any other script. This is left to the system administrator.

@@ -5783,12 +5889,12 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq the package, but only those necessary to get the package running on a given system. Ideally the sysadmin should not have to do any configuration other than that done - (semi-)automatically by the postinst script.

+ (semi-)automatically by the postinst script.

A common practice is to create a script called package-configure and have the - package's postinst call it if and only if the + package's postinst call it if and only if the configuration file does not already exist. In certain cases it is useful for there to be an example or template file which the maintainer scripts use. Such files should @@ -5966,7 +6072,7 @@ endscript

Log files should be removed when the package is purged (but not when it is only removed), by checking the - argument to the postrm script (see the Debian + argument to the postrm script (see the Debian Packaging Manual for details).

@@ -6320,7 +6426,7 @@ http://localhost/doc/<package>/<filename>

/etc/aliases is the source file for the system mail aliases (e.g., postmaster, usenet, etc.), it is the one - which the sysadmin and postinst scripts may edit. + which the sysadmin and postinst scripts may edit. After /etc/aliases is edited the program or human editing it must call newaliases. All MTA packages must come with a newaliases program, @@ -6755,7 +6861,7 @@ name [`syshostname']: - Documentation + Documentation -- 2.39.5