Changes between Version 46 and Version 47 of RpmHowToPackagers

Timestamp:

Feb 3, 2017, 9:39:09 AM (7 years ago)

Author:

dmik

Comment:

Add Creating doc packages

RpmHowToPackagers

@@ -337 +337 @@
 Note that the lines you insert contain a `@todo` block which you should leave in. It is to remind to replace these lines with simpler constructs when #119 is fixed.
 
+== Creating doc packages ==
+
+A lot of software comes with various types of documentation. User-level documentation (such as manuals in MAN and INFO formats) is usually installed with the main package as it should be always available once the software is installed. However, many software packages also come with the development libraries (in a sub-package called `PACKAGE-devel`) accompanied by the documentation for developers. This documentation may occupy quite a lot of space on disk (several or even several dozen MB) when installed and unpacked. Given that it's usually more convenient to read it online, it makes little sense to have it installed each time when `PACKAGE-devel` is installed.
+
+Some packages already separate the developer's documentation from the development sub-package by putting it to a separate package `PACKAGE-devel-doc` but there is a plenty of them that still put everything in `PACKAGE-devel`. A .spec file for such a packages should be altered to separate the documentation from development libraries and tools. Here is a template for the respective part of the .spec file:
+
+{{{
+%package    devel-doc
+Summary:    Development Documentation files for MYSOFTWARE
+Group:      Documentation
+BuildArch:  noarch
+Requires:   %{name}-devel = %{version}-%{release}
+...
+%files devel-doc
+%doc docs/html/
+%doc examples/*.c
+}}}
+
+Please note that `PACKAGE-devel-doc` requires `PACKAGE-devel` but make sure that `PACKAGE-devel` does NOT require `PACKAGE-devel-doc` as otherwise this separation will be useless because the documentation sub-package will be implicitly installed each time the development sub-package is installed.
+
+Of course, if you create a new .spec file from scratch, you should separate `devel` and `devel-doc` right away.
+
+Note that in some rare cases user-level documentation may also be quite bulky (especially when it contains a lot of HTML files with pictures, big PDF files, etc). In such cases it may make sense to put it to a separate package, named `PACKAGE-doc` (`%package doc` in terms of the .spec file) similarly to the template shown above. A rule of thumb is that brief documentation (MAN, INFO) should be always installed with the main package and extended documentation, if it's several dozen MB or more, should go to a `doc` sub-package.
+
 == Generating debug packages ==