/usr/share/doc/debian-policy/policy.html/ch-docs.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">

<html>

<head>

<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">

<title>Debian Policy Manual - Documentation</title>

<link href="index.html" rel="start">
<link href="ch-customized-programs.html" rel="prev">
<link href="ap-pkg-scope.html" rel="next">
<link href="index.html#contents" rel="contents">
<link href="index.html#copyright" rel="copyright">
<link href="ch-scope.html" rel="chapter" title="1 About this manual">
<link href="ch-archive.html" rel="chapter" title="2 The Debian Archive">
<link href="ch-binary.html" rel="chapter" title="3 Binary packages">
<link href="ch-source.html" rel="chapter" title="4 Source packages">
<link href="ch-controlfields.html" rel="chapter" title="5 Control files and their fields">
<link href="ch-maintainerscripts.html" rel="chapter" title="6 Package maintainer scripts and installation procedure">
<link href="ch-relationships.html" rel="chapter" title="7 Declaring relationships between packages">
<link href="ch-sharedlibs.html" rel="chapter" title="8 Shared libraries">
<link href="ch-opersys.html" rel="chapter" title="9 The Operating System">
<link href="ch-files.html" rel="chapter" title="10 Files">
<link href="ch-customized-programs.html" rel="chapter" title="11 Customized programs">
<link href="ch-docs.html" rel="chapter" title="12 Documentation">
<link href="ap-pkg-scope.html" rel="appendix" title="A Introduction and scope of these appendices">
<link href="ap-pkg-binarypkg.html" rel="appendix" title="B Binary packages (from old Packaging Manual)">
<link href="ap-pkg-sourcepkg.html" rel="appendix" title="C Source packages (from old Packaging Manual)">
<link href="ap-pkg-controlfields.html" rel="appendix" title="D Control files and their fields (from old Packaging Manual)">
<link href="ap-pkg-conffiles.html" rel="appendix" title="E Configuration file handling (from old Packaging Manual)">
<link href="ap-pkg-alternatives.html" rel="appendix" title="F Alternative versions of an interface - update-alternatives (from old Packaging Manual)">
<link href="ap-pkg-diversions.html" rel="appendix" title="G Diversions - overriding a package's version of a file (from old Packaging Manual)">
<link href="ch-scope.html#s1.1" rel="section" title="1.1 Scope">
<link href="ch-scope.html#s1.2" rel="section" title="1.2 New versions of this document">
<link href="ch-scope.html#s-authors" rel="section" title="1.3 Authors and Maintainers">
<link href="ch-scope.html#s-related" rel="section" title="1.4 Related documents">
<link href="ch-scope.html#s-definitions" rel="section" title="1.5 Definitions">
<link href="ch-archive.html#s-dfsg" rel="section" title="2.1 The Debian Free Software Guidelines">
<link href="ch-archive.html#s-sections" rel="section" title="2.2 Archive areas">
<link href="ch-archive.html#s-pkgcopyright" rel="section" title="2.3 Copyright considerations">
<link href="ch-archive.html#s-subsections" rel="section" title="2.4 Sections">
<link href="ch-archive.html#s-priorities" rel="section" title="2.5 Priorities">
<link href="ch-binary.html#s3.1" rel="section" title="3.1 The package name">
<link href="ch-binary.html#s-versions" rel="section" title="3.2 The version of a package">
<link href="ch-binary.html#s-maintainer" rel="section" title="3.3 The maintainer of a package">
<link href="ch-binary.html#s-descriptions" rel="section" title="3.4 The description of a package">
<link href="ch-binary.html#s-dependencies" rel="section" title="3.5 Dependencies">
<link href="ch-binary.html#s-virtual_pkg" rel="section" title="3.6 Virtual packages">
<link href="ch-binary.html#s3.7" rel="section" title="3.7 Base system">
<link href="ch-binary.html#s3.8" rel="section" title="3.8 Essential packages">
<link href="ch-binary.html#s-maintscripts" rel="section" title="3.9 Maintainer Scripts">
<link href="ch-source.html#s-standardsversion" rel="section" title="4.1 Standards conformance">
<link href="ch-source.html#s-pkg-relations" rel="section" title="4.2 Package relationships">
<link href="ch-source.html#s4.3" rel="section" title="4.3 Changes to the upstream sources">
<link href="ch-source.html#s-dpkgchangelog" rel="section" title="4.4 Debian changelog: debian/changelog">
<link href="ch-source.html#s-dpkgcopyright" rel="section" title="4.5 Copyright: debian/copyright">
<link href="ch-source.html#s4.6" rel="section" title="4.6 Error trapping in makefiles">
<link href="ch-source.html#s-timestamps" rel="section" title="4.7 Time Stamps">
<link href="ch-source.html#s-restrictions" rel="section" title="4.8 Restrictions on objects in source packages">
<link href="ch-source.html#s-debianrules" rel="section" title="4.9 Main building script: debian/rules">
<link href="ch-source.html#s-substvars" rel="section" title="4.10 Variable substitutions: debian/substvars">
<link href="ch-source.html#s-debianwatch" rel="section" title="4.11 Optional upstream source location: debian/watch">
<link href="ch-source.html#s-debianfiles" rel="section" title="4.12 Generated files list: debian/files">
<link href="ch-source.html#s-embeddedfiles" rel="section" title="4.13 Convenience copies of code">
<link href="ch-source.html#s-readmesource" rel="section" title="4.14 Source package handling: debian/README.source">
<link href="ch-controlfields.html#s-controlsyntax" rel="section" title="5.1 Syntax of control files">
<link href="ch-controlfields.html#s-sourcecontrolfiles" rel="section" title="5.2 Source package control files -- debian/control">
<link href="ch-controlfields.html#s-binarycontrolfiles" rel="section" title="5.3 Binary package control files -- DEBIAN/control">
<link href="ch-controlfields.html#s-debiansourcecontrolfiles" rel="section" title="5.4 Debian source control files -- .dsc">
<link href="ch-controlfields.html#s-debianchangesfiles" rel="section" title="5.5 Debian changes files -- .changes">
<link href="ch-controlfields.html#s-controlfieldslist" rel="section" title="5.6 List of fields">
<link href="ch-controlfields.html#s5.7" rel="section" title="5.7 User-defined fields">
<link href="ch-maintainerscripts.html#s6.1" rel="section" title="6.1 Introduction to package maintainer scripts">
<link href="ch-maintainerscripts.html#s-idempotency" rel="section" title="6.2 Maintainer scripts idempotency">
<link href="ch-maintainerscripts.html#s-controllingterminal" rel="section" title="6.3 Controlling terminal for maintainer scripts">
<link href="ch-maintainerscripts.html#s-exitstatus" rel="section" title="6.4 Exit status">
<link href="ch-maintainerscripts.html#s-mscriptsinstact" rel="section" title="6.5 Summary of ways maintainer scripts are called">
<link href="ch-maintainerscripts.html#s-unpackphase" rel="section" title="6.6 Details of unpack phase of installation or upgrade">
<link href="ch-maintainerscripts.html#s-configdetails" rel="section" title="6.7 Details of configuration">
<link href="ch-maintainerscripts.html#s-removedetails" rel="section" title="6.8 Details of removal and/or configuration purging">
<link href="ch-relationships.html#s-depsyntax" rel="section" title="7.1 Syntax of relationship fields">
<link href="ch-relationships.html#s-binarydeps" rel="section" title="7.2 Binary Dependencies - Depends, Recommends, Suggests, Enhances, Pre-Depends">
<link href="ch-relationships.html#s-breaks" rel="section" title="7.3 Packages which break other packages - Breaks">
<link href="ch-relationships.html#s-conflicts" rel="section" title="7.4 Conflicting binary packages - Conflicts">
<link href="ch-relationships.html#s-virtual" rel="section" title="7.5 Virtual packages - Provides">
<link href="ch-relationships.html#s-replaces" rel="section" title="7.6 Overwriting files and replacing packages - Replaces">
<link href="ch-relationships.html#s-sourcebinarydeps" rel="section" title="7.7 Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep">
<link href="ch-sharedlibs.html#s-sharedlibs-runtime" rel="section" title="8.1 Run-time shared libraries">
<link href="ch-sharedlibs.html#s-sharedlibs-support-files" rel="section" title="8.2 Shared library support files">
<link href="ch-sharedlibs.html#s-sharedlibs-static" rel="section" title="8.3 Static libraries">
<link href="ch-sharedlibs.html#s-sharedlibs-dev" rel="section" title="8.4 Development files">
<link href="ch-sharedlibs.html#s-sharedlibs-intradeps" rel="section" title="8.5 Dependencies between the packages of the same library">
<link href="ch-sharedlibs.html#s-sharedlibs-shlibdeps" rel="section" title="8.6 Dependencies between the library and other packages - the shlibs system">
<link href="ch-opersys.html#s9.1" rel="section" title="9.1 File system hierarchy">
<link href="ch-opersys.html#s9.2" rel="section" title="9.2 Users and groups">
<link href="ch-opersys.html#s-sysvinit" rel="section" title="9.3 System run levels and init.d scripts">
<link href="ch-opersys.html#s9.4" rel="section" title="9.4 Console messages from init.d scripts">
<link href="ch-opersys.html#s-cron-jobs" rel="section" title="9.5 Cron jobs">
<link href="ch-opersys.html#s-menus" rel="section" title="9.6 Menus">
<link href="ch-opersys.html#s-mime" rel="section" title="9.7 Multimedia handlers">
<link href="ch-opersys.html#s9.8" rel="section" title="9.8 Keyboard configuration">
<link href="ch-opersys.html#s9.9" rel="section" title="9.9 Environment variables">
<link href="ch-opersys.html#s-doc-base" rel="section" title="9.10 Registering Documents using doc-base">
<link href="ch-files.html#s-binaries" rel="section" title="10.1 Binaries">
<link href="ch-files.html#s-libraries" rel="section" title="10.2 Libraries">
<link href="ch-files.html#s10.3" rel="section" title="10.3 Shared libraries">
<link href="ch-files.html#s-scripts" rel="section" title="10.4 Scripts">
<link href="ch-files.html#s10.5" rel="section" title="10.5 Symbolic links">
<link href="ch-files.html#s10.6" rel="section" title="10.6 Device files">
<link href="ch-files.html#s-config-files" rel="section" title="10.7 Configuration files">
<link href="ch-files.html#s10.8" rel="section" title="10.8 Log files">
<link href="ch-files.html#s-permissions-owners" rel="section" title="10.9 Permissions and owners">
<link href="ch-customized-programs.html#s-arch-spec" rel="section" title="11.1 Architecture specification strings">
<link href="ch-customized-programs.html#s11.2" rel="section" title="11.2 Daemons">
<link href="ch-customized-programs.html#s11.3" rel="section" title="11.3 Using pseudo-ttys and modifying wtmp, utmp and lastlog">
<link href="ch-customized-programs.html#s11.4" rel="section" title="11.4 Editors and pagers">
<link href="ch-customized-programs.html#s-web-appl" rel="section" title="11.5 Web servers and applications">
<link href="ch-customized-programs.html#s-mail-transport-agents" rel="section" title="11.6 Mail transport, delivery and user agents">
<link href="ch-customized-programs.html#s11.7" rel="section" title="11.7 News system configuration">
<link href="ch-customized-programs.html#s11.8" rel="section" title="11.8 Programs for the X Window System">
<link href="ch-customized-programs.html#s-perl" rel="section" title="11.9 Perl programs and modules">
<link href="ch-customized-programs.html#s-emacs" rel="section" title="11.10 Emacs lisp programs">
<link href="ch-customized-programs.html#s11.11" rel="section" title="11.11 Games">
<link href="ch-docs.html#s12.1" rel="section" title="12.1 Manual pages">
<link href="ch-docs.html#s12.2" rel="section" title="12.2 Info documents">
<link href="ch-docs.html#s12.3" rel="section" title="12.3 Additional documentation">
<link href="ch-docs.html#s12.4" rel="section" title="12.4 Preferred documentation formats">
<link href="ch-docs.html#s-copyrightfile" rel="section" title="12.5 Copyright information">
<link href="ch-docs.html#s12.6" rel="section" title="12.6 Examples">
<link href="ch-docs.html#s-changelogs" rel="section" title="12.7 Changelog files">
<link href="ap-pkg-binarypkg.html#s-pkg-bincreating" rel="section" title="B.1 Creating package files - dpkg-deb">
<link href="ap-pkg-binarypkg.html#s-pkg-controlarea" rel="section" title="B.2 Package control information files">
<link href="ap-pkg-binarypkg.html#s-pkg-controlfile" rel="section" title="B.3 The main control information file: control">
<link href="ap-pkg-binarypkg.html#sB.4" rel="section" title="B.4 Time Stamps">
<link href="ap-pkg-sourcepkg.html#s-pkg-sourcetools" rel="section" title="C.1 Tools for processing source packages">
<link href="ap-pkg-sourcepkg.html#s-pkg-sourcetree" rel="section" title="C.2 The Debian package source tree">
<link href="ap-pkg-sourcepkg.html#s-pkg-sourcearchives" rel="section" title="C.3 Source packages as archives">
<link href="ap-pkg-sourcepkg.html#sC.4" rel="section" title="C.4 Unpacking a Debian source package without dpkg-source">
<link href="ap-pkg-controlfields.html#sD.1" rel="section" title="D.1 Syntax of control files">
<link href="ap-pkg-controlfields.html#sD.2" rel="section" title="D.2 List of fields">
<link href="ap-pkg-conffiles.html#sE.1" rel="section" title="E.1 Automatic handling of configuration files by dpkg">
<link href="ap-pkg-conffiles.html#sE.2" rel="section" title="E.2 Fully-featured maintainer script configuration handling">
<link href="ch-archive.html#s-main" rel="subsection" title="2.2.1 The main archive area">
<link href="ch-archive.html#s-contrib" rel="subsection" title="2.2.2 The contrib archive area">
<link href="ch-archive.html#s-non-free" rel="subsection" title="2.2.3 The non-free archive area">
<link href="ch-binary.html#s3.2.1" rel="subsection" title="3.2.1 Version numbers based on dates">
<link href="ch-binary.html#s-synopsis" rel="subsection" title="3.4.1 The single line synopsis">
<link href="ch-binary.html#s-extendeddesc" rel="subsection" title="3.4.2 The extended description">
<link href="ch-binary.html#s-maintscriptprompt" rel="subsection" title="3.9.1 Prompting in maintainer scripts">
<link href="ch-source.html#s-debianrules-options" rel="subsection" title="4.9.1 debian/rules and DEB_BUILD_OPTIONS">
<link href="ch-controlfields.html#s-f-Source" rel="subsection" title="5.6.1 Source">
<link href="ch-controlfields.html#s-f-Maintainer" rel="subsection" title="5.6.2 Maintainer">
<link href="ch-controlfields.html#s-f-Uploaders" rel="subsection" title="5.6.3 Uploaders">
<link href="ch-controlfields.html#s-f-Changed-By" rel="subsection" title="5.6.4 Changed-By">
<link href="ch-controlfields.html#s-f-Section" rel="subsection" title="5.6.5 Section">
<link href="ch-controlfields.html#s-f-Priority" rel="subsection" title="5.6.6 Priority">
<link href="ch-controlfields.html#s-f-Package" rel="subsection" title="5.6.7 Package">
<link href="ch-controlfields.html#s-f-Architecture" rel="subsection" title="5.6.8 Architecture">
<link href="ch-controlfields.html#s-f-Essential" rel="subsection" title="5.6.9 Essential">
<link href="ch-controlfields.html#s5.6.10" rel="subsection" title="5.6.10 Package interrelationship fields: Depends, Pre-Depends, Recommends, Suggests, Breaks, Conflicts, Provides, Replaces, Enhances">
<link href="ch-controlfields.html#s-f-Standards-Version" rel="subsection" title="5.6.11 Standards-Version">
<link href="ch-controlfields.html#s-f-Version" rel="subsection" title="5.6.12 Version">
<link href="ch-controlfields.html#s-f-Description" rel="subsection" title="5.6.13 Description">
<link href="ch-controlfields.html#s-f-Distribution" rel="subsection" title="5.6.14 Distribution">
<link href="ch-controlfields.html#s-f-Date" rel="subsection" title="5.6.15 Date">
<link href="ch-controlfields.html#s-f-Format" rel="subsection" title="5.6.16 Format">
<link href="ch-controlfields.html#s-f-Urgency" rel="subsection" title="5.6.17 Urgency">
<link href="ch-controlfields.html#s-f-Changes" rel="subsection" title="5.6.18 Changes">
<link href="ch-controlfields.html#s-f-Binary" rel="subsection" title="5.6.19 Binary">
<link href="ch-controlfields.html#s-f-Installed-Size" rel="subsection" title="5.6.20 Installed-Size">
<link href="ch-controlfields.html#s-f-Files" rel="subsection" title="5.6.21 Files">
<link href="ch-controlfields.html#s-f-Closes" rel="subsection" title="5.6.22 Closes">
<link href="ch-controlfields.html#s-f-Homepage" rel="subsection" title="5.6.23 Homepage">
<link href="ch-controlfields.html#s-f-Checksums" rel="subsection" title="5.6.24 Checksums-Sha1 and Checksums-Sha256">
<link href="ch-controlfields.html#s-f-DM-Upload-Allowed" rel="subsection" title="5.6.25 DM-Upload-Allowed">
<link href="ch-relationships.html#s7.6.1" rel="subsection" title="7.6.1 Overwriting files in other packages">
<link href="ch-relationships.html#s7.6.2" rel="subsection" title="7.6.2 Replacing whole packages, forcing their removal">
<link href="ch-sharedlibs.html#s-ldconfig" rel="subsection" title="8.1.1 ldconfig">
<link href="ch-sharedlibs.html#s8.6.1" rel="subsection" title="8.6.1 The shlibs files present on the system">
<link href="ch-sharedlibs.html#s8.6.2" rel="subsection" title="8.6.2 How to use dpkg-shlibdeps and the shlibs files">
<link href="ch-sharedlibs.html#s-shlibs" rel="subsection" title="8.6.3 The shlibs File Format">
<link href="ch-sharedlibs.html#s8.6.4" rel="subsection" title="8.6.4 Providing a shlibs file">
<link href="ch-opersys.html#s-fhs" rel="subsection" title="9.1.1 File System Structure">
<link href="ch-opersys.html#s9.1.2" rel="subsection" title="9.1.2 Site-specific programs">
<link href="ch-opersys.html#s9.1.3" rel="subsection" title="9.1.3 The system-wide mail directory">
<link href="ch-opersys.html#s-fhs-run" rel="subsection" title="9.1.4 /run and /run/lock">
<link href="ch-opersys.html#s9.2.1" rel="subsection" title="9.2.1 Introduction">
<link href="ch-opersys.html#s9.2.2" rel="subsection" title="9.2.2 UID and GID classes">
<link href="ch-opersys.html#s-/etc/init.d" rel="subsection" title="9.3.1 Introduction">
<link href="ch-opersys.html#s-writing-init" rel="subsection" title="9.3.2 Writing the scripts">
<link href="ch-opersys.html#s9.3.3" rel="subsection" title="9.3.3 Interfacing with the initscript system">
<link href="ch-opersys.html#s9.3.3.1" rel="subsection" title="9.3.3.1 Managing the links">
<link href="ch-opersys.html#s9.3.3.2" rel="subsection" title="9.3.3.2 Running initscripts">
<link href="ch-opersys.html#s9.3.4" rel="subsection" title="9.3.4 Boot-time initialization">
<link href="ch-opersys.html#s9.3.5" rel="subsection" title="9.3.5 Example">
<link href="ch-opersys.html#s-cron-files" rel="subsection" title="9.5.1 Cron job file names">
<link href="ch-files.html#s10.7.1" rel="subsection" title="10.7.1 Definitions">
<link href="ch-files.html#s10.7.2" rel="subsection" title="10.7.2 Location">
<link href="ch-files.html#s10.7.3" rel="subsection" title="10.7.3 Behavior">
<link href="ch-files.html#s10.7.4" rel="subsection" title="10.7.4 Sharing configuration files">
<link href="ch-files.html#s10.7.5" rel="subsection" title="10.7.5 User configuration files (&quot;dotfiles&quot;)">
<link href="ch-files.html#s10.9.1" rel="subsection" title="10.9.1 The use of dpkg-statoverride">
<link href="ch-customized-programs.html#s-arch-wildcard-spec" rel="subsection" title="11.1.1 Architecture wildcards">
<link href="ch-customized-programs.html#s11.8.1" rel="subsection" title="11.8.1 Providing X support and package priorities">
<link href="ch-customized-programs.html#s11.8.2" rel="subsection" title="11.8.2 Packages providing an X server">
<link href="ch-customized-programs.html#s11.8.3" rel="subsection" title="11.8.3 Packages providing a terminal emulator">
<link href="ch-customized-programs.html#s11.8.4" rel="subsection" title="11.8.4 Packages providing a window manager">
<link href="ch-customized-programs.html#s11.8.5" rel="subsection" title="11.8.5 Packages providing fonts">
<link href="ch-customized-programs.html#s-appdefaults" rel="subsection" title="11.8.6 Application defaults files">
<link href="ch-customized-programs.html#s11.8.7" rel="subsection" title="11.8.7 Installation directory issues">
<link href="ch-docs.html#s-copyrightformat" rel="subsection" title="12.5.1 Machine-readable copyright information">
<link href="ap-pkg-sourcepkg.html#s-pkg-dpkg-source" rel="subsection" title="C.1.1 dpkg-source - packs and unpacks Debian source packages">
<link href="ap-pkg-sourcepkg.html#s-pkg-dpkg-buildpackage" rel="subsection" title="C.1.2 dpkg-buildpackage - overall package-building control script">
<link href="ap-pkg-sourcepkg.html#s-pkg-dpkg-gencontrol" rel="subsection" title="C.1.3 dpkg-gencontrol - generates binary package control files">
<link href="ap-pkg-sourcepkg.html#s-pkg-dpkg-shlibdeps" rel="subsection" title="C.1.4 dpkg-shlibdeps - calculates shared library dependencies">
<link href="ap-pkg-sourcepkg.html#s-pkg-dpkg-distaddfile" rel="subsection" title="C.1.5 dpkg-distaddfile - adds a file to debian/files">
<link href="ap-pkg-sourcepkg.html#s-pkg-dpkg-genchanges" rel="subsection" title="C.1.6 dpkg-genchanges - generates a .changes upload control file">
<link href="ap-pkg-sourcepkg.html#s-pkg-dpkg-parsechangelog" rel="subsection" title="C.1.7 dpkg-parsechangelog - produces parsed representation of a changelog">
<link href="ap-pkg-sourcepkg.html#s-pkg-dpkg-architecture" rel="subsection" title="C.1.8 dpkg-architecture - information about the build and host system">
<link href="ap-pkg-sourcepkg.html#s-pkg-debianrules" rel="subsection" title="C.2.1 debian/rules - the main building script">
<link href="ap-pkg-sourcepkg.html#s-pkg-srcsubstvars" rel="subsection" title="C.2.2 debian/substvars and variable substitutions">
<link href="ap-pkg-sourcepkg.html#sC.2.3" rel="subsection" title="C.2.3 debian/files">
<link href="ap-pkg-sourcepkg.html#sC.2.4" rel="subsection" title="C.2.4 debian/tmp">
<link href="ap-pkg-sourcepkg.html#sC.4.1" rel="subsection" title="C.4.1 Restrictions on objects in source packages">
<link href="ap-pkg-controlfields.html#s-pkg-f-Filename" rel="subsection" title="D.2.1 Filename and MSDOS-Filename">
<link href="ap-pkg-controlfields.html#s-pkg-f-Size" rel="subsection" title="D.2.2 Size and MD5sum">
<link href="ap-pkg-controlfields.html#s-pkg-f-Status" rel="subsection" title="D.2.3 Status">
<link href="ap-pkg-controlfields.html#s-pkg-f-Config-Version" rel="subsection" title="D.2.4 Config-Version">
<link href="ap-pkg-controlfields.html#s-pkg-f-Conffiles" rel="subsection" title="D.2.5 Conffiles">
<link href="ap-pkg-controlfields.html#sD.2.6" rel="subsection" title="D.2.6 Obsolete fields">

</head>

<body>

<p><a name="ch-docs"></a></p>
<hr>

<p>
[ <a href="ch-customized-programs.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch-scope.html">1</a> ]
[ <a href="ch-archive.html">2</a> ]
[ <a href="ch-binary.html">3</a> ]
[ <a href="ch-source.html">4</a> ]
[ <a href="ch-controlfields.html">5</a> ]
[ <a href="ch-maintainerscripts.html">6</a> ]
[ <a href="ch-relationships.html">7</a> ]
[ <a href="ch-sharedlibs.html">8</a> ]
[ <a href="ch-opersys.html">9</a> ]
[ <a href="ch-files.html">10</a> ]
[ <a href="ch-customized-programs.html">11</a> ]
[ 12 ]
[ <a href="ap-pkg-scope.html">A</a> ]
[ <a href="ap-pkg-binarypkg.html">B</a> ]
[ <a href="ap-pkg-sourcepkg.html">C</a> ]
[ <a href="ap-pkg-controlfields.html">D</a> ]
[ <a href="ap-pkg-conffiles.html">E</a> ]
[ <a href="ap-pkg-alternatives.html">F</a> ]
[ <a href="ap-pkg-diversions.html">G</a> ]
[ <a href="ap-pkg-scope.html">next</a> ]
</p>

<hr>

<h1>
Debian Policy Manual
<br>Chapter 12 - Documentation
</h1>

<hr>

<h2><a name="s12.1"></a>12.1 Manual pages</h2>

<p>
You should install manual pages in <code>nroff</code> source form, in
appropriate places under <code>/usr/share/man</code>.  You should only use
sections 1 to 9 (see the FHS for more details).  You must not install a
pre-formatted &quot;cat page&quot;.
</p>

<p>
Each program, utility, and function should have an associated manual page
included in the same package.  It is suggested that all configuration files
also have a manual page included as well.  Manual pages for protocols and other
auxiliary things are optional.
</p>

<p>
If no manual page is available, this is considered as a bug and should be
reported to the Debian Bug Tracking System (the maintainer of the package is
allowed to write this bug report themselves, if they so desire).  Do not close
the bug report until a proper man page is available.[<a
href="footnotes.html#f98" name="fr98">98</a>]
</p>

<p>
You may forward a complaint about a missing man page to the upstream authors,
and mark the bug as forwarded in the Debian bug tracking system.  Even though
the GNU Project do not in general consider the lack of a man page to be a bug,
we do; if they tell you that they don't consider it a bug you should leave the
bug in our bug tracking system open anyway.
</p>

<p>
Manual pages should be installed compressed using <samp>gzip -9</samp>.
</p>

<p>
If one man page needs to be accessible via several names it is better to use a
symbolic link than the <code>.so</code> feature, but there is no need to fiddle
with the relevant parts of the upstream source to change from <code>.so</code>
to symlinks: don't do it unless it's easy.  You should not create hard links in
the manual page directories, nor put absolute filenames in <code>.so</code>
directives.  The filename in a <code>.so</code> in a man page should be
relative to the base of the man page tree (usually
<code>/usr/share/man</code>).  If you do not create any links (whether
symlinks, hard links, or <samp>.so</samp> directives) in the file system to the
alternate names of the man page, then you should not rely on <code>man</code>
finding your man page under those names based solely on the information in the
man page's header.[<a href="footnotes.html#f99" name="fr99">99</a>]
</p>

<p>
Manual pages in locale-specific subdirectories of <code>/usr/share/man</code>
should use either UTF-8 or the usual legacy encoding for that language
(normally the one corresponding to the shortest relevant locale name in
<code>/usr/share/i18n/SUPPORTED</code>).  For example, pages under
<code>/usr/share/man/fr</code> should use either UTF-8 or ISO-8859-1.[<a
href="footnotes.html#f100" name="fr100">100</a>]
</p>

<p>
A country name (the <samp>DE</samp> in <samp>de_DE</samp>) should not be
included in the subdirectory name unless it indicates a significant difference
in the language, as this excludes speakers of the language in other
countries.[<a href="footnotes.html#f101" name="fr101">101</a>]
</p>

<p>
If a localized version of a manual page is provided, it should either be
up-to-date or it should be obvious to the reader that it is outdated and the
original manual page should be used instead.  This can be done either by a note
at the beginning of the manual page or by showing the missing or changed
portions in the original language instead of the target language.
</p>

<hr>

<h2><a name="s12.2"></a>12.2 Info documents</h2>

<p>
Info documents should be installed in <code>/usr/share/info</code>.  They
should be compressed with <samp>gzip -9</samp>.
</p>

<p>
The <code>install-info</code> program maintains a directory of installed info
documents in <code>/usr/share/info/dir</code> for the use of info readers.[<a
href="footnotes.html#f102" name="fr102">102</a>] This file must not be included
in packages.  Packages containing info documents should depend on <samp>dpkg
(&gt;= 1.15.4) | install-info</samp> to ensure that the directory file is
properly rebuilt during partial upgrades from Debian 5.0 (lenny) and earlier.
</p>

<p>
Info documents should contain section and directory entry information in the
document for the use of <code>install-info</code>.  The section should be
specified via a line starting with <samp>INFO-DIR-SECTION</samp> followed by a
space and the section of this info page.  The directory entry or entries should
be included between a <samp>START-INFO-DIR-ENTRY</samp> line and an
<samp>END-INFO-DIR-ENTRY</samp> line.  For example:
</p>

<pre>
     INFO-DIR-SECTION Individual utilities
     START-INFO-DIR-ENTRY
     * example: (example).               An example info directory entry.
     END-INFO-DIR-ENTRY
</pre>

<p>
To determine which section to use, you should look at
<code>/usr/share/info/dir</code> on your system and choose the most relevant
(or create a new section if none of the current sections are relevant).[<a
href="footnotes.html#f103" name="fr103">103</a>]
</p>

<hr>

<h2><a name="s12.3"></a>12.3 Additional documentation</h2>

<p>
Any additional documentation that comes with the package may be installed at
the discretion of the package maintainer.  Plain text documentation should be
installed in the directory <code>/usr/share/doc/<var>package</var></code>,
where <var>package</var> is the name of the package, and compressed with
<samp>gzip -9</samp> unless it is small.
</p>

<p>
If a package comes with large amounts of documentation which many users of the
package will not require you should create a separate binary package to contain
it, so that it does not take up disk space on the machines of users who do not
need or want it installed.
</p>

<p>
It is often a good idea to put text information files (<code>README</code>s,
changelogs, and so forth) that come with the source package in
<code>/usr/share/doc/<var>package</var></code> in the binary package.  However,
you don't need to install the instructions for building and installing the
package, of course!
</p>

<p>
Packages must not require the existence of any files in
<code>/usr/share/doc/</code> in order to function [<a
href="footnotes.html#f104" name="fr104">104</a>].  Any files that are
referenced by programs but are also useful as stand alone documentation should
be installed under <code>/usr/share/<var>package</var>/</code> with symbolic
links from <code>/usr/share/doc/<var>package</var></code>.
</p>

<p>
<code>/usr/share/doc/<var>package</var></code> may be a symbolic link to
another directory in <code>/usr/share/doc</code> only if the two packages both
come from the same source and the first package Depends on the second.[<a
href="footnotes.html#f105" name="fr105">105</a>]
</p>

<p>
Former Debian releases placed all additional documentation in
<code>/usr/doc/<var>package</var></code>.  This has been changed to
<code>/usr/share/doc/<var>package</var></code>, and packages must not put
documentation in the directory <code>/usr/doc/<var>package</var></code>.  [<a
href="footnotes.html#f106" name="fr106">106</a>]
</p>

<hr>

<h2><a name="s12.4"></a>12.4 Preferred documentation formats</h2>

<p>
The unification of Debian documentation is being carried out via HTML.
</p>

<p>
If your package comes with extensive documentation in a markup format that can
be converted to various other formats you should if possible ship HTML versions
in a binary package, in the directory
<code>/usr/share/doc/<var>appropriate-package</var></code> or its
subdirectories.[<a href="footnotes.html#f107" name="fr107">107</a>]
</p>

<p>
Other formats such as PostScript may be provided at the package maintainer's
discretion.
</p>

<hr>

<h2><a name="s-copyrightfile"></a>12.5 Copyright information</h2>

<p>
Every package must be accompanied by a verbatim copy of its copyright
information and distribution license in the file
<code>/usr/share/doc/<var>package</var>/copyright</code>.  This file must
neither be compressed nor be a symbolic link.
</p>

<p>
In addition, the copyright file must say where the upstream sources (if any)
were obtained, and should name the original authors.
</p>

<p>
Packages in the <em>contrib</em> or <em>non-free</em> archive areas should
state in the copyright file that the package is not part of the Debian
distribution and briefly explain why.
</p>

<p>
A copy of the file which will be installed in
<code>/usr/share/doc/<var>package</var>/copyright</code> should be in
<code>debian/copyright</code> in the source package.
</p>

<p>
<code>/usr/share/doc/<var>package</var></code> may be a symbolic link to
another directory in <code>/usr/share/doc</code> only if the two packages both
come from the same source and the first package Depends on the second.  These
rules are important because <code>copyright</code> files must be extractable by
mechanical means.
</p>

<p>
Packages distributed under the Apache license (version 2.0), the Artistic
license, the GNU GPL (versions 1, 2, or 3), the GNU LGPL (versions 2, 2.1, or
3), and the GNU FDL (versions 1.2 or 1.3) should refer to the corresponding
files under <code>/usr/share/common-licenses</code>,[<a
href="footnotes.html#f108" name="fr108">108</a>] rather than quoting them in
the copyright file.
</p>

<p>
You should not use the copyright file as a general <code>README</code> file.
If your package has such a file it should be installed in
<code>/usr/share/doc/<var>package</var>/README</code> or
<code>README.Debian</code> or some other appropriate place.
</p>

<hr>

<h3><a name="s-copyrightformat"></a>12.5.1 Machine-readable copyright information</h3>

<p>
A specification for a standard, machine-readable format for
<code>debian/copyright</code> files is maintained as part of the
<code>debian-policy</code> package.  This document may be found in the
<code>copyright-format</code> files in the <code>debian-policy</code> package.
It is also available from the Debian web mirrors at <samp><code><a
href="http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/">/doc/packaging-manuals/copyright-format/1.0/</a></code></samp>.
</p>

<p>
Use of this format is optional.
</p>

<hr>

<h2><a name="s12.6"></a>12.6 Examples</h2>

<p>
Any examples (configurations, source files, whatever), should be installed in a
directory <code>/usr/share/doc/<var>package</var>/examples</code>.  These files
should not be referenced by any program: they're there for the benefit of the
system administrator and users as documentation only.  Architecture-specific
example files should be installed in a directory
<code>/usr/lib/<var>package</var>/examples</code> with symbolic links to them
from <code>/usr/share/doc/<var>package</var>/examples</code>, or the latter
directory itself may be a symbolic link to the former.
</p>

<p>
If the purpose of a package is to provide examples, then the example files may
be installed into <code>/usr/share/doc/<var>package</var></code>.
</p>

<hr>

<h2><a name="s-changelogs"></a>12.7 Changelog files</h2>

<p>
Packages that are not Debian-native must contain a compressed copy of the
<code>debian/changelog</code> file from the Debian source tree in
<code>/usr/share/doc/<var>package</var></code> with the name
<code>changelog.Debian.gz</code>.
</p>

<p>
If an upstream changelog is available, it should be accessible as
<code>/usr/share/doc/<var>package</var>/changelog.gz</code> in plain text.  If
the upstream changelog is distributed in HTML, it should be made available in
that form as <code>/usr/share/doc/<var>package</var>/changelog.html.gz</code>
and a plain text <code>changelog.gz</code> should be generated from it using,
for example, <samp>lynx -dump -nolist</samp>.  If the upstream changelog files
do not already conform to this naming convention, then this may be achieved
either by renaming the files, or by adding a symbolic link, at the maintainer's
discretion.[<a href="footnotes.html#f109" name="fr109">109</a>]
</p>

<p>
All of these files should be installed compressed using <samp>gzip -9</samp>,
as they will become large with time even if they start out small.
</p>

<p>
If the package has only one changelog which is used both as the Debian
changelog and the upstream one because there is no separate upstream maintainer
then that changelog should usually be installed as
<code>/usr/share/doc/<var>package</var>/changelog.gz</code>; if there is a
separate upstream maintainer, but no upstream changelog, then the Debian
changelog should still be called <code>changelog.Debian.gz</code>.
</p>

<p>
For details about the format and contents of the Debian changelog file, please
see <a href="ch-source.html#s-dpkgchangelog">Debian changelog:
<code>debian/changelog</code>, Section 4.4</a>.
</p>

<hr>

<p>
[ <a href="ch-customized-programs.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch-scope.html">1</a> ]
[ <a href="ch-archive.html">2</a> ]
[ <a href="ch-binary.html">3</a> ]
[ <a href="ch-source.html">4</a> ]
[ <a href="ch-controlfields.html">5</a> ]
[ <a href="ch-maintainerscripts.html">6</a> ]
[ <a href="ch-relationships.html">7</a> ]
[ <a href="ch-sharedlibs.html">8</a> ]
[ <a href="ch-opersys.html">9</a> ]
[ <a href="ch-files.html">10</a> ]
[ <a href="ch-customized-programs.html">11</a> ]
[ 12 ]
[ <a href="ap-pkg-scope.html">A</a> ]
[ <a href="ap-pkg-binarypkg.html">B</a> ]
[ <a href="ap-pkg-sourcepkg.html">C</a> ]
[ <a href="ap-pkg-controlfields.html">D</a> ]
[ <a href="ap-pkg-conffiles.html">E</a> ]
[ <a href="ap-pkg-alternatives.html">F</a> ]
[ <a href="ap-pkg-diversions.html">G</a> ]
[ <a href="ap-pkg-scope.html">next</a> ]
</p>

<hr>

<p>
Debian Policy Manual
</p>

<address>
version 3.9.3.1, 2012-03-13<br>
<br>
<a href="ch-scope.html#s-authors">The Debian Policy Mailing List</a><br>
<br>
</address>
<hr>

</body>

</html>
debian-policy 3.9.3.1 / usr / share / doc / debian-policy / policy.html / ch-docs.html
