Bug#907970: Please stop using debiandoc-sgml (deprecated)
Package: debian-installer
Version: 20180610
Severity: normal
Tags: patch
I am in process of dropping debiandoc-sgml. So please convert
partman-doc to DocBook XML with attached patch.
-- System Information:
Debian Release: buster/sid
APT prefers testing
APT policy: (500, 'testing'), (10, 'unstable')
Architecture: amd64 (x86_64)
Kernel: Linux 4.17.0-3-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US:en (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
From 9e165a7690557672fcba4278894858b0badc789f Mon Sep 17 00:00:00 2001
From: Osamu Aoki <osamu@debian.org>
Date: Fri, 31 Aug 2018 10:54:10 +0000
Subject: [PATCH] partman-doc: Convert to DocBook XML 4.5
Convert with:
$ debiandoc2dbk -1 partman-doc.sgml
Build script are from internals (some symlink)
Also update .gitignore to match all *.html
Signed-off-by: Osamu Aoki <osamu@debian.org>
---
debian/control | 4 +-
debian/rules | 2 +-
doc/devel/internals/.gitignore | 2 +-
doc/devel/partman/.gitignore | 2 +-
doc/devel/partman/Makefile | 27 +-
doc/devel/partman/build.sh | 16 +
doc/devel/partman/internals.css | 1 +
doc/devel/partman/partman-doc.dbk | 1751 ++++++++++++++++++++++++++++
doc/devel/partman/partman-doc.sgml | 1507 ------------------------
doc/devel/partman/style-common.xsl | 1 +
doc/devel/partman/style-html.xsl | 1 +
11 files changed, 1777 insertions(+), 1537 deletions(-)
create mode 100755 doc/devel/partman/build.sh
create mode 120000 doc/devel/partman/internals.css
create mode 100644 doc/devel/partman/partman-doc.dbk
delete mode 100644 doc/devel/partman/partman-doc.sgml
create mode 120000 doc/devel/partman/style-common.xsl
create mode 120000 doc/devel/partman/style-html.xsl
diff --git a/debian/control b/debian/control
index f903622e2..686a5ef6d 100644
--- a/debian/control
+++ b/debian/control
@@ -24,12 +24,10 @@ Build-Depends:
# Used to test validity of mirrors.
bc,
# Used for some image size calculations.
- debiandoc-sgml,
-# partman's manual is in debiandoc.
xsltproc,
docbook-xml,
docbook-xsl,
-# The d-i internals manual is in DocBook XML.
+# The d-i partman-doc and internals manual is in DocBook XML 4.x.
libbogl-dev,
# For bdftobogl used in font reduction.
#
diff --git a/debian/rules b/debian/rules
index e4f417dfd..63ae420d5 100755
--- a/debian/rules
+++ b/debian/rules
@@ -75,7 +75,7 @@ binary-arch: install
dh_testroot
dh_installchangelogs
dh_installdocs doc/* -X Makefile -X build.sh -X .xsl \
- -X internals.xml -X partman-doc.sgml -X .gitignore
+ -X internals.xml -X partman-doc.dbk -X .gitignore
dh_compress
dh_fixperms
diff --git a/doc/devel/internals/.gitignore b/doc/devel/internals/.gitignore
index eb6fe0602..3432c3fd8 100644
--- a/doc/devel/internals/.gitignore
+++ b/doc/devel/internals/.gitignore
@@ -1,2 +1,2 @@
-index.html
+*.html
diff --git a/doc/devel/partman/.gitignore b/doc/devel/partman/.gitignore
index ca2b6c7a2..3432c3fd8 100644
--- a/doc/devel/partman/.gitignore
+++ b/doc/devel/partman/.gitignore
@@ -1,2 +1,2 @@
-partman-doc.html
+*.html
diff --git a/doc/devel/partman/Makefile b/doc/devel/partman/Makefile
index b9cbcc66c..2e36b62b3 100644
--- a/doc/devel/partman/Makefile
+++ b/doc/devel/partman/Makefile
@@ -1,26 +1,5 @@
-SHELL=bash
-name=partman-doc
-
-$(name).html/: $(name).sgml
- debiandoc2html $(name).sgml
-
-%.txt: %.sgml
- debiandoc2text $<
-
-%.pdf: %.sgml
- debiandoc2pdf $<
-
-%.dvi: %.sgml
- debiandoc2dvi $<
-
-%.info: %.sgml
- debiandoc2info $<
-
-%.ps: %.sgml
- debiandoc2ps $<
-
-%.tov: %.sgml
- debiandoc2textov $<
+all: *.xsl *.dbk
+ @./build.sh
clean:
- rm -rf $(name).html
+ @rm -f *.html
diff --git a/doc/devel/partman/build.sh b/doc/devel/partman/build.sh
new file mode 100755
index 000000000..a5e8e7816
--- /dev/null
+++ b/doc/devel/partman/build.sh
@@ -0,0 +1,16 @@
+#!/bin/sh
+
+xsltproc=`which xsltproc`
+stylesheet=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl
+
+if [ -n "$xsltproc" ] ; then
+ if [ -e "$stylesheet" ]; then
+ $xsltproc --xinclude style-html.xsl partman-doc.dbk
+ else
+ echo "stylesheet missing; please install the docbook-xsl Debian package"
+ exit 1
+ fi
+else
+ echo "xsltproc not found; please install the xsltproc Debian package"
+ exit 1
+fi
diff --git a/doc/devel/partman/internals.css b/doc/devel/partman/internals.css
new file mode 120000
index 000000000..44d290828
--- /dev/null
+++ b/doc/devel/partman/internals.css
@@ -0,0 +1 @@
+../internals/internals.css
\ No newline at end of file
diff --git a/doc/devel/partman/partman-doc.dbk b/doc/devel/partman/partman-doc.dbk
new file mode 100644
index 000000000..fafd15c73
--- /dev/null
+++ b/doc/devel/partman/partman-doc.dbk
@@ -0,0 +1,1751 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [
+<!-- Include entity definition file by uncommenting the following -->
+<!-- <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata; -->
+]>
+
+<book lang="en">
+
+<title>Partition Management for the Debian Installer</title>
+
+<bookinfo>
+
+<authorgroup>
+<author><personname>Anton Zinoviev</personname><email>anton@lml.bas.bg</email></author>
+
+</authorgroup>
+<releaseinfo></releaseinfo>
+
+<pubdate><!-- put date --></pubdate>
+
+
+<copyright><year> 2003,2004,2007</year><holder>Anton Zinoviev</holder></copyright>
+<legalnotice>
+<para>
+This manual is free software; you may redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2, or (at your option) any later version.
+</para>
+<para>
+This is distributed in the hope that it will be useful, but <emphasis>without
+any warranty</emphasis>; without even the implied warranty of merchantability
+or fitness for a particular purpose. See the GNU General Public License for
+more details.
+</para>
+<para>
+A copy of the GNU General Public License is available as
+<literal>/usr/share/common-licenses/GPL</literal> in the Debian GNU/Linux
+distribution or on the World Wide Web at the <ulink
+url="http://www.gnu.org/copyleft/gpl.html";>GNU website</ulink>. You can also
+obtain it by writing to the Free Software Foundation, Inc., 51 Franklin St,
+Fifth Floor, Boston, MA 02110-1301, USA.
+</para>
+</legalnotice>
+
+</bookinfo>
+
+
+<chapter id="ch1"><title>Introduction</title>
+<para>
+There are many wishlist features that we might desire from any installer of
+GNU/Linux and that are related to partitioning:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The partitioner should support different file systems. Some of them need more
+care than only libraries and suitable arguments for <command>mount</command>.
+</para>
+</listitem>
+<listitem>
+<para>
+It should support not only regular partitions but also software RAID and LVM as
+well as encrypted file systems.
+</para>
+</listitem>
+<listitem>
+<para>
+It should be able to partition disks automatically and allow the user to
+inspect and customise the automatic partitioning later.
+</para>
+</listitem>
+<listitem>
+<para>
+It should be able to resize partitions and move their contents from one place
+to another.
+</para>
+</listitem>
+<listitem>
+<para>
+The users should be protected from mistakes – by allowing them to undo their
+partitioning operations.
+</para>
+</listitem>
+<listitem>
+<para>
+The partitioner should discover that there is already some installed GNU/Linux
+system and analyse its <command>fstab</command>, <command>passwd</command>,
+etc. in order to provide an automatic upgrade from the old already installed
+GNU/Linux system to the new one.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+One nice feature of the Debian installer is that it is modular. Its components
+are packaged in separate udebs and they can have relatively independent
+development process. This document describes how we can solve all mentioned
+tasks keeping the Debian installer as modular as it is now. Ideally in order
+to add some new feature only a few new udebs must be all that is needed – no
+changes in the existing udebs and no recompilation would be required.
+</para>
+<para>
+The script <filename>partman</filename> from the package <systemitem
+role="package">partman-base</systemitem> opens the main partitioning menu; it
+may look like this one:
+</para>
+<screen>
++------------------+ [!!] Partition the storage devices +-----------------+
+| Partition, free space or device to be modified |
+| |
+| IDE1 master - Seagate U Series 40810 (40.0 GB) |
+| #3 primary 2.1 GB B F ext3 / |
+| pri/log 4.4 GB FREE SPACE |
+| #5 logical 3.6 GB |
+| #7 logical 10.0 GB F ext3 /usr |
+| #8 logical 19.9 GB K ext2 /home |
+| IDE2 master - Maxtor 6Y120L0 (122.9 GB) |
+| #7 logical 1.0 GB linux-swap |
+| logical 114.5 GB FREE SPACE |
+| #5 logical 5.5 GB reiserfs |
+| #6 logical 1.9 GB |
+| |
+| Undo changes to partitions |
+| Finish partitioning and write changes to disk |
+| |
+| <Go Back> <Continue> |
+| |
++-------------------------------------------------------------------------+
+</screen>
+<para>
+When the users choose some free space they are offered to create a new
+partition just like they are in <command>cfdisk</command>. When users choose a
+partition they are offered with a menu with various editing operations:
+</para>
+<screen>
++------------------+ [!!] Partition the storage devices +-----------------+
+| Settings on the partition: |
+| |
+| Usage method: format the partition |
+| File system: ext3 |
+| Mount point: /var/mail |
+| Mount options: noatime,nodev,nosuid,noexec,usrquota |
+| Bootable flag: off |
+| Size: 995.2 MB |
+| |
+| Finished setting up partition |
+| Delete the partition |
+| |
+| <Go Back> <Continue> |
+| |
++-------------------------------------------------------------------------+
+</screen>
+<para>
+All udebs are allowed to add items to this menu as well as to several other
+menus. They can add new items in the list of devices such as software RAID and
+LVM devices, networked file systems, encrypted partitions, etc. The package
+<systemitem role="package">partman-partitioning</systemitem> is responsible for
+pure partitioning operations such as creation of new partitions and deletion.
+The packages <systemitem role="package">partman-target</systemitem> and
+<systemitem role="package">partman-basicmethods</systemitem> are responsible
+for the items `Choose how this partition should be used' and `Choose a file
+system'. The package <systemitem
+role="package">partman-basicfilesystems</systemitem> adds support for
+<literal>ext2</literal>, <literal>linux-swap</literal>,
+<literal>fat16</literal> and <literal>fat32</literal>. The package <systemitem
+role="package">partman-ext3</systemitem> adds support for
+<literal>ext3</literal>.
+</para>
+</chapter>
+
+<chapter id="ch2"><title>Changes in partman since 2005</title>
+<para>
+This chapter documents important changes in the sctructure of partman. It is
+provided as a test if you need to reread some of the sections in this document.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+New directory <command>check.d</command> with some of the scripts formerly in
+<command>finish.d</command>
+</para>
+</listitem>
+<listitem>
+<para>
+New directory <command>display.d</command> with different methods to do the
+partitioning (manual, automatic, etc.)
+</para>
+</listitem>
+<listitem>
+<para>
+New command GET_LABEL_TYPE in parted_server
+</para>
+</listitem>
+</itemizedlist>
+</chapter>
+
+<chapter id="ch3"><title>Package interrelations</title>
+<section id="basics"><title>Basics</title>
+<para>
+The GNU Parted disk partitioning library provides high-level, architecture
+independent functions for operations such as creating, deleting, resizing and
+moving of partitions. Most of the functions of libparted work in a
+nondestructive way. The partition table is written in data structures and any
+change in the partition table happens only in these data structures rather than
+directly on the disk. This makes possible to implement partitioning tools
+based on <systemitem role="package">libparted</systemitem> that support undoing
+of the editing operations.
+</para>
+<para>
+However we have to solve two problems. The first is that we want to use as
+much as possible shell scripts rather than C programs. The second is that
+different programs have to operate with same instance of libparted structures.
+For example the user can use some tool for automatic partitioning, then correct
+or customise the automatic partitioning, perform some other arbitrary
+operations being still allowed to undo everything.
+</para>
+<para>
+There is one obvious solution of these two problems – we keep the data
+structures of libparted in a daemon process and communicate with it in order to
+make changes in these data structures. This process is
+<filename>/bin/parted_server</filename> from the package <systemitem
+role="package">partman-base</systemitem>.
+</para>
+<para>
+The scripts from <filename>/lib/partman/init.d/</filename> are executed before
+all partitioning operations. They can be used to initialise the partitioning
+system. The scripts may be invoked more than once in which case they should
+behave properly. For example this directory can contain a script to discover
+the existing hard drives. If invoked for second time the script must either do
+nothing or check if there is some new kernel module giving access to new still
+undiscovered device.
+</para>
+<para>
+Any udeb may install a script in this directory. For example the script
+<filename>/lib/partman/init.d/30parted</filename> from the package <systemitem
+role="package">partman-base</systemitem> is responsible for running
+<command>parted_server</command>. Notice that the scripts are prefixed by a
+two-digit number. This number determines the order the scripts are executed.
+If any of the scripts exit with non-zero exit code the partitioning will be
+aborted. This means that in almost all cases these scripts must end with
+exit-code 0.
+</para>
+<para>
+When the initialisation completes, the scripts from
+<filename>/lib/partman/display.d</filename> are executed. These scripts are
+supposed to make the actual partitioning interactively or non-interactively.
+The exit code <replaceable>code</replaceable> of these scripts is interpreted
+as follows:
+</para>
+<variablelist>
+<varlistentry>
+<term><replaceable>code</replaceable> = 0</term>
+<listitem>
+<para>
+The script did nothing, move to the next script in
+<command>display.d</command>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>1 <= <replaceable>code</replaceable> <= 99</term>
+<listitem>
+<para>
+Restart the partitioning (move again to the first script in
+<command>display.d</command>).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>100 <= <replaceable>code</replaceable> <= 254</term>
+<listitem>
+<para>
+The script successfully partitioned the disks, do not execute the following
+scripts in <command>display.d</command>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><replaceable>code</replaceable> = 255</term>
+<listitem>
+<para>
+Abort the partitioning.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>
+When the disks become ready, the scripts in
+<filename>/lib/partman/check.d</filename> are executed. They have to check if
+everything is OK to proceed with commiting the changes on the disks, mounting
+file systems, etc. For example the package <systemitem
+role="package">partman-target</systemitem> installs there a script to check if
+there is a root file system. If a script in <command>check.d</command> exits
+with non-zero exit code then the scripts in <command>display.d</command> are
+executed again and as a result the user is allowed to fix the partitioning.
+</para>
+<para>
+The directory <command>check.d</command> is remarkable with the fact that some
+of the scripts in it are installed by non-partman packages. The packages for
+the various bootloaders (lilo, grub, palo, etc.) install there scripts to
+ensure the partitioning scheme conforms to their requirements.
+</para>
+<para>
+While the user is modifying the partitions this happens only in the memory of
+the computer and not in the edited devices. This is because almost all changes
+happen either in the data-structures of <command>parted_server</command> or in
+files in the installer's ram-disk. That's why we can provide the user with the
+option to undo everything. When the user chooses to undo the scripts in the
+directory <filename>/lib/partman/undo.d/</filename> are executed. Any udeb may
+install a script in this directory. For example the script
+<filename>/lib/partman/undo.d/30parted</filename> is responsible for restoring
+the contents of the data structures of <command>parted_server</command>. In
+most cases the scripts from <command>undo.d</command> must exit with exit-code
+0. If any of the scripts exit with non-zero exit code the partitioning will be
+aborted.
+</para>
+<para>
+In order to perform the editing operations on the storage devices (and in
+particular to transfer the partitions from the internal data-structures of
+<command>parted_server</command> to the hard disks) the scripts from the
+directory <filename>/lib/partman/commit.d/</filename> are executed. The order
+in which these scripts are executed is determined again by two-digit prefixes
+in the script names. Every script from <command>commit.d</command> is
+guaranteed that the scripts ordered before it have been already executed.
+However if any of the scripts exit with non-zero exit-code the execution of the
+scripts in <command>commit.d</command> will be stopped. In this case the
+partitioning will continue and the user is expected to fix the problem. If any
+script exits with non-zero exit code it is supposed to inform the user what
+went wrong using debconf.
+</para>
+<para>
+There are two cases when the scripts from <command>commit.d</command> are
+executed. The first case is when the user wants to commit the changes to the
+disks but continue partitioning. The second case is when the partitioning
+ends. In the first case if none of the scripts fails the scripts from
+<command>init.d</command> will be also executed and the user will be returned
+to the partitioning dialog. In the second case the scripts from
+<command>finish.d</command> will be executed. In both cases if any of the
+scripts in <command>commit.d</command> fail the user will be returned
+immediately back to the partitioning dialog.
+</para>
+<para>
+The scripts from <filename>/lib/partman/finish.d/</filename> are responsible
+for final tasks such as to mount partitions on <filename>/target</filename>,
+generate of <command>fstab</command>, stop <command>parted_server</command>
+etc.<footnote><para> What tasks will be performed depends on what udebs are
+unpacked. If the packages responsible for mounting partitions and creating
+fstab are not unpacked we have only a simple partitioner providing <systemitem
+role="package">partitioned-harddrives</systemitem>. If they are unpacked they
+provide also <systemitem role="package">made-filesystems</systemitem> and
+<systemitem role="package">mounted-partitions</systemitem>. </para>
+</footnote> If any of these scripts exit with non-zero exit-code the execution
+of the scripts will be stopped. If the exit-code was 1 then the user will be
+returned back to the partitioning dialog and is expected to correct the
+problem. If the exit-code was neither 0 nor 1 then the partitioning will be
+aborted.
+</para>
+<para>
+For every hard disk in the system the script
+<filename>/lib/partman/init.d/30parted</filename> creates a subdirectory in
+<filename>/var/lib/partman/devices/</filename> and informs
+<command>parted_server</command> that the device is to be edited (`opens' the
+device). All udebs that provide storage device (software RAID, LVM, encrypted
+partitions) must do the same. This subdirectory must contain at least three
+files – <command>device</command>, <command>model</command> and
+<command>size</command>. The first contains the name of a device file (for
+example <filename>/dev/ide/host0/bus0/target0/lun0/disc</filename>). The
+second contains the name of the device (for example `Maxtor 6Y120L0'). The
+third contains the physical size of the storage device (in bytes, for example
+`122942324736'). <footnote><para> Please notice that udebs that provide
+support for storage `devices' that cannot be partitioned (such as networked
+file systems) should not create a subdirectory in
+<filename>/var/lib/partman/devices</filename> and certainly cannot provide the
+device to the management of <command>parted_server</command>. </para>
+</footnote> The subdirectories of
+<filename>/var/lib/partman/devices/</filename> can but are not obligated to
+contain additional information. We call these subdirectories <emphasis>device
+directories</emphasis>.
+</para>
+<para>
+Every partition in a device managed by <command>parted_server</command> is
+given a unique name having the form
+<replaceable>first_byte</replaceable>-<replaceable>last_byte</replaceable>.
+This name can be used to determine where the partition starts and where it
+ends.<footnote><para> Unlike one can suppose <command>parted_server</command>
+always measures sizes and places in bytes rather than in sectors.
+<replaceable>Last_byte</replaceable> is the number of the last byte of the last
+sector of the partition. </para> </footnote> If the device directory contains
+a subdirectory named
+<command><replaceable>first_byte</replaceable>-<replaceable>last_byte</replaceable></command>
+then this subdirectory stores information about the partition. We call this
+subdirectory <emphasis>directory of the partition</emphasis>. We call the
+string<replaceable>first_byte</replaceable>-<replaceable>last_byte</replaceable>
+`<emphasis>id</emphasis>' of the partition.
+</para>
+</section>
+
+<section id="menudirs"><title>Menu-directories</title>
+<para>
+There are several menus involved in partitioning. In order to keep the Debian
+installer modular and extensible we want to allow every udeb to install items
+in these menus. Let us be more specific. When the users decide to format some
+existing partition we need a menu with an item for every supported file system.
+Obviously we don't want to hardwire the list of the supported file systems
+anywhere in our installer. If we want to add support to the installer say for
+XFS or UMSDOS file systems, only a few new udebs must be all that is needed.
+</para>
+<para>
+In order to achieve this flexibility the package <systemitem
+role="package">partman-base</systemitem> provides support for the so-called
+menu-directories. Every such directory contains files named
+<command>question</command> and <command>priority</command>. They contain the
+name of a Debconf template and the priority of the question correspondingly.
+The template must have exactly the following type and choices fields:
+</para>
+<screen>
+Type: select
+Choices-C: ${CHOICES}
+Choices: ${DESCRIPTIONS}
+</screen>
+<para>
+All other files in the menu directory are subdirectories. Any udeb can install
+such a subdirectory in order to add items to the menu. For example the udebs
+for software RAID volumes can install in the menu of the editing operations an
+item to resize the chosen partition to have the same size as another. These
+subdirectories must contain two scripts – <command>choices</command> and
+<command>do_option</command>. The purpose of the first script is to print menu
+items. For every menu item <command>choices</command> must print a line having
+the form
+</para>
+<screen>
+<replaceable>menu_item_id</replaceable><TAB>The text for the user
+</screen>
+<para>
+The script <command>choices</command> is allowed to print nothing. In this
+case no item for the menu is created. Here <literal><TAB></literal> is
+ASCII 9. The text `The text for the user' will be presented to the users. If
+they choose this particular menu item the script <command>do_option</command>
+will be invoked.
+</para>
+<para>
+The script <command>choices</command> may be given some arguments depending on
+the particular menu-directory. The first argument given to
+<command>do_option</command> is always the
+<replaceable><literal>menu_item_id</literal></replaceable> of the chosen menu
+item. The rest of the arguments are the same as the arguments given to
+<command>choices</command>.
+</para>
+<para>
+Let we take as an example the menu that the users see when they choose to edit
+some particular partition. The file <command>question</command> in the
+menu-directory for this menu contains the text
+<literal>partman/active_partition</literal>. This is the name of a
+Debconf-template with type `select' and description `Please choose what to do
+with this partition'. The package <systemitem
+role="package">partman-partitioning</systemitem> installs in this
+menu-directory some subdirectories – <command>62change_name</command>,
+<command>65toggle_bootable</command> and <command>85delete</command>. The
+script <filename>62change_name/choices</filename> is given two arguments –
+the hard disk we edit and the id of the partition. It checks if the type of
+the partition table supports partition names in which case it prints the line
+</para>
+<screen>
+setname<TAB>Set the name of the partition
+</screen>
+<para>
+If the partition table doesn't support names, then this script prints nothing.
+When the user chooses to `set the name of the partition' the script
+<filename>62change_name/do_option</filename> is invoked. Its first argument is
+<literal>setname</literal> (this is the first part of the line printed by
+<command>choices</command>) and the other arguments are the same to the
+arguments given to the script <command>choices</command>. In our case the
+script <command>do_option</command> ignores its first argument. The script
+<command>do_option</command> can use its first argument in order to determine
+which menu item the user has chosen in cases when <command>choices</command>
+has printed several.
+</para>
+<para>
+Notice that the names of the subdirectories in any menu-directory start with
+two digits. They are used to determine the order of the items in the menu.
+</para>
+</section>
+
+<section id="s3.3"><title>Partitioning</title>
+<para>
+The partitioning starts with the menu of the menu-directory
+<filename>/lib/partman/choose_partition</filename>. This is the main
+partitioning menu. Every udeb is allowed to install new items in it. If the
+script <command>do_option</command> exits with exit-code 0 the user will be
+shown again the main partitioning menu. If the script exits with exit-code 100
+this means that the partitioning should be finished. In this case the scripts
+from <command>commit.d</command> and <command>finish.d</command> will be
+executed as described in <xref linkend="basics"/>. If the script
+<command>do_option</command> exits with exit code 255 the partitioning will be
+aborted immediately.
+</para>
+<para>
+The main partitioning menu always contains an item for every partitioned
+storage device, an item for every partition and an item for every free space.
+</para>
+<para>
+If the user chooses a storage device the menu of the menu-directory
+<filename>/lib/partman/storage_device</filename> will be opened. The first
+argument given to <command>choices</command> is the device
+directory<footnote><para> We are not going to describe the arguments given to
+<command>do_option</command>. Look at <xref linkend="menudirs"/>. </para>
+</footnote>.
+</para>
+<para>
+If the user chooses a free space the menu-directory
+<filename>/lib/partman/free_space</filename> will be opened. The first
+argument given to <command>choices</command> is the device directory. The
+second argument is the id of the free space.
+</para>
+<para>
+If the user chooses an active partition the menu-directory
+<filename>/lib/partman/active_partition</filename> will be opened. The first
+argument given to <command>choices</command> is the device directory. The
+second argument is the id of the chosen partition. If the script
+<command>do_option</command> exits with exit-code 0 the user will be shown
+again the menu <command>active_partition</command> for the same partition. If
+the script <command>do_option</command> exits with exit-code 100 or 255 the
+user will be returned back to the main partitioning menu. This should happen
+when the id of the partition is invalidated, for example when the partition is
+deleted or resized.
+</para>
+<para>
+In the main partitioning menu the partitions are presented by lines of this
+kind:
+</para>
+<screen>
+#8 primary 19.9 GB K ext2 /home
+</screen>
+<para>
+Notice that it is useless to indicate that the partition is primary if the type
+of the partition table is `mac' as this partition table doesn't support logical
+partitions. On the other hand this partition table supports partition names.
+We see that we need a flexible way to determine how the partitions are
+presented in the main partitioning menu.
+</para>
+<para>
+The directory <filename>/lib/partman/visual.d</filename> contains scripts that
+print the parts of the partition line. For example the script
+<filename>/lib/partman/visual.d/filesystem</filename> prints strings like
+`ext3' or `FREE SPACE'. These scripts usualy start with the following cliche:
+</para>
+<screen>
+cd $1
+
+num=$2
+id=$3
+size=$4
+type=$5
+fs=$6
+path=$7
+shift; shift; shift; shift; shift; shift; shift
+name=$*
+</screen>
+<para>
+$1 is the device directory. $num is the number of the partition (for example
+<filename>/dev/hda6</filename> has number 6). $id is the id of the partition.
+$size is the size of the partition (in bytes). If this is an active partition
+then $type is either `primary' or `logical'. If this is a free space then
+$type shows what partition can be created in it and $type can be `primary',
+`logical', `pri/log' or `unusable'. $fs is `free' if this is a free space.
+Otherwise $fs is the type of the file system of this partition as known to
+<command>parted_server</command>. $path is a device name for the partition,
+for example <filename>/dev/ide/host0/bus0/target0/lun0/part6</filename>. $name
+is the name of the partition or the empty string if the partition table doesn't
+support partition names.
+</para>
+<para>
+The script <filename>/lib/partman/commit.d/30parted</filename> transfers the
+partition tables from the internal structures of
+<command>parted_server</command> to the disks. The script
+<filename>/lib/partman/finish.d/80parted</filename> stops
+<command>parted_server</command>.
+</para>
+<para>
+The package <systemitem role="package">partman-base</systemitem> installs in
+<command>update.d</command> (see <xref linkend="update-partitions"/>) a script
+to ensure that for every partition that contains some file system there is a
+file <command>detected_filesystem</command> in the directory of the partition
+whose contents is the type of the detected file system as returned by
+<command>parted_server</command>.
+</para>
+</section>
+
+<section id="s3.4"><title>Setup <filename>/target</filename></title>
+<para>
+Without the package <systemitem role="package">partman-target</systemitem> the
+packages <systemitem role="package">partman-base</systemitem> and <systemitem
+role="package">partman-partitioning</systemitem> provide only the regular
+partitioning operations. However if the package <systemitem
+role="package">partman-target</systemitem> is also unpacked then the user will
+be provided with options to choose file systems for the partitions, specify
+wether they should be formatted and select mount points. The package
+<systemitem role="package">partman-target</systemitem> adds to the menu
+directory <filename>/lib/partman/active_partition</filename> the item `Usage
+method:'. If the user chooses this item the menu directory
+<filename>/lib/partman/choose_method</filename> will be opened. The scripts
+<command>choices</command> from <command>choose_method</command> are given the
+device directory as first argument and the partition id as second argument.
+</para>
+<para>
+The package <systemitem role="package">partman-basicmethods</systemitem> adds
+in the menu of the menu directory <command>choose_method</command> three items:
+`Do not use the partition', `Format the partition' and `Keep and use the
+existing data in the partition' (the last only if some file system is
+detected). Other udebs can provide another methods to use partitions.
+</para>
+<para>
+Every partition that is to be used somehow in the future Debian system should
+have a file named `method' in its directory (what is `directory of a partition'
+is described in <xref linkend="basics"/>). The scripts
+<command>do_option</command> of the menu directory
+<command>choose_method</command> manage the file <command>method</command>. It
+contains the name of the usage method chosen by the user. For example if the
+user chooses to `format the partition' the contents of this file will be
+`format' and if the user chooses to `keep and use the existing data' the
+contents of this file will be `keep'. Partitions that won't be used do not
+have a file <command>method</command>.
+</para>
+<para>
+The udebs providing methods may provide also translatable names of the methods
+for the user interface using debconf templates named
+<command>partman/method_long/<replaceable>some_method</replaceable></command>
+and
+<command>partman/method_short/<replaceable>some_method</replaceable></command>.
+For example the package <systemitem role="package">partman-palo</systemitem>
+providing method <command>palo</command> can provide also the following debconf
+templates:
+</para>
+<screen>
+Template: partman/method_long/palo
+Type: text
+_Description: Palo boot partition
+
+Template: partman/method_short/palo
+Type: text
+_Description: Palo
+</screen>
+<para>
+Another job for the scripts <command>do_option</command> of the menu directory
+<command>choose_method</command> is to create or remove a file named
+<command>use_filesystem</command> in the directory of the partitions. This
+file is created when the usage method requires the partition to be used
+together with some file system. Otherwise it is removed. Example methods that
+are used together with a file system are `format the partition' and `keep and
+use the existing data'. Example methods that are not used together with a file
+system are `LVM physical volume' and `PALO boot partition'.
+</para>
+<para>
+Finaly, the scripts <command>do_option</command> of the menu directory
+<command>choose_method</command> have to create or remove a file named `format'
+in the directory of the partitions. If the partition directory contains a file
+named <command>format</command> then it will be formatted. Otherwise it will
+not be formatted. For example if the user chooses to `format the partition'
+the script <command>do_option</command> will create a file
+<command>format</command>. If the user chooses to `keep and use the existing
+data' the file <command>format</command> will be removed if it exists.
+</para>
+<para>
+The menu item `Choose a file system' in the menu directory
+<command>active_partition</command> is also provided by the package <systemitem
+role="package">partman-target</systemitem>. If the user chooses it the menu
+<command>choose_filesystem</command> will be opened. This menu however is not
+produced using a menu directory.
+</para>
+<para>
+Packages that provide support for some file system should install a script in
+the directory <filename>/lib/partman/valid_filesystems</filename>. The first
+argument given to this script is some device directory, the second argument is
+the id of some partition and the third argument is one of the strings
+`formatable' and `existing'. If it is `formatable' then the job of the script
+is to check if the specified partition can be formatted and used. If the third
+argument is `existing' then the job of the script is to check if the partition
+can be used without formatting. In either case if the partition can be used
+then the script should print a line with the identifier of the type of the file
+system.
+</para>
+<para>
+Packages that provide support for some file systems use the directory
+<filename>/lib/partman/parted_names</filename> to define a mapping from the
+unique file system type identifiers to the names used by
+<command>parted_server</command>. Suppose for example that the package
+providing support for UMSDOS file system chooses the string `umsdos' as unique
+identifier for the file system. Then this package must install in this
+directory a file named <command>umsdos</command> whose contents is the string
+`fat16'. This means that <command>parted_server</command> will know UMSDOS
+file systems as being fat16 file systems.
+</para>
+<para>
+The udebs providing file systems may provide also translatable names of the
+file systems for the user interface using debconf templates named
+<command>partman/filesystem_long/<replaceable>some_filesystem</replaceable></command>
+and
+<command>partman/filesystem_short/<replaceable>some_filesystem</replaceable></command>.
+For example the package <systemitem role="package">partman-ext3</systemitem>
+providing file system with unique identifier <command>ext3</command> can
+provide also the following debconf templates:
+</para>
+<screen>
+Template: partman/filesystem_long/ext3
+Type: text
+_Description: Extended 3
+
+Template: partman/filesystem_short/ext3
+Type: text
+_Description: Ext3
+</screen>
+<para>
+Most of the packages that provide support for a file system will have to add an
+item `Mount point:' to the menu <command>active_partition</command>. Of course
+this item should be shown only when the contents of the file
+<command>acting_filesystem</command> is appropriate. The mount point chosen by
+the user should be written in a file named <command>mountpoint</command>
+situated in the directory of the partition. If the user chooses not to mount
+this file system then the file <command>mountpoint</command> should be removed
+(if it exists).
+</para>
+<para>
+In order to be able to mount file systems and generate fstab the directories
+<filename>/lib/partman/fstab.d/</filename> and
+<filename>/lib/partman/mount.d/</filename> are used. The scripts from
+<command>fstab.d</command> should print lines in a form similar to that of
+<filename>/etc/fstab</filename>:
+</para>
+<screen>
+<replaceable>file_system</replaceable> <replaceable>mount_point</replaceable> <replaceable>type</replaceable> <replaceable>options</replaceable> <replaceable>dump</replaceable> <replaceable>pass</replaceable>
+</screen>
+<para>
+The first field (<replaceable><literal>file_system</literal></replaceable>) is
+the name of a device that can be accessed by the installer. For example this
+can be <filename>/dev/ide/host0/bus0/target0/lun0/part5</filename> despite that
+in the future system this device will be named <filename>/dev/hda5</filename>.
+On the other hand the other five fields should look exactly the same way as in
+the <command>fstab</command> to be generated. For example
+<replaceable><literal>options</literal></replaceable> can contain options such
+as <literal>quota</literal> that are senseless for the installer.
+</para>
+<para>
+The scripts from <command>mount.d</command> are used to mount file systems. A
+string having the same form as the lines output by the scripts from
+<command>fstab.d</command> should be given as first argument to any script from
+<command>mount.d</command>. Any script from <command>mount.d</command> checks
+if it can mount the requested file system. If it cannot then the script exits
+with some non-zero exit code. Otherwise the script must mount the file system
+in the proper place in the hierarchy over <filename>/target</filename>, print
+on its standard output a command that should be used in order to unmount the
+file system and exit with exit code 0.
+</para>
+<para>
+The scripts in the directories <command>fstab.d</command> and
+<command>mount.d</command> are installed by the udebs that provide support for
+file systems.
+</para>
+<para>
+Packages that provide support for file systems install in
+<command>commit.d</command> a script to format the partitions that the user has
+requested to be formatted. The package <systemitem
+role="package">partman-target</systemitem> installs in
+<command>finish.d</command> a script to mount the partitions on
+<filename>/target</filename>. The packages that provide support for storage
+devices (RAID, LVM, etc.) install in <command>finish.d</command> a script to
+add in <filename>/target/etc/fstab</filename> the necessary lines.
+</para>
+<para>
+The package <systemitem role="package">partman-target</systemitem> installs in
+<command>update.d</command> (see <xref linkend="update-partitions"/>) a script
+to ensure that for every partition that is to be used there is a file
+<command>acting_filesystem</command> in the directory of the partition whose
+contents is the identifier of the type of file system under which the partition
+should be used.
+</para>
+</section>
+
+</chapter>
+
+<chapter id="ch4"><title><filename>/lib/partman/lib/*</filename></title>
+<para>
+Various scripts in partman make use of <emphasis>function libraries</emphasis>:
+separate files, mostly containing shell functions, that are sourced by scripts
+so they can make use of common functions and code duplication can be avoided.
+</para>
+<para>
+The main function library is <filename>base.sh</filename>, provided by
+<systemitem role="package">partman-base</systemitem>. This file is sourced by
+most scripts in partman as it defines a lot of useful variables and common
+functions. Some of these are documented in the remainder of this chapter.
+<footnote><para> The script <filename>base.sh</filename> has become somewhat
+too long and this probably makes its sourcing slow. Although some
+reorganization has already taken place, it could be a good idea to split it up
+further. </para> </footnote>
+</para>
+<para>
+Other packages provide more targeted function libraries. In most cases their
+scope and use can easily be determined from their name.
+</para>
+<section id="s4.1"><title>Environment</title>
+<para>
+The variables <literal>TAB</literal> and <literal>NL</literal> have values
+ASCII 9 and ASCII 10 correspondingly. They can be used as temporary values
+for the variable <literal>IFS</literal>. The function
+<command>restore_ifs</command> restores the variable <literal>IFS</literal> its
+original value.
+</para>
+<para>
+The function library <command>base.sh</command> also contains simple
+reimplementations of <command>basename</command> and <command>dirname</command>
+so that busybox doesn't have to provide them.
+</para>
+</section>
+
+<section id="s4.2"><title>Menus</title>
+<para>
+The function <command>debconf_select</command> is a high level function to ask
+user with a menu using a Debconf question with type `select'. Synopsis:
+</para>
+<screen>
+debconf_select <replaceable>priority</replaceable> <replaceable>template</replaceable> <replaceable>choices</replaceable> <replaceable>default</replaceable>
+</screen>
+<para>
+The first argument is the debconf-priority of the question and the second is
+the name of the template to be used. The third argument is a newline-separated
+list of items for the menu. Each item has the form
+</para>
+<screen>
+<replaceable>menu_item_id</replaceable><TAB>The text for the user
+</screen>
+<para>
+Here <literal><TAB></literal> is ASCII 9. The text `The text for the
+user' is the text of the menu item. If
+<replaceable><literal>menu_item_id</literal></replaceable> of some menu-item is
+identical with the fourth argument given to <command>debconf_select</command>
+then this menu-item will be default.
+</para>
+<para>
+If the user cancels the question <command>debconf_select</command> returns with
+exit-code 255. Otherwise the value of the variable <literal>RET</literal> will
+be the <replaceable><literal>menu_item_id</literal></replaceable> of the chosen
+menu item. If the chosen menu item was chosen by the user then the exit-code
+is 0. If the item was chosen automatically (due to the debconf-priority or to
+some other reason) the exit-code is 1.
+</para>
+<para>
+The function <command>debconf_select</command> doesn't care to
+<command>db_fset</command> <literal>$template</literal> <literal>seen</literal>
+<literal>false</literal>. The template must have exactly the following type
+and choices fields:
+</para>
+<screen>
+Type: select
+Choices-C: ${CHOICES}
+Choices: ${DESCRIPTIONS}
+</screen>
+<para>
+The udebs that generate menus using menu-directories use the function
+<command>ask_user</command> instead of <command>debconf_select</command>.
+Synopsis:
+</para>
+<screen>
+ask_user <replaceable>a_menu_directory</replaceable> <replaceable>additional_optional_arguments</replaceable>...
+</screen>
+<para>
+This function displays the menu for
+<literal><replaceable>a_menu_directory</replaceable></literal>. The first
+argument is a menu-directory (see <xref linkend="menudirs"/>). If the user
+cancels the dialog then <command>ask_user</command> returns with exit code 255.
+Otherwise it returns with the exit code of the script
+<command>do_option</command>.
+</para>
+<para>
+If <command>ask_user</command> is called re-entrantly from within a
+<command>do_option</command> script, then the calling
+<command>do_option</command> script should typically be careful to handle or
+discard exit code 255 itself (and sometimes other codes, depending on the
+protocol in force) to avoid a backup operation inadvertently backing up out of
+several nested menus at once.
+</para>
+<para>
+The script <command>choices</command> is invoked with
+<replaceable><literal>additional_optional_arguments</literal></replaceable> as
+arguments. The first argument given to <command>do_option</command> is the
+<replaceable><literal>menu_item_id</literal></replaceable> of the chosen menu
+item and the other arguments are again
+<replaceable><literal>additional_optional_arguments</literal></replaceable>.
+</para>
+<para>
+To set the default selected item in a menu-directory, use the function
+<command>menudir_default_choice</command>. Synopsis:
+</para>
+<screen>
+menudir_default_choice <replaceable>a_menu_directory</replaceable> <replaceable>subdirectory</replaceable> <replaceable>menu_item_id</replaceable>
+</screen>
+<para>
+Where the <replaceable><literal>subdirectory</literal></replaceable> is the
+name of a subdirectory in the menu-directory with the leading sequence number
+stripped off and <replaceable><literal>menu_item_id</literal></replaceable> is
+the id of a menu-item printed by
+<filename><replaceable>a_menu_directory</replaceable>/??<replaceable>subdirectory</replaceable>/choices</filename>.
+The specified item is set as default not forever but only for the next
+invocation of <command>ask_user</command>. It is not an error to set as
+default non-existing item; in this case the first item in the menu will be
+default.
+</para>
+<para>
+The function <command>partition_tree_choices</command> prints a sequence of
+lines in the form
+</para>
+<screen>
+<replaceable>menu_item_id</replaceable><TAB>The text for the user
+</screen>
+<para>
+– one for every storage device and one for every partition. The
+<replaceable><literal>menu_item_id</literal></replaceable> of the storage
+devices is their storage directory. The
+<replaceable><literal>menu_item_id</literal></replaceable> of the partitions
+has the form
+<replaceable>storage_directory</replaceable>//<replaceable>partition_id</replaceable>.
+The output of <command>partition_tree_choices</command> can be given as third
+argument to <command>debconf_select</command>.
+</para>
+</section>
+
+<section id="s4.3"><title>Long numbers</title>
+<para>
+Notice that the sizes of most of the present storage devices are so large that
+we cannot measure them using 32-bit integers. Consequently we cannot use the
+usual shell arithmetic. The functions <command>longint_le</command>,
+<command>longint2human</command>, <command>human2longint</command> and
+<command>valid_human</command> exist in order to deal with such big numbers.
+</para>
+<para>
+The function <command>longint_le</command> is used to compare two big numbers.
+</para>
+<screen>
+longint_le <replaceable>number1</replaceable> <replaceable>number2</replaceable>
+</screen>
+<para>
+returns with exit code 0 if the first number is less or equal to the second
+and returns 1 otherwise.
+</para>
+<para>
+The function <command>longint2human</command> accepts in its first argument
+some number of bytes, converts it to something that is more meaningful for
+humans and outputs the result. For example
+</para>
+<screen>
+longint2human 1234567890
+</screen>
+<para>
+gives <literal>1.2 GB</literal>. Notice that this function rounds its
+argument.
+</para>
+<para>
+The function <command>human2longint</command> is used for the opposite
+convertion:
+</para>
+<screen>
+human2longint 1.234Gb
+</screen>
+<para>
+gives <literal>1234000000</literal>.
+</para>
+<para>
+The function <command>valid_human</command> returns with exit code 0 when its
+first argument is a string that is suitable to be given to
+<command>human2longint</command>. Otherwise it returns with exit code 1.
+</para>
+</section>
+
+<section id="update-partitions"><title>Updating partition directories</title>
+<para>
+Different components of the installer may need to get information about the
+partitions. They can communicate with <command>parted_server</command> in
+order to know the characteristics of the partition. However not everything can
+be known from <command>parted_server</command>. Imagine an udeb that provides
+the user with the option to upgrade some existing GNU/Linux installation. This
+udeb analyses the <command>fstab</command> and knows that some partition is
+used as <filename>/home</filename> and should not be formatted. This sort of
+information has nothing to do with <command>parted_server</command>. The udeb
+stores it in a subdirectory of the device directory named after the id of the
+partition.
+</para>
+<para>
+But now a problem arises. Suppose that the user chooses to format some
+partition as ext2 and mount it on <filename>/home</filename>. The udebs
+responsible for formatting and mounting create the directories
+<command>filesystem</command> and <command>mountpoint</command> in the
+partition. What will happen if the users change their mind and decide to use
+the same partition as swap space? Swap spaces have no mount points and the
+file <command>mountpoint</command> should be removed. Who is responsible for
+removing it? The udeb that allows the user to choose a file system for the
+partition doesn't have to know that swap-spaces have no mount points, only the
+udeb that provides support for swap-spaces can know that the file
+<command>mountpoint</command> should be removed.
+</para>
+<para>
+In order to solve this difficulty every script that makes changes to some
+partition should invoke the function <command>update_partition</command> from
+<command>base.sh</command>. Synopsis:
+</para>
+<screen>
+update_partition <replaceable>device_directory</replaceable> <replaceable>partition_id</replaceable>
+</screen>
+<para>
+In order to update the contents of the directory
+<filename><replaceable>device_directory</replaceable>/<replaceable>partition_id</replaceable></filename>
+the function <command>update_partition</command> executes the scripts from the
+directory <filename>/lib/partman/update.d/</filename>. Every udeb is allowed
+to install scripts in this directory. Their names are prefixed by two-digit
+numbers that control the order of the execution. The scripts from
+<command>update.d</command> are given several arguments. $1 is the
+<replaceable>device_directory</replaceable>. $2 is the number of the partition
+(<filename>/dev/hda6</filename> will have number 6). $3 is the id of the
+partition. $4 is the length of the partition (in bytes). $5 is the type of
+the partition, it can be either `primary' or `logical'. $6 is the type of the
+file system as known to <command>parted_server</command>, in most cases you
+should ignore this argument. $7 is the device name (for example
+<filename>/dev/ide/host0/bus0/target0/lun0/part6</filename>).
+"$8 $9 $10 $11 ..." is the name of the partition in partition tables that
+support partition names. Otherwise $8, $9, $10,... are not defined.
+</para>
+</section>
+
+<section id="s4.5"><title>Communication with <command>parted_server</command></title>
+<para>
+The package <systemitem role="package">partman-base</systemitem> creates two
+FIFOs – <filename>/var/lib/partman/infifo</filename> and
+<filename>/var/lib/partman/outfifo</filename>.
+<command>Parted_server</command> reads instructions from
+<command>infifo</command> and responds by writting to
+<command>outfifo</command>. Consequently the clients write to
+<command>infifo</command> and read from <command>outfifo</command>. The
+function library <command>base.sh</command> contain several functions to make
+the communication with <command>parted_server</command> easier. Here we will
+omit the details, if you want to know the exact communication protocol please
+read how these functions are implemented.
+</para>
+<para>
+The functions <command>open_infifo</command>, <command>close_infifo</command>,
+<command>open_outfifo</command> and <command>close_outfifo</command> are called
+without arguments. They open and close <command>infifo</command> and
+<command>outfifo</command> assigning them file descriptors 6 and 7
+correspondingly. You do not need to use these low-level functions.
+</para>
+<para>
+The function <command>write_line</command> prints its arguments to
+<command>outfifo</command>.
+</para>
+<para>
+The function <command>read_line</command> reads from <command>infifo</command>
+a line, splits it in fields according to <literal>$IFS</literal> and assigns
+these fields to variables whose names are given to <command>read_line</command>
+as arguments. For example
+</para>
+<screen>
+read_line x y z
+</screen>
+<para>
+reads a line from <command>infifo</command>, splits it and assigns the first
+field to the variable <literal>x</literal>, the second field to the variable
+<literal>y</literal> and the rest to the variable <literal>z</literal>. You
+see that <command>read_line</command> is used the same way as the shell
+operator <command>read</command>.
+</para>
+<para>
+The function <command>read_paragraph</command> reads consequently lines from
+<command>infifo</command> until it reaches an empty line. It prints the read
+lines with the exception of the last empty line.
+</para>
+<para>
+The function <command>read_list</command> reads lines the same way as the
+function <command>read_paragraph</command>. However the function
+<command>read_list</command> always prints only one line that is a
+comma-separated sequence of the lines read from <command>infifo</command>. If
+<command>read_paragraph</command> prints
+</para>
+<screen>
+This is the first line
+This is the second line
+This is the third line
+</screen>
+<para>
+<command>read_list</command> prints
+</para>
+<screen>
+This is the first line, This is the second line, This is the third line
+</screen>
+<para>
+In order to initiate a communication dialog with
+<command>parted_server</command> you will use the function
+<command>open_dialog</command>. You will invoke it in the device directory of
+the device you want to issue command about. The first argument of
+<command>open_dialog</command> is a command for
+<command>parted_server</command>. The rest arguments are arguments for the
+command.
+</para>
+<para>
+You use the function <command>close_dialog</command> in order to terminate the
+communication dialog.
+</para>
+<para>
+When you send <command>parted_server</command> an order to do some long
+operation (e.g. resize a file system) the user will be shown a progress bar.
+You may give a name to it by the function <command>name_progress_bar</command>.
+It may be used right before the command <command>open_dialog</command> and
+accepts only one argument – a template with type text that describes what is
+being done.
+</para>
+<para>
+The function <command>log</command> appends its arguments to the file
+<filename>/var/log/partman</filename>. This file is used as log-file also by
+<command>parted_server</command>.
+</para>
+</section>
+
+</chapter>
+
+<chapter id="ch5"><title>The commands of <command>parted_server</command></title>
+<para>
+You should be very careful when you communicate with the
+<command>parted_server</command>. If <command>parted_server</command> detects
+any error it will exit immediately. This is safer approach then to try to
+resolve somehow the error. However this also means that the user will not be
+shown any information about what happened and why the installer freezed. The
+log-file <filename>/var/log/partman</filename> can be used to see the reasons
+why <command>parted_server</command> exited.
+</para>
+<section id="s5.1"><title>Open a new device</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog OPEN <replaceable>device_name</replaceable>
+read_line status
+close_dialog
+case $status in
+ OK)
+ # The device has been opened successfully
+ ;;
+ failed)
+ # We wasn't able to open the device
+ ;;
+esac
+</screen>
+<para>
+Here <replaceable><literal>device_name</literal></replaceable> can be for
+example <filename>/dev/ide/host0/bus0/target0/lun0/disc</filename>.
+</para>
+</section>
+
+<section id="s5.2"><title>Close a device</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog CLOSE
+close_dialog
+</screen>
+<para>
+After this command you may not issue commands regarding the device of
+<replaceable><literal>device_directory</literal></replaceable>. This command
+does <emphasis role="strong">not</emphasis> invoke the command COMMIT.
+</para>
+</section>
+
+<section id="s5.3"><title>Does the partition exist on the disk?</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog VIRTUAL <replaceable>partition_id</replaceable>
+read_line virtuality
+close_dialog
+case $virtuality in
+ yes)
+ # the partition does not exist on the disk
+ # probably because it is newly created
+ ;;
+ no)
+ # the partition exists on the disk
+ ;;
+esac
+</screen>
+</section>
+
+<section id="s5.4"><title>Remember the partition table as unchanged</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog DISK_UNCHANGED
+close_dialog
+</screen>
+<para>
+After this command <command>parted_server</command> will know that the
+partition table in its onw internal data structures is the same as the
+partition table actualy existing on the device. The main purpose of this
+command is to be used for partition tables with type <literal>loop</literal>.
+</para>
+</section>
+
+<section id="s5.5"><title>Report whether the partition table is changed</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog IS_CHANGED
+read_line changed
+close_dialog
+case $changed in
+ yes)
+ # the partition table is changed
+ ;;
+ no)
+ # the partition table is not changed
+ ;;
+esac
+</screen>
+</section>
+
+<section id="s5.6"><title>Dump the partitions</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog DUMP
+close_dialog
+</screen>
+<para>
+This command prints in <filename>/var/log/partition_dump</filename> all the
+data regarding the device. It is used for debugging.
+</para>
+</section>
+
+<section id="s5.7"><title>Write partitioning to the disk</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog COMMIT
+close_dialog
+</screen>
+<para>
+This command transfers the partitions in the device of
+<replaceable><literal>device_directory</literal></replaceable> from the
+internal structures of <command>parted_server</command> to the disk.
+</para>
+</section>
+
+<section id="s5.8"><title>Undo the changes</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog UNDO
+close_dialog
+</screen>
+<para>
+This command destroys the internal data structures in
+<command>parted_server</command> for a device and then rereads them from the
+device.
+</para>
+</section>
+
+<section id="s5.9"><title>Get the partitions</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog PARTITIONS
+while { read_line num id size type fs path name; [ "$id" ]; }; do
+ # do something for this partition
+done
+close_dialog
+</screen>
+<para>
+The body of the loop is executed for every partition and free space. $num is
+the number of the partition (for example <filename>/dev/hda6</filename> has
+number 6). $id is the id of the partition. $size is the size of the partition
+(in bytes). If this is an active partition then $type is either `primary' or
+`logical'. If this is a free space then $type shows what partition can be
+created in it. In this case $type can be `primary', `logical', `pri/log' or
+`unusable'. $fs is `free' if this is a free space. Otherwise $fs is the type
+of the file system of this partition as known to
+<command>parted_server</command>. $path is a device name for the partition,
+for example <filename>/dev/ide/host0/bus0/target0/lun0/part6</filename>. $name
+is the name of the partition or the empty string if the partition table doesn't
+support partition names.
+</para>
+<para>
+Notice that in the loop-body you may not initiate another dialog with
+<command>parted_server</command>. If you need this you can use the following
+construction instead:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog PARTITIONS
+partitions=$(read_paragraph)
+close_dialog
+
+echo "$partitions" |
+while { read num id size type fs path name; [ "$id" ]; }; do
+ # do something for this partition
+done
+</screen>
+</section>
+
+<section id="s5.10"><title>Getting info about a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog PARTITION_INFO <replaceable>partition_id</replaceable>
+read_line num id size type fs path name
+close_dialog
+</screen>
+<para>
+Here <replaceable><literal>partition_id</literal></replaceable> is the id of
+the partition to get info. The meaning of the variables are the same as in the
+command PARTITIONS.
+</para>
+</section>
+
+<section id="s5.11"><title>Getting cylinder/head/sector geometry of a partition/free space</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog GET_CHS <replaceable>partition_id</replaceable>
+read_line start_cyl start_head start_sector end_cyl end_head end_sector
+close_dialog
+</screen>
+</section>
+
+<section id="s5.12"><title>Getting the supported partition table types</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog LABEL_TYPES
+supported=$(read_list)
+close_dialog
+</screen>
+<para>
+For the result of this command
+<replaceable><literal>device_directory</literal></replaceable> is irrelevant.
+Despite this <replaceable><literal>device_directory</literal></replaceable>
+must be a valid device directory.
+</para>
+<para>
+This command is used to read which types partition tables are supported by
+<command>parted_server</command> (i.e. by libparted). $supported is a
+comma-separated list of the supported types. At the time of writting the
+following types are supported: bsd, gpt, mac, dvh, msdos, pc98, sun and loop.
+</para>
+</section>
+
+<section id="s5.13"><title>Get the type of the disk label</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog GET_LABEL_TYPE
+read_line label_type
+close_dialog
+if [ "$label_type" = unknown ]; then
+ echo "The disk is unknown or it has no disk label
+ or the disk label is unknown"
+else
+ echo "The type of the disk label is:" "$label_type"
+fi
+</screen>
+<para>
+This command returns the type of the disk label (i.e. the partition table) of
+a disk. It can be used to check if there is a partition table (if not, then it
+is safe to create a new partition table or to use the entire disk for RAID,
+LVM, encrypted unit, etc).
+</para>
+</section>
+
+<section id="s5.14"><title>Create a new empty partition table</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog NEW_LABEL <replaceable>partition_table_type</replaceable>
+close_dialog
+</screen>
+<para>
+This command creates in the device a new empty partition table with type
+<replaceable><literal>partition_table_type</literal></replaceable>. (Of course
+it won't be written to the disk if you don't use the command COMMIT.)
+</para>
+</section>
+
+<section id="s5.15"><title>Getting the meaningful flags for a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog VALID_FLAGS <replaceable>partition_id</replaceable>
+meaningful_flags=$(read_list)
+close_dialog
+</screen>
+<para>
+$meaningful_flags is a comma-separated list of the flags that are meaningful
+for the partition with id
+<replaceable><literal>partition_id</literal></replaceable>.
+</para>
+<para>
+In order to check wether some particular flag xyz is meaningful you can use
+this code:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+xyz_is_meaningful=no
+open_dialog VALID_FLAGS <replaceable>partition_id</replaceable>
+while { read_line flag; [ "$flag" ]; }; do
+ if [ "$flag" = xyz ]; then
+ xyz_is_meaningful=yes
+ # you may not use break here
+ fi
+done
+close_dialog
+</screen>
+</section>
+
+<section id="s5.16"><title>Getting the active flags of a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog GET_FLAGS <replaceable>partition_id</replaceable>
+active_flags=$(read_list)
+close_dialog
+</screen>
+<para>
+$active_flags is a comma-separated list of the flags of the partition with id
+<replaceable><literal>partition_id</literal></replaceable> that are in state 1.
+This is a sublist of the list returned by the command VALID_FLAGS.
+</para>
+<para>
+In order to check if some partition is denoted as bootable you can use this
+code:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+is_bootable=no
+open_dialog GET_FLAGS <replaceable>partition_id</replaceable>
+while { read_line flag; [ "$flag" ]; }; do
+ if [ "$flag" = boot ]; then
+ is_bootable=yes
+ # you may not use break here
+ fi
+done
+close_dialog
+</screen>
+</section>
+
+<section id="s5.17"><title>Set the flags of a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog SET_FLAGS <replaceable>partition_id</replaceable>
+for flag in $all_flags_that_should_be_active; do
+ write_line $flag
+done
+write_line NO_MORE
+close_dialog
+</screen>
+<para>
+If you want to denote some partition as non-bootable you can use the following
+code:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog GET_FLAGS <replaceable>partition_id</replaceable>
+new_flags=$(
+ while { read_line flag; [ "$flag" ]; }; do
+ if [ "$flag" != boot ]; then
+ echo $flag
+ fi
+ done
+)
+close_dialog
+
+open_dialog SET_FLAGS $id
+write_line "$new_flags"
+write_line NO_MORE
+close_dialog
+</screen>
+</section>
+
+<section id="s5.18"><title>Check if partition names are supported</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog USES_NAMES
+read_line supported
+close_dialog
+case $supported in
+ yes)
+ # the partition table supports partition names
+ ;;
+ no)
+ # the partition table doesn't support partition names
+ ;;
+esac
+</screen>
+</section>
+
+<section id="s5.19"><title>Set the name of a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog SET_NAME <replaceable>partition_id</replaceable> <replaceable>new_name</replaceable>
+close_dialog
+</screen>
+<para>
+After this command the name of
+<replaceable><literal>partition_id</literal></replaceable> will be
+<replaceable><literal>new_name</literal></replaceable>. It is an error to use
+this command with a partition table that doesn't support partition names.
+</para>
+</section>
+
+<section id="s5.20"><title>Get the maximum number of primary partitions</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog GET_MAX_PRIMARY
+read_line primaries
+close_dialog
+logger "This disk may contain up to $primaries primary partitions"
+</screen>
+</section>
+
+<section id="s5.21"><title>Check if extended and logical partitions are supported</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog USES_EXTENDED
+read_line supported
+close_dialog
+case $supported in
+ yes)
+ # the partition table supports extended and logical partitions
+ ;;
+ no)
+ # the partition table doesn't support extended and logical partitions
+ ;;
+esac
+</screen>
+</section>
+
+<section id="s5.22"><title>Get the known to <command>parted_server</command> file systems</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog FILE_SYSTEM_TYPES
+known_filesystems=$(read_list)
+close_dialog
+</screen>
+<para>
+$known_filesystems is a comma-separated list of the file systems that are known
+to <command>parted_server</command>. You probably won't need to use this
+command.
+</para>
+</section>
+
+<section id="s5.23"><title>Try to detect the file system in a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog GET_FILE_SYSTEM <replaceable>partition_id</replaceable>
+read_line filesystem
+close_dialog
+if [ "$filesystem" = none ]; then
+ # no known file system is detected
+else
+ # a file system of type $filesystem is detected
+fi
+</screen>
+</section>
+
+<section id="s5.24"><title>Change the filesystem of a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog CHANGE_FILE_SYSTEM <replaceable>partition_id</replaceable> <replaceable>new_filesystem</replaceable>
+close_dialog
+</screen>
+<para>
+libparted assigns every partition some file system. This command can be used
+to change this file system. The file system assigned to the partition is not
+necessarily the same as the actual file system. Libparted uses it to determine
+automatically the type of the partition in some partition tables. For example
+with msdos partition tables the partitions with file system `ext2' receive type
+83. The partitions that are swap spaces receive type 82.
+</para>
+</section>
+
+<section id="s5.25"><title>Create a new partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog NEW_PARTITION $type $fs $freespace $position $length
+read_line num id size type fs path name
+close_dialog
+if [ "$id" ]; then
+ # the partition is successfully created
+else
+ # wasn't able to create the partition
+fi
+</screen>
+<para>
+$type is either primary or logical. $fs is the type of the file system to be
+assigned to the partition. $freespace is the id of some free space. $position
+is either `full', `beginning' or `end' and determines where in $freespace to
+create the new partition. If $position is not `full' then $length is the
+length that the new partition should have (in bytes).
+</para>
+<para>
+If the new file system is successfully created $num is tne number of the
+created partition (for example <filename>/dev/hda6</filename> has number 6).
+$id is the id of the new partition. $size is the size of the new partition.
+$size is approximately $length but not necessarily the same. $type and $fs
+don't change their values. $path is a device name, for example
+<filename>/dev/ide/host0/bus0/target0/lun0/part6</filename>. $name is the name
+of the new partition or an empty string if the partition table doesn't support
+partition names.
+</para>
+</section>
+
+<section id="s5.26"><title>Delete a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog DELETE_PARTITION <replaceable>partition_id</replaceable>
+close_dialog
+</screen>
+</section>
+
+<section id="s5.27"><title>Resize a partition</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+name_progress_bar <replaceable>some/debconf/template</replaceable>
+open_dialog RESIZE_PARTITION <replaceable>partition_id</replaceable> <replaceable>new_size</replaceable>
+read_line new_id
+close_dialog
+</screen>
+<para>
+This command resizes a partition. As usualy
+<replaceable><literal>new_size</literal></replaceable> is measured in bytes.
+$new_id is the new id that the partition receives. The resizing is not
+supported always. If it fails $new_id will be the same as
+<replaceable><literal>partition_id</literal></replaceable>.
+</para>
+<para>
+If the partition exists on the storage device and contains some file system,
+then the data in the partition will be preserved and the new partition table
+<emphasis>will be written on the storage device</emphasis>. When it is
+impossible to resize the file system, the partition will be left unresized.
+When the partition doesn't exist on the storage device, the new version of the
+partition table will not be written to it.
+</para>
+<para>
+This command doesn't move the start of the partition but only its end.
+</para>
+<para>
+The command <command>name_progress_bar</command> may be omitted. The debconf
+template must have type text. It will be used to give the user information of
+what is being done.
+</para>
+</section>
+
+<section id="s5.28"><title>Get resize range</title>
+<para>
+Synopsis:
+</para>
+<screen>
+cd <replaceable>device_directory</replaceable>
+open_dialog GET_RESIZE_RANGE <replaceable>partition_id</replaceable>
+read_line minimal_size current_size maximal_size
+close_dialog
+</screen>
+<para>
+This command returns the minimal and the maximal size that can be achieved by
+using the command RESIZE_PARTITION. $minimal_size, $current_size and
+$maximal_size are measured in bytes.
+</para>
+</section>
+
+</chapter>
+
+<chapter id="ch6"><title>Bugs and limitations</title>
+<para>
+All files and directories are assumed to not contain spaces in their names.
+</para>
+<para>
+If the partition table supports extended and logical partitions the user won't
+be shown free spaces whose size is less than one cylinder.
+</para>
+</chapter>
+
+
+</book>
+
diff --git a/doc/devel/partman/partman-doc.sgml b/doc/devel/partman/partman-doc.sgml
deleted file mode 100644
index bb19576e5..000000000
--- a/doc/devel/partman/partman-doc.sgml
+++ /dev/null
@@ -1,1507 +0,0 @@
-<!doctype debiandoc SYSTEM>
-
-<book>
-<title> Partition Management for the Debian Installer </title>
-<author>
- <name>Anton Zinoviev</name><email>anton@lml.bas.bg</email>
-</author>
-
-<copyright>
-<copyrightsummary> © 2003,2004,2007 Anton Zinoviev </copyrightsummary>
-
-<p> This manual is free software; you may redistribute it and/or
-modify it under the terms of the GNU General Public License as
-published by the Free Software Foundation; either version 2, or
-(at your option) any later version.
-
-<p> This is distributed in the hope that it will be useful, but
-<em>without any warranty</em>; without even the implied warranty of
-merchantability or fitness for a particular purpose. See the GNU
-General Public License for more details.
-
-<p> A copy of the GNU General Public License is available as
-<tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
-distribution or on the World Wide Web at the <url
-id="http://www.gnu.org/copyleft/gpl.html"; name="GNU website">. You can
-also obtain it by writing to the Free Software Foundation, Inc.,
-51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
-
-</copyright>
-
-<toc>
-
-<chapt> Introduction
-
-<p> There are many wishlist features that we might desire from any
-installer of GNU/Linux and that are related to partitioning:
-<list>
-<item> The partitioner should support different file systems. Some of
- them need more care than only libraries and suitable arguments for
- <prgn>mount</prgn>.
-
-<item> It should support not only regular partitions but also software
- RAID and LVM as well as encrypted file systems.
-
-<item> It should be able to partition disks automatically and allow
- the user to inspect and customise the automatic partitioning
- later.
-
-<item> It should be able to resize partitions and move their contents
-from one place to another.
-
-<item> The users should be protected from mistakes – by allowing
-them to undo their partitioning operations.
-
-<item> The partitioner should discover that there is already some
- installed GNU/Linux system and analyse its <prgn>fstab</prgn>,
- <prgn>passwd</prgn>, etc. in order to provide an automatic upgrade from
- the old already installed GNU/Linux system to the new one.
-</list>
-
-<p> One nice feature of the Debian installer is that it is modular.
- Its components are packaged in separate udebs and they can have
- relatively independent development process. This document describes
- how we can solve all mentioned tasks keeping the Debian installer as
- modular as it is now. Ideally in order to add some new feature only
- a few new udebs must be all that is needed – no changes in the
- existing udebs and no recompilation would be required.
-
-<p> The script <file>partman</file> from the package
-<package>partman-base</package> opens the main partitioning menu; it may
-look like this one:
-<example>
-+------------------+ [!!] Partition the storage devices +-----------------+
-| Partition, free space or device to be modified |
-| |
-| IDE1 master - Seagate U Series 40810 (40.0 GB) |
-| #3 primary 2.1 GB B F ext3 / |
-| pri/log 4.4 GB FREE SPACE |
-| #5 logical 3.6 GB |
-| #7 logical 10.0 GB F ext3 /usr |
-| #8 logical 19.9 GB K ext2 /home |
-| IDE2 master - Maxtor 6Y120L0 (122.9 GB) |
-| #7 logical 1.0 GB linux-swap |
-| logical 114.5 GB FREE SPACE |
-| #5 logical 5.5 GB reiserfs |
-| #6 logical 1.9 GB |
-| |
-| Undo changes to partitions |
-| Finish partitioning and write changes to disk |
-| |
-| <Go Back> <Continue> |
-| |
-+-------------------------------------------------------------------------+
-</example>
-
-<p> When the users choose some free space they are offered to create a
-new partition just like they are in <prgn>cfdisk</prgn>. When users
-choose a partition they are offered with a menu with various editing
-operations:
-
-<example>
-+------------------+ [!!] Partition the storage devices +-----------------+
-| Settings on the partition: |
-| |
-| Usage method: format the partition |
-| File system: ext3 |
-| Mount point: /var/mail |
-| Mount options: noatime,nodev,nosuid,noexec,usrquota |
-| Bootable flag: off |
-| Size: 995.2 MB |
-| |
-| Finished setting up partition |
-| Delete the partition |
-| |
-| <Go Back> <Continue> |
-| |
-+-------------------------------------------------------------------------+
-</example>
-
-<p> All udebs are allowed to add items to this menu as well as to
-several other menus. They can add new items in the list of devices
-such as software RAID and LVM devices, networked file systems,
-encrypted partitions, etc. The package
-<package>partman-partitioning</package> is responsible for pure
-partitioning operations such as creation of new partitions and
-deletion. The packages <package>partman-target</package> and
-<package>partman-basicmethods</package> are responsible for the items
-`Choose how this partition should be used' and `Choose a file system'.
-The package <package>partman-basicfilesystems</package> adds support
-for <tt>ext2</tt>, <tt>linux-swap</tt>, <tt>fat16</tt> and
-<tt>fat32</tt>. The package <package>partman-ext3</package> adds
-support for <tt>ext3</tt>.
-
-<chapt> Changes in partman since 2005
-
-<p> This chapter documents important changes in the sctructure of
-partman. It is provided as a test if you need to reread some of the
-sections in this document.
-
-<list>
-<item> New directory <prgn>check.d</prgn> with some of the scripts
-formerly in <prgn>finish.d</prgn>
-<item> New directory <prgn>display.d</prgn> with different methods to
-do the partitioning (manual, automatic, etc.)
-<item> New command GET_LABEL_TYPE in parted_server
-</list>
-
-<chapt> Package interrelations
-
-<sect id="basics"> Basics
-
-<p> The GNU Parted disk partitioning library provides high-level,
- architecture independent functions for operations such as creating,
- deleting, resizing and moving of partitions. Most of the functions of
- libparted work in a nondestructive way. The partition table is
- written in data structures and any change in the partition table
- happens only in these data structures rather than directly on the
- disk. This makes possible to implement partitioning tools based on
- <package>libparted</package> that support undoing of the editing
- operations.
-
-<p> However we have to solve two problems. The first is that we want
-to use as much as possible shell scripts rather than C programs. The
-second is that different programs have to operate with same instance
-of libparted structures. For example the user can use some tool for
-automatic partitioning, then correct or customise the automatic
-partitioning, perform some other arbitrary operations being still
-allowed to undo everything.
-
-<p> There is one obvious solution of these two problems – we
-keep the data structures of libparted in a daemon process and
-communicate with it in order to make changes in these data structures.
-This process is <file>/bin/parted_server</file> from the package
-<package>partman-base</package>.
-
-<p> The scripts from <file>/lib/partman/init.d/</file> are executed
- before all partitioning operations. They can be used to initialise
- the partitioning system. The scripts may be invoked more than once
- in which case they should behave properly. For example this
- directory can contain a script to discover the existing hard drives.
- If invoked for second time the script must either do nothing or
- check if there is some new kernel module giving access to new still
- undiscovered device.
-
- <p> Any udeb may install a script in this directory. For example
-the script <file>/lib/partman/init.d/30parted</file> from the package
-<package>partman-base</package> is responsible for running
-<prgn>parted_server</prgn>. Notice that the scripts are prefixed by a
-two-digit number. This number determines the order the scripts are
-executed. If any of the scripts exit with non-zero exit code the
-partitioning will be aborted. This means that in almost all cases
-these scripts must end with exit-code 0.
-
-<p> When the initialisation completes, the scripts from
-<file>/lib/partman/display.d</file> are executed. These scripts are
-supposed to make the actual partitioning interactively or
-non-interactively. The exit code <var>code</var> of these scripts is
-interpreted as follows:
-<taglist compact>
-<tag><var>code</var> = 0<item>The script did nothing, move to the next
-script in <prgn>display.d</prgn>.
-<tag>1 <= <var>code</var> <= 99<item>Restart the partitioning (move
-again to the first script in <prgn>display.d</prgn>).
-<tag>100 <= <var>code</var> <= 254<item>The script successfully
-partitioned the disks, do not execute the following scripts in
-<prgn>display.d</prgn>.
-<tag><var>code</var> = 255<item>Abort the partitioning.
-</taglist>
-
-<p> When the disks become ready, the scripts in
-<file>/lib/partman/check.d</file> are executed. They have to check if
-everything is OK to proceed with commiting the changes on the disks,
-mounting file systems, etc. For example the package
-<package>partman-target</package> installs there a script to check if
-there is a root file system. If a script in <prgn>check.d</prgn>
-exits with non-zero exit code then the scripts in
-<prgn>display.d</prgn > are executed again and as a result the user is
-allowed to fix the partitioning.
-
-<p> The directory <prgn>check.d</prgn> is remarkable with the fact
-that some of the scripts in it are installed by non-partman packages.
-The packages for the various bootloaders (lilo, grub, palo, etc.)
-install there scripts to ensure the partitioning scheme conforms to
-their requirements.
-
-<p> While the user is modifying the partitions this happens only in
- the memory of the computer and not in the edited devices. This is
- because almost all changes happen either in the data-structures of
- <prgn>parted_server</prgn> or in files in the installer's ram-disk.
- That's why we can provide the user with the option to undo
- everything. When the user chooses to undo the scripts in the
- directory <file>/lib/partman/undo.d/</file> are executed. Any udeb
- may install a script in this directory. For example the script
- <file>/lib/partman/undo.d/30parted</file> is responsible for
- restoring the contents of the data structures of
- <prgn>parted_server</prgn>. In most cases the scripts from
- <prgn>undo.d</prgn> must exit with exit-code 0. If any of the
- scripts exit with non-zero exit code the partitioning will be
- aborted.
-
-<p> In order to perform the editing operations on the storage devices
-(and in particular to transfer the partitions from the internal
-data-structures of <prgn>parted_server</prgn> to the hard disks) the
-scripts from the directory <file>/lib/partman/commit.d/</file> are
-executed. The order in which these scripts are executed is determined
-again by two-digit prefixes in the script names. Every script from
-<prgn>commit.d</prgn> is guaranteed that the scripts ordered before it
-have been already executed. However if any of the scripts exit with
-non-zero exit-code the execution of the scripts in
-<prgn>commit.d</prgn> will be stopped. In this case the partitioning
-will continue and the user is expected to fix the problem. If any
-script exits with non-zero exit code it is supposed to inform the user
-what went wrong using debconf.
-
-<p> There are two cases when the scripts from <prgn>commit.d</prgn>
-are executed. The first case is when the user wants to commit the
-changes to the disks but continue partitioning. The second case is
-when the partitioning ends. In the first case if none of the scripts
-fails the scripts from <prgn>init.d</prgn> will be also executed and
-the user will be returned to the partitioning dialog. In the second
-case the scripts from <prgn>finish.d</prgn> will be executed. In both
-cases if any of the scripts in <prgn>commit.d</prgn> fail the user
-will be returned immediately back to the partitioning dialog.
-
-<p> The scripts from <file>/lib/partman/finish.d/</file> are
-responsible for final tasks such as to mount partitions on
-<file>/target</file>, generate of <prgn>fstab</prgn>, stop
-<prgn>parted_server</prgn> etc.<footnote>What tasks will be performed
-depends on what udebs are unpacked. If the packages responsible for
-mounting partitions and creating fstab are not unpacked we have only a
-simple partitioner providing
-<package>partitioned-harddrives</package>. If they are unpacked they
-provide also <package>made-filesystems</package> and
-<package>mounted-partitions</package>.</footnote> If any of these
-scripts exit with non-zero exit-code the execution of the scripts
-will be stopped. If the exit-code was 1 then the user will be
-returned back to the partitioning dialog and is expected to correct
-the problem. If the exit-code was neither 0 nor 1 then the
-partitioning will be aborted.
-
-<p> For every hard disk in the system the script
-<file>/lib/partman/init.d/30parted</file> creates a subdirectory in
-<file>/var/lib/partman/devices/</file> and informs
-<prgn>parted_server</prgn> that the device is to be edited (`opens'
-the device). All udebs that provide storage device (software RAID,
-LVM, encrypted partitions) must do the same. This subdirectory must
-contain at least three files – <prgn>device</prgn>,
-<prgn>model</prgn> and <prgn>size</prgn>. The first contains the name
-of a device file (for example
-<file>/dev/ide/host0/bus0/target0/lun0/disc</file>). The second
-contains the name of the device (for example `Maxtor 6Y120L0'). The
-third contains the physical size of the storage device (in bytes, for
-example `122942324736'). <footnote>Please notice that udebs that
-provide support for storage `devices' that cannot be partitioned
-(such as networked file systems) should not create a subdirectory in
-<file>/var/lib/partman/devices</file> and certainly cannot provide
-the device to the management of <prgn>parted_server</prgn>.</footnote>
-The subdirectories of <file>/var/lib/partman/devices/</file> can but
-are not obligated to contain additional information. We call these
-subdirectories <em>device directories</em>.
-
-<p> Every partition in a device managed by <prgn>parted_server</prgn>
-is given a unique name having the form
-<var>first_byte</var>-<var>last_byte</var>. This name can be used to
-determine where the partition starts and where it
-ends.<footnote>Unlike one can suppose <prgn>parted_server</prgn>
-always measures sizes and places in bytes rather than in sectors.
-<var>Last_byte</var> is the number of the last byte of the last sector
-of the partition.</footnote> If the device directory contains a
-subdirectory named
-<prgn><var>first_byte</var>-<var>last_byte</var></prgn> then this
-subdirectory stores information about the partition. We call this
-subdirectory <em>directory of the partition</em>. We call the
-string<var>first_byte</var>-<var>last_byte</var> `<em>id</em>' of the
-partition.
-
-
-<sect id="menudirs"> Menu-directories
-
-<p> There are several menus involved in partitioning. In order to
-keep the Debian installer modular and extensible we want to allow
-every udeb to install items in these menus. Let us be more specific.
-When the users decide to format some existing partition we need a menu
-with an item for every supported file system. Obviously we don't want
-to hardwire the list of the supported file systems anywhere in our
-installer. If we want to add support to the installer say for XFS or
-UMSDOS file systems, only a few new udebs must be all that is needed.
-
-<p> In order to achieve this flexibility the package
- <package>partman-base</package> provides support for the so-called
- menu-directories. Every such directory contains files named
- <prgn>question</prgn> and <prgn>priority</prgn>. They contain the
- name of a Debconf template and the priority of the question
- correspondingly. The template must have exactly the following type
- and choices fields:
-<example>
-Type: select
-Choices-C: ${CHOICES}
-Choices: ${DESCRIPTIONS}
-</example>
-
-<p> All other files in the menu directory are subdirectories. Any
- udeb can install such a subdirectory in order to add items to the
- menu. For example the udebs for software RAID volumes can install in
- the menu of the editing operations an item to resize the chosen
- partition to have the same size as another. These subdirectories
- must contain two scripts – <prgn>choices</prgn> and
- <prgn>do_option</prgn>. The purpose of the first script is to print
- menu items. For every menu item <prgn>choices</prgn> must print a
- line having the form
-
-<example>
-<var>menu_item_id</var><TAB>The text for the user
-</example>
-
-<p> The script <prgn>choices</prgn> is allowed to print nothing. In
-this case no item for the menu is created. Here <tt><TAB></tt>
-is ASCII 9. The text `The text for the user' will be presented
-to the users. If they choose this particular menu item the script
-<prgn>do_option</prgn> will be invoked.
-
-<p> The script <prgn>choices</prgn> may be given some arguments
- depending on the particular menu-directory. The first argument
- given to <prgn>do_option</prgn> is always the
- <var><tt>menu_item_id</tt></var> of the chosen menu item. The rest
- of the arguments are the same as the arguments given to
- <prgn>choices</prgn>.
-
-<p> Let we take as an example the menu that the users see when they
- choose to edit some particular partition. The file
- <prgn>question</prgn> in the menu-directory for this menu contains
- the text <tt>partman/active_partition</tt>. This is the name of a
- Debconf-template with type `select' and description `Please choose
- what to do with this partition'. The package
- <package>partman-partitioning</package> installs in this
- menu-directory some subdirectories –
- <prgn>62change_name</prgn>, <prgn>65toggle_bootable</prgn> and
- <prgn>85delete</prgn>. The script
- <file>62change_name/choices</file> is given two arguments –
- the hard disk we edit and the id of the partition. It checks if the
- type of the partition table supports partition names in which case
- it prints the line
-<example>
-setname<TAB>Set the name of the partition
-</example>
-If the partition table doesn't support names, then this script prints
-nothing. When the user chooses to `set the name of the partition' the
-script <file>62change_name/do_option</file> is invoked. Its first
-argument is <tt>setname</tt> (this is the first part of the line
-printed by <prgn>choices</prgn>) and the other arguments are the same
-to the arguments given to the script <prgn>choices</prgn>. In our
-case the script <prgn>do_option</prgn> ignores its first argument.
-The script <prgn>do_option</prgn> can use its first argument in order
-to determine which menu item the user has chosen in cases when
-<prgn>choices</prgn> has printed several.
-
-<p> Notice that the names of the subdirectories in any menu-directory
-start with two digits. They are used to determine the order of the
-items in the menu.
-
-<sect> Partitioning
-
-<p> The partitioning starts with the menu of the menu-directory
-<file>/lib/partman/choose_partition</file>. This is the main
-partitioning menu. Every udeb is allowed to install new items in it.
-If the script <prgn>do_option</prgn> exits with exit-code 0 the user
-will be shown again the main partitioning menu. If the script exits
-with exit-code 100 this means that the partitioning should be
-finished. In this case the scripts from <prgn>commit.d</prgn> and
-<prgn>finish.d</prgn> will be executed as described in <ref
-id="basics">. If the script <prgn>do_option</prgn> exits with exit
-code 255 the partitioning will be aborted immediately.
-
-<p> The main partitioning menu always contains an item for every
-partitioned storage device, an item for every partition and an item
-for every free space.
-
-<p> If the user chooses a storage device the menu of the
-menu-directory <file>/lib/partman/storage_device</file> will be
-opened. The first argument given to <prgn>choices</prgn> is the
-device directory<footnote>We are not going to describe the arguments
-given to <prgn>do_option</prgn>. Look at <ref id="menudirs">.</footnote>.
-
-<p> If the user chooses a free space the menu-directory
-<file>/lib/partman/free_space</file> will be opened. The first
-argument given to <prgn>choices</prgn> is the device directory. The
-second argument is the id of the free space.
-
-<p> If the user chooses an active partition the menu-directory
-<file>/lib/partman/active_partition</file> will be opened. The first
-argument given to <prgn>choices</prgn> is the device directory. The
-second argument is the id of the chosen partition. If the script
-<prgn>do_option</prgn> exits with exit-code 0 the user will be shown
-again the menu <prgn>active_partition</prgn> for the same partition.
-If the script <prgn>do_option</prgn> exits with exit-code 100 or 255
-the user will be returned back to the main partitioning menu. This
-should happen when the id of the partition is invalidated, for example
-when the partition is deleted or resized.
-
-<p> In the main partitioning menu the partitions are presented by
-lines of this kind:
-<example>
-#8 primary 19.9 GB K ext2 /home
-</example>
-Notice that it is useless to indicate that the partition is primary if
-the type of the partition table is `mac' as this partition table
-doesn't support logical partitions. On the other hand this partition
-table supports partition names. We see that we need a flexible way to
-determine how the partitions are presented in the main partitioning
-menu.
-
-<p> The directory <file>/lib/partman/visual.d</file> contains scripts
-that print the parts of the partition line. For example the script
-<file>/lib/partman/visual.d/filesystem</file> prints strings like
-`ext3' or `FREE SPACE'. These scripts usualy start with the following
-cliche:
-
-<example>
-cd $1
-
-num=$2
-id=$3
-size=$4
-type=$5
-fs=$6
-path=$7
-shift; shift; shift; shift; shift; shift; shift
-name=$*
-</example>
-$1 is the device directory. $num is the number of the partition (for
-example <file>/dev/hda6</file> has number 6). $id is the id of the
-partition. $size is the size of the partition (in bytes). If this is
-an active partition then $type is either `primary' or `logical'. If
-this is a free space then $type shows what partition can be created in
-it and $type can be `primary', `logical', `pri/log' or `unusable'.
-$fs is `free' if this is a free space. Otherwise $fs is the type of
-the file system of this partition as known to
-<prgn>parted_server</prgn>. $path is a device name for the partition,
-for example <file>/dev/ide/host0/bus0/target0/lun0/part6</file>.
-$name is the name of the partition or the empty string if the
-partition table doesn't support partition names.
-
-<p> The script <file>/lib/partman/commit.d/30parted</file> transfers
-the partition tables from the internal structures of
-<prgn>parted_server</prgn> to the disks. The script
-<file>/lib/partman/finish.d/80parted</file> stops
-<prgn>parted_server</prgn>.
-
-<p> The package <package>partman-base</package> installs in
-<prgn>update.d</prgn> (see <ref id="update_partitions">) a script to
-ensure that for every partition that contains some file system there
-is a file <prgn>detected_filesystem</prgn> in the directory of the
-partition whose contents is the type of the detected file system as
-returned by <prgn>parted_server</prgn>.
-
-<sect> Setup <file>/target</file>
-
-<p> Without the package <package>partman-target</package> the packages
-<package>partman-base</package> and <package>partman-partitioning</package>
-provide only the regular partitioning operations. However if the
-package <package>partman-target</package> is also unpacked then the
-user will be provided with options to choose file systems for the
-partitions, specify wether they should be formatted and select mount
-points. The package <package>partman-target</package> adds to the
-menu directory <file>/lib/partman/active_partition</file> the item
-`Usage method:'. If the user chooses this item the menu directory
-<file>/lib/partman/choose_method</file> will be opened. The scripts
-<prgn>choices</prgn> from <prgn>choose_method</prgn> are given the
-device directory as first argument and the partition id as second
-argument.
-
-<p> The package <package>partman-basicmethods</package> adds in the
-menu of the menu directory <prgn>choose_method</prgn> three items: `Do
-not use the partition', `Format the partition' and `Keep and use the
-existing data in the partition' (the last only if some file system is
-detected). Other udebs can provide another methods to use partitions.
-
-<p> Every partition that is to be used somehow in the future Debian
-system should have a file named `method' in its directory (what is
-`directory of a partition' is described in <ref id="basics">). The
-scripts <prgn>do_option</prgn> of the menu directory
-<prgn>choose_method</prgn> manage the file <prgn>method</prgn>. It
-contains the name of the usage method chosen by the user. For
-example if the user chooses to `format the partition' the contents of
-this file will be `format' and if the user chooses to `keep and use
-the existing data' the contents of this file will be `keep'.
-Partitions that won't be used do not have a file <prgn>method</prgn>.
-
-<p>The udebs providing methods may provide also translatable names of
-the methods for the user interface using debconf templates named
-<prgn>partman/method_long/<var>some_method</var></prgn> and
-<prgn>partman/method_short/<var>some_method</var></prgn>. For example
-the package <package>partman-palo</package> providing method
-<prgn>palo</prgn> can provide also the following debconf templates:
-
-<example>
-Template: partman/method_long/palo
-Type: text
-_Description: Palo boot partition
-
-Template: partman/method_short/palo
-Type: text
-_Description: Palo
-</example>
-
-<p> Another job for the scripts <prgn>do_option</prgn> of the menu
-directory <prgn>choose_method</prgn> is to create or remove a file
-named <prgn>use_filesystem</prgn> in the directory of the partitions.
-This file is created when the usage method requires the partition to
-be used together with some file system. Otherwise it is removed.
-Example methods that are used together with a file system are `format
-the partition' and `keep and use the existing data'. Example methods
-that are not used together with a file system are `LVM physical
-volume' and `PALO boot partition'.
-
-<p> Finaly, the scripts <prgn>do_option</prgn> of the menu directory
-<prgn>choose_method</prgn> have to create or remove a file named
-`format' in the directory of the partitions. If the partition
-directory contains a file named <prgn>format</prgn> then it will be
-formatted. Otherwise it will not be formatted. For example if the user
-chooses to `format the partition' the script <prgn>do_option</prgn>
-will create a file <prgn>format</prgn>. If the user chooses to `keep
-and use the existing data' the file <prgn>format</prgn> will be
-removed if it exists.
-
-<p> The menu item `Choose a file system' in the menu directory
-<prgn>active_partition</prgn> is also provided by the package
-<package>partman-target</package>. If the user chooses it the menu
-<prgn>choose_filesystem</prgn> will be opened. This menu however is
-not produced using a menu directory.
-
-<p> Packages that provide support for some file system should install
-a script in the directory <file>/lib/partman/valid_filesystems</file>.
-The first argument given to this script is some device directory, the
-second argument is the id of some partition and the third argument is
-one of the strings `formatable' and `existing'. If it is `formatable'
-then the job of the script is to check if the specified partition can
-be formatted and used. If the third argument is `existing' then the
-job of the script is to check if the partition can be used without
-formatting. In either case if the partition can be used then the
-script should print a line with the identifier of the type of the file
-system.
-
-<p> Packages that provide support for some file systems use the
-directory <file>/lib/partman/parted_names</file> to define a mapping
-from the unique file system type identifiers to the names used by
-<prgn>parted_server</prgn>. Suppose for example that the package
-providing support for UMSDOS file system chooses the string `umsdos'
-as unique identifier for the file system. Then this package must
-install in this directory a file named <prgn>umsdos</prgn> whose
-contents is the string `fat16'. This means that
-<prgn>parted_server</prgn> will know UMSDOS file systems as being
-fat16 file systems.
-
-<p>The udebs providing file systems may provide also translatable
-names of the file systems for the user interface using debconf
-templates named
-<prgn>partman/filesystem_long/<var>some_filesystem</var></prgn> and
-<prgn>partman/filesystem_short/<var>some_filesystem</var></prgn>. For
-example the package <package>partman-ext3</package> providing file
-system with unique identifier <prgn>ext3</prgn> can provide also the
-following debconf templates:
-
-<example>
-Template: partman/filesystem_long/ext3
-Type: text
-_Description: Extended 3
-
-Template: partman/filesystem_short/ext3
-Type: text
-_Description: Ext3
-</example>
-
-<p> Most of the packages that provide support for a file system will
-have to add an item `Mount point:' to the menu
-<prgn>active_partition</prgn>. Of course this item should be shown
-only when the contents of the file <prgn>acting_filesystem</prgn> is
-appropriate. The mount point chosen by the user should be written in
-a file named <prgn>mountpoint</prgn> situated in the directory of the
-partition. If the user chooses not to mount this file system then the
-file <prgn>mountpoint</prgn> should be removed (if it exists).
-
-<p> In order to be able to mount file systems and generate fstab the
- directories <file>/lib/partman/fstab.d/</file> and
- <file>/lib/partman/mount.d/</file> are used. The scripts from
- <prgn>fstab.d</prgn> should print lines in a form similar to that of
- <file>/etc/fstab</file>:
-<example>
-<var>file_system</var> <var>mount_point</var> <var>type</var> <var>options</var> <var>dump</var> <var>pass</var>
-</example>
-
- The first field (<var><tt>file_system</tt></var>) is the name of a
- device that can be accessed by the installer. For example this can
- be <file>/dev/ide/host0/bus0/target0/lun0/part5</file> despite that
- in the future system this device will be named
- <file>/dev/hda5</file>. On the other hand the other five fields
- should look exactly the same way as in the <prgn>fstab</prgn> to be
- generated. For example <var><tt>options</tt></var> can contain
- options such as <tt>quota</tt> that are senseless for the installer.
-
-<p> The scripts from <prgn>mount.d</prgn> are used to mount file
- systems. A string having the same form as the lines output by the
- scripts from <prgn>fstab.d</prgn> should be given as first argument
- to any script from <prgn>mount.d</prgn>. Any script from
- <prgn>mount.d</prgn> checks if it can mount the requested file
- system. If it cannot then the script exits with some non-zero exit
- code. Otherwise the script must mount the file system in the proper
- place in the hierarchy over <file>/target</file>, print on its
- standard output a command that should be used in order to unmount
- the file system and exit with exit code 0.
-
-<p> The scripts in the directories <prgn>fstab.d</prgn> and
-<prgn>mount.d</prgn> are installed by the udebs that provide support
-for file systems.
-
-<p> Packages that provide support for file systems install in
-<prgn>commit.d</prgn> a script to format the partitions that the user
-has requested to be formatted. The package
-<package>partman-target</package> installs in <prgn>finish.d</prgn> a
-script to mount the partitions on <file>/target</file>. The packages
-that provide support for storage devices (RAID, LVM, etc.) install in
-<prgn>finish.d</prgn> a script to add in
-<file>/target/etc/fstab</file> the necessary lines.
-
-<p> The package <package>partman-target</package> installs in
-<prgn>update.d</prgn> (see <ref id="update_partitions">) a script to
-ensure that for every partition that is to be used there is a file
-<prgn>acting_filesystem</prgn> in the directory of the partition whose
-contents is the identifier of the type of file system under which the
-partition should be used.
-
-<chapt> <file>/lib/partman/lib/*</file>
-
-<p> Various scripts in partman make use of <em>function libraries</em>:
-separate files, mostly containing shell functions, that are sourced
-by scripts so they can make use of common functions and code duplication
-can be avoided.
-
-<p> The main function library is <file>base.sh</file>, provided by
-<package>partman-base</package>. This file is sourced by most scripts
-in partman as it defines a lot of useful variables and common functions.
-Some of these are documented in the remainder of this chapter.
-<footnote>The script <file>base.sh</file> has become somewhat too long and
-this probably makes its sourcing slow. Although some reorganization has
-already taken place, it could be a good idea to split it up further.</footnote>
-
-<p> Other packages provide more targeted function libraries. In most cases
-their scope and use can easily be determined from their name.
-
-<sect> Environment
-
-<p> The variables <tt>TAB</tt> and <tt>NL</tt> have values
-ASCII 9 and ASCII 10 correspondingly. They can be used as
-temporary values for the variable <tt>IFS</tt>. The function
-<prgn>restore_ifs</prgn> restores the variable <tt>IFS</tt> its
-original value.
-
-<p> The function library <prgn>base.sh</prgn> also contains simple
-reimplementations of <prgn>basename</prgn> and <prgn>dirname</prgn> so
-that busybox doesn't have to provide them.
-
-
-<sect> Menus
-
-<p> The function <prgn>debconf_select</prgn> is a high level function
- to ask user with a menu using a Debconf question with type `select'.
- Synopsis:
-<example>
-debconf_select <var>priority</var> <var>template</var> <var>choices</var> <var>default</var>
-</example>
-
-<p> The first argument is the debconf-priority of the question and the
- second is the name of the template to be used. The third argument
- is a newline-separated list of items for the menu. Each item has
- the form
-<example>
-<var>menu_item_id</var><TAB>The text for the user
-</example>
-
-<p> Here <tt><TAB></tt> is ASCII 9. The text `The text for
- the user' is the text of the menu item. If
- <var><tt>menu_item_id</tt></var> of some menu-item is identical with
- the fourth argument given to <prgn>debconf_select</prgn> then this
- menu-item will be default.
-
-<p> If the user cancels the question <prgn>debconf_select</prgn>
- returns with exit-code 255. Otherwise the value of the variable
- <tt>RET</tt> will be the <var><tt>menu_item_id</tt></var> of the
- chosen menu item. If the chosen menu item was chosen by the user
- then the exit-code is 0. If the item was chosen automatically (due
- to the debconf-priority or to some other reason) the exit-code is 1.
-
-<p> The function <prgn>debconf_select</prgn> doesn't care
- to <prgn>db_fset</prgn> <tt>$template</tt> <tt>seen</tt> <tt>false</tt>.
- The template must have exactly the following type and choices fields:
-<example>
-Type: select
-Choices-C: ${CHOICES}
-Choices: ${DESCRIPTIONS}
-</example>
-
-<p> The udebs that generate menus using menu-directories use the
- function <prgn>ask_user</prgn> instead of
- <prgn>debconf_select</prgn>. Synopsis:
-
-<example>
-ask_user <var>a_menu_directory</var> <var>additional_optional_arguments</var>...
-</example>
-
-<p> This function displays the menu for
- <tt><var>a_menu_directory</var></tt>. The first argument is a
- menu-directory (see <ref id="menudirs">). If the user cancels the
- dialog then <prgn>ask_user</prgn> returns with exit code 255.
- Otherwise it returns with the exit code of the script
- <prgn>do_option</prgn>.
-
-<p> If <prgn>ask_user</prgn> is called re-entrantly from within a
-<prgn>do_option</prgn> script, then the calling <prgn>do_option</prgn>
-script should typically be careful to handle or discard exit code 255
-itself (and sometimes other codes, depending on the protocol in force)
-to avoid a backup operation inadvertently backing up out of several
-nested menus at once.
-
-<p> The script <prgn>choices</prgn> is invoked with
-<var><tt>additional_optional_arguments</tt></var> as arguments. The
-first argument given to <prgn>do_option</prgn> is the
-<var><tt>menu_item_id</tt></var> of the chosen menu item and the
-other arguments are again
-<var><tt>additional_optional_arguments</tt></var>.
-
-<p> To set the default selected item in a menu-directory, use the function
- <prgn>menudir_default_choice</prgn>. Synopsis:
-
-<example>
-menudir_default_choice <var>a_menu_directory</var> <var>subdirectory</var> <var>menu_item_id</var>
-</example>
-
-<p> Where the <var><tt>subdirectory</tt></var> is the name of a
-subdirectory in the menu-directory with the leading sequence number
-stripped off and <var><tt>menu_item_id</tt></var> is the id of a
-menu-item printed by
-<file><var>a_menu_directory</var>/??<var>subdirectory</var>/choices</file>.
-The specified item is set as default not forever but only for the next
-invocation of <prgn>ask_user</prgn>. It is not an error to set as
-default non-existing item; in this case the first item in the menu
-will be default.
-
-<p> The function <prgn>partition_tree_choices</prgn> prints a sequence
-of lines in the form
-<example>
-<var>menu_item_id</var><TAB>The text for the user
-</example>
-– one for every storage device and one for every partition. The
-<var><tt>menu_item_id</tt></var> of the storage devices is their
-storage directory. The <var><tt>menu_item_id</tt></var> of the
-partitions has the form
-<var>storage_directory</var>//<var>partition_id</var>. The output of
-<prgn>partition_tree_choices</prgn> can be given as third argument to
-<prgn>debconf_select</prgn>.
-
-
-<sect> Long numbers
-
-<p> Notice that the sizes of most of the present storage devices
-are so large that we cannot measure them using 32-bit integers.
-Consequently we cannot use the usual shell arithmetic. The functions
-<prgn>longint_le</prgn>, <prgn>longint2human</prgn>,
-<prgn>human2longint</prgn> and <prgn>valid_human</prgn> exist in order
-to deal with such big numbers.
-
-<p> The function <prgn>longint_le</prgn> is used to compare two big
-numbers.
-<example>
-longint_le <var>number1</var> <var>number2</var>
-</example>
-returns with exit code 0 if the first number is less or equal to
-the second and returns 1 otherwise.
-
-<p> The function <prgn>longint2human</prgn> accepts in its first
-argument some number of bytes, converts it to something that is more
-meaningful for humans and outputs the result. For example
-<example>
-longint2human 1234567890
-</example>
-gives <tt>1.2 GB</tt>. Notice that this function rounds its
-argument.
-
-<p> The function <prgn>human2longint</prgn> is used for the opposite
-convertion:
-<example>
-human2longint 1.234Gb
-</example>
-gives <tt>1234000000</tt>.
-
-<p> The function <prgn>valid_human</prgn> returns with exit
-code 0 when its first argument is a string that is suitable to be
-given to <prgn>human2longint</prgn>. Otherwise it returns with exit
-code 1.
-
-<sect id="update_partitions"> Updating partition directories
-
-<p> Different components of the installer may need to get information
-about the partitions. They can communicate with
-<prgn>parted_server</prgn> in order to know the characteristics of the
-partition. However not everything can be known from
-<prgn>parted_server</prgn>. Imagine an udeb that provides the user
-with the option to upgrade some existing GNU/Linux installation. This
-udeb analyses the <prgn>fstab</prgn> and knows that some partition is
-used as <file>/home</file> and should not be formatted. This sort of
-information has nothing to do with <prgn>parted_server</prgn>. The
-udeb stores it in a subdirectory of the device directory named after
-the id of the partition.
-
-<p> But now a problem arises. Suppose that the user chooses to format
-some partition as ext2 and mount it on <file>/home</file>. The udebs
-responsible for formatting and mounting create the directories
-<prgn>filesystem</prgn> and <prgn>mountpoint</prgn> in the partition.
-What will happen if the users change their mind and decide to use the
-same partition as swap space? Swap spaces have no mount points and
-the file <prgn>mountpoint</prgn> should be removed. Who is
-responsible for removing it? The udeb that allows the user to choose a
-file system for the partition doesn't have to know that swap-spaces
-have no mount points, only the udeb that provides support for
-swap-spaces can know that the file <prgn>mountpoint</prgn> should be
-removed.
-
-<p> In order to solve this difficulty every script that makes changes
-to some partition should invoke the function
-<prgn>update_partition</prgn> from <prgn>base.sh</prgn>.
-Synopsis:
-<example>
-update_partition <var>device_directory</var> <var>partition_id</var>
-</example>
-In order to update the contents of the directory
-<file><var>device_directory</var>/<var>partition_id</var></file> the
-function <prgn>update_partition</prgn> executes the scripts from the
-directory <file>/lib/partman/update.d/</file>. Every udeb is allowed
-to install scripts in this directory. Their names are prefixed by
-two-digit numbers that control the order of the execution. The
-scripts from <prgn>update.d</prgn> are given several arguments. $1 is
-the <var>device_directory</var>. $2 is the number of the partition
-(<file>/dev/hda6</file> will have number 6). $3 is the id of the
-partition. $4 is the length of the partition (in bytes). $5 is the
-type of the partition, it can be either `primary' or `logical'. $6 is
-the type of the file system as known to <prgn>parted_server</prgn>, in
-most cases you should ignore this argument. $7 is the device name
-(for example <file>/dev/ide/host0/bus0/target0/lun0/part6</file>).
-"$8 $9 $10 $11 ..." is the name of the partition
-in partition tables that support partition names. Otherwise $8, $9,
-$10,... are not defined.
-
-<sect> Communication with <prgn>parted_server</prgn>
-
-<p> The package <package>partman-base</package> creates two FIFOs –
-<file>/var/lib/partman/infifo</file> and
-<file>/var/lib/partman/outfifo</file>. <prgn>Parted_server</prgn>
-reads instructions from <prgn>infifo</prgn> and responds by writting
-to <prgn>outfifo</prgn>. Consequently the clients write to
-<prgn>infifo</prgn> and read from <prgn>outfifo</prgn>. The function
-library <prgn>base.sh</prgn> contain several functions to make the
-communication with <prgn>parted_server</prgn> easier. Here we will
-omit the details, if you want to know the exact communication protocol
-please read how these functions are implemented.
-
-<p> The functions <prgn>open_infifo</prgn>, <prgn>close_infifo</prgn>,
-<prgn>open_outfifo</prgn> and <prgn>close_outfifo</prgn> are called
-without arguments. They open and close <prgn>infifo</prgn> and
-<prgn>outfifo</prgn> assigning them file descriptors 6 and 7
-correspondingly. You do not need to use these low-level functions.
-
-<p> The function <prgn>write_line</prgn> prints its arguments to
-<prgn>outfifo</prgn>.
-
-<p> The function <prgn>read_line</prgn> reads from <prgn>infifo</prgn>
-a line, splits it in fields according to <tt>$IFS</tt> and assigns
-these fields to variables whose names are given to
-<prgn>read_line</prgn> as arguments. For example
-<example>
-read_line x y z
-</example>
-reads a line from <prgn>infifo</prgn>, splits it and assigns the first
-field to the variable <tt>x</tt>, the second field to the variable
-<tt>y</tt> and the rest to the variable <tt>z</tt>. You see that
-<prgn>read_line</prgn> is used the same way as the shell operator
-<prgn>read</prgn>.
-
-<p> The function <prgn>read_paragraph</prgn> reads consequently lines
-from <prgn>infifo</prgn> until it reaches an empty line. It prints
-the read lines with the exception of the last empty line.
-
-<p> The function <prgn>read_list</prgn> reads lines the same way as
-the function <prgn>read_paragraph</prgn>. However the function
-<prgn>read_list</prgn> always prints only one line that is a
-comma-separated sequence of the lines read from <prgn>infifo</prgn>.
-If <prgn>read_paragraph</prgn> prints
-<example>
-This is the first line
-This is the second line
-This is the third line
-</example>
-<prgn>read_list</prgn> prints
-<example>
-This is the first line, This is the second line, This is the third line
-</example>
-
-<p> In order to initiate a communication dialog with
-<prgn>parted_server</prgn> you will use the function
-<prgn>open_dialog</prgn>. You will invoke it in the device directory
-of the device you want to issue command about. The first argument of
-<prgn>open_dialog</prgn> is a command for <prgn>parted_server</prgn>.
-The rest arguments are arguments for the command.
-
-<p> You use the function <prgn>close_dialog</prgn> in order to
-terminate the communication dialog.
-
-<p> When you send <prgn>parted_server</prgn> an order to do some
-long operation (e.g. resize a file system) the user will be shown a
-progress bar. You may give a name to it by the function
-<prgn>name_progress_bar</prgn>. It may be used right before the
-command <prgn>open_dialog</prgn> and accepts only one argument –
-a template with type text that describes what is being done.
-
-<p> The function <prgn>log</prgn> appends its arguments to the file
-<file>/var/log/partman</file>. This file is used as log-file also by
-<prgn>parted_server</prgn>.
-
-<chapt> The commands of <prgn>parted_server</prgn>
-
-<p> You should be very careful when you communicate with the
-<prgn>parted_server</prgn>. If <prgn>parted_server</prgn> detects any
-error it will exit immediately. This is safer approach then to try to
-resolve somehow the error. However this also means that the user will
-not be shown any information about what happened and why the installer
-freezed. The log-file <file>/var/log/partman</file> can be used to
-see the reasons why <prgn>parted_server</prgn> exited.
-
-<sect> Open a new device
-
-<p>Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog OPEN <var>device_name</var>
-read_line status
-close_dialog
-case $status in
- OK)
- # The device has been opened successfully
- ;;
- failed)
- # We wasn't able to open the device
- ;;
-esac
-</example>
-Here <var><tt>device_name</tt></var> can be for example
-<file>/dev/ide/host0/bus0/target0/lun0/disc</file>.
-
-<sect> Close a device
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog CLOSE
-close_dialog
-</example>
-
-After this command you may not issue commands regarding the device of
-<var><tt>device_directory</tt></var>. This command does
-<strong>not</strong> invoke the command COMMIT.
-
-<sect> Does the partition exist on the disk?
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog VIRTUAL <var>partition_id</var>
-read_line virtuality
-close_dialog
-case $virtuality in
- yes)
- # the partition does not exist on the disk
- # probably because it is newly created
- ;;
- no)
- # the partition exists on the disk
- ;;
-esac
-</example>
-
-<sect> Remember the partition table as unchanged
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog DISK_UNCHANGED
-close_dialog
-</example>
-
-After this command <prgn>parted_server</prgn> will know that the
-partition table in its onw internal data structures is the same as the
-partition table actualy existing on the device. The main purpose of
-this command is to be used for partition tables with type <tt>loop</tt>.
-
-<sect> Report whether the partition table is changed
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog IS_CHANGED
-read_line changed
-close_dialog
-case $changed in
- yes)
- # the partition table is changed
- ;;
- no)
- # the partition table is not changed
- ;;
-esac
-</example>
-
-
-<sect> Dump the partitions
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog DUMP
-close_dialog
-</example>
-
-<p> This command prints in <file>/var/log/partition_dump</file>
-all the data regarding the device. It is used for debugging.
-
-<sect> Write partitioning to the disk
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog COMMIT
-close_dialog
-</example>
-
-<p> This command transfers the partitions in the device of
-<var><tt>device_directory</tt></var> from the internal structures of
-<prgn>parted_server</prgn> to the disk.
-
-<sect> Undo the changes
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog UNDO
-close_dialog
-</example>
-
-<p> This command destroys the internal data structures in
-<prgn>parted_server</prgn> for a device and then rereads them from the
-device.
-
-<sect> Get the partitions
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog PARTITIONS
-while { read_line num id size type fs path name; [ "$id" ]; }; do
- # do something for this partition
-done
-close_dialog
-</example>
-
-<p> The body of the loop is executed for every partition and free
-space. $num is the number of the partition (for example
-<file>/dev/hda6</file> has number 6). $id is the id of the partition.
-$size is the size of the partition (in bytes). If this is an active
-partition then $type is either `primary' or `logical'. If this is a
-free space then $type shows what partition can be created in it. In
-this case $type can be `primary', `logical', `pri/log' or `unusable'.
-$fs is `free' if this is a free space. Otherwise $fs is the type of
-the file system of this partition as known to
-<prgn>parted_server</prgn>. $path is a device name for the partition,
-for example <file>/dev/ide/host0/bus0/target0/lun0/part6</file>.
-$name is the name of the partition or the empty string if the
-partition table doesn't support partition names.
-
-<p> Notice that in the loop-body you may not initiate another dialog
-with <prgn>parted_server</prgn>. If you need this you can use the
-following construction instead:
-<example>
-cd <var>device_directory</var>
-open_dialog PARTITIONS
-partitions=$(read_paragraph)
-close_dialog
-
-echo "$partitions" |
-while { read num id size type fs path name; [ "$id" ]; }; do
- # do something for this partition
-done
-</example>
-
-<sect> Getting info about a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog PARTITION_INFO <var>partition_id</var>
-read_line num id size type fs path name
-close_dialog
-</example>
-Here <var><tt>partition_id</tt></var> is the id of the partition to
-get info. The meaning of the variables are the same as in the command
-PARTITIONS.
-
-<sect> Getting cylinder/head/sector geometry of a partition/free space
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog GET_CHS <var>partition_id</var>
-read_line start_cyl start_head start_sector end_cyl end_head end_sector
-close_dialog
-</example>
-
-<sect> Getting the supported partition table types
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog LABEL_TYPES
-supported=$(read_list)
-close_dialog
-</example>
-For the result of this command <var><tt>device_directory</tt></var> is
-irrelevant. Despite this <var><tt>device_directory</tt></var> must be
-a valid device directory.
-
-<p> This command is used to read which types partition tables are
-supported by <prgn>parted_server</prgn> (i.e. by libparted).
-$supported is a comma-separated list of the supported types. At the
-time of writting the following types are supported: bsd, gpt, mac,
-dvh, msdos, pc98, sun and loop.
-
-<sect> Get the type of the disk label
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog GET_LABEL_TYPE
-read_line label_type
-close_dialog
-if [ "$label_type" = unknown ]; then
- echo "The disk is unknown or it has no disk label
- or the disk label is unknown"
-else
- echo "The type of the disk label is:" "$label_type"
-fi
-</example>
-This command returns the type of the disk label (i.e. the partition
-table) of a disk. It can be used to check if there is a partition
-table (if not, then it is safe to create a new partition table or to
-use the entire disk for RAID, LVM, encrypted unit, etc).
-
-<sect> Create a new empty partition table
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog NEW_LABEL <var>partition_table_type</var>
-close_dialog
-</example>
-This command creates in the device a new empty partition table with
-type <var><tt>partition_table_type</tt></var>. (Of course it won't be
-written to the disk if you don't use the command COMMIT.)
-
-<sect> Getting the meaningful flags for a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog VALID_FLAGS <var>partition_id</var>
-meaningful_flags=$(read_list)
-close_dialog
-</example>
-$meaningful_flags is a comma-separated list of the flags that are
-meaningful for the partition with id
-<var><tt>partition_id</tt></var>.
-
-<p> In order to check wether some particular flag xyz is meaningful
-you can use this code:
-<example>
-cd <var>device_directory</var>
-xyz_is_meaningful=no
-open_dialog VALID_FLAGS <var>partition_id</var>
-while { read_line flag; [ "$flag" ]; }; do
- if [ "$flag" = xyz ]; then
- xyz_is_meaningful=yes
- # you may not use break here
- fi
-done
-close_dialog
-</example>
-
-<sect> Getting the active flags of a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog GET_FLAGS <var>partition_id</var>
-active_flags=$(read_list)
-close_dialog
-</example>
-$active_flags is a comma-separated list of the flags of the partition
-with id <var><tt>partition_id</tt></var> that are in state 1. This is
-a sublist of the list returned by the command VALID_FLAGS.
-
-<p> In order to check if some partition is denoted as bootable you can
-use this code:
-<example>
-cd <var>device_directory</var>
-is_bootable=no
-open_dialog GET_FLAGS <var>partition_id</var>
-while { read_line flag; [ "$flag" ]; }; do
- if [ "$flag" = boot ]; then
- is_bootable=yes
- # you may not use break here
- fi
-done
-close_dialog
-</example>
-
-<sect> Set the flags of a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog SET_FLAGS <var>partition_id</var>
-for flag in $all_flags_that_should_be_active; do
- write_line $flag
-done
-write_line NO_MORE
-close_dialog
-</example>
-
-<p> If you want to denote some partition as non-bootable you can use
-the following code:
-
-<example>
-cd <var>device_directory</var>
-open_dialog GET_FLAGS <var>partition_id</var>
-new_flags=$(
- while { read_line flag; [ "$flag" ]; }; do
- if [ "$flag" != boot ]; then
- echo $flag
- fi
- done
-)
-close_dialog
-
-open_dialog SET_FLAGS $id
-write_line "$new_flags"
-write_line NO_MORE
-close_dialog
-</example>
-
-<sect> Check if partition names are supported
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog USES_NAMES
-read_line supported
-close_dialog
-case $supported in
- yes)
- # the partition table supports partition names
- ;;
- no)
- # the partition table doesn't support partition names
- ;;
-esac
-</example>
-
-<sect> Set the name of a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog SET_NAME <var>partition_id</var> <var>new_name</var>
-close_dialog
-</example>
-After this command the name of <var><tt>partition_id</tt></var> will
-be <var><tt>new_name</tt></var>. It is an error to use this command with
-a partition table that doesn't support partition names.
-
-<sect> Get the maximum number of primary partitions
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog GET_MAX_PRIMARY
-read_line primaries
-close_dialog
-logger "This disk may contain up to $primaries primary partitions"
-</example>
-
-<sect> Check if extended and logical partitions are supported
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog USES_EXTENDED
-read_line supported
-close_dialog
-case $supported in
- yes)
- # the partition table supports extended and logical partitions
- ;;
- no)
- # the partition table doesn't support extended and logical partitions
- ;;
-esac
-</example>
-
-<sect> Get the known to <prgn>parted_server</prgn> file systems
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog FILE_SYSTEM_TYPES
-known_filesystems=$(read_list)
-close_dialog
-</example>
-$known_filesystems is a comma-separated list of the file systems that
-are known to <prgn>parted_server</prgn>. You probably won't need to
-use this command.
-
-<sect> Try to detect the file system in a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog GET_FILE_SYSTEM <var>partition_id</var>
-read_line filesystem
-close_dialog
-if [ "$filesystem" = none ]; then
- # no known file system is detected
-else
- # a file system of type $filesystem is detected
-fi
-</example>
-
-<sect> Change the filesystem of a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog CHANGE_FILE_SYSTEM <var>partition_id</var> <var>new_filesystem</var>
-close_dialog
-</example>
-
-<p> libparted assigns every partition some file system. This command
-can be used to change this file system. The file system assigned to
-the partition is not necessarily the same as the actual file system.
-Libparted uses it to determine automatically the type of the partition
-in some partition tables. For example with msdos partition tables the
-partitions with file system `ext2' receive type 83. The partitions
-that are swap spaces receive type 82.
-
-<sect> Create a new partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog NEW_PARTITION $type $fs $freespace $position $length
-read_line num id size type fs path name
-close_dialog
-if [ "$id" ]; then
- # the partition is successfully created
-else
- # wasn't able to create the partition
-fi
-</example>
-$type is either primary or logical. $fs is the type of the file
-system to be assigned to the partition. $freespace is the id of some
-free space. $position is either `full', `beginning' or `end' and
-determines where in $freespace to create the new partition. If
-$position is not `full' then $length is the length that the new
-partition should have (in bytes).
-
-<p> If the new file system is successfully created $num is tne number
-of the created partition (for example <file>/dev/hda6</file> has
-number 6). $id is the id of the new partition. $size is the size of
-the new partition. $size is approximately $length but not necessarily
-the same. $type and $fs don't change their values. $path is a
-device name, for example
-<file>/dev/ide/host0/bus0/target0/lun0/part6</file>. $name is the
-name of the new partition or an empty string if the partition table
-doesn't support partition names.
-
-<sect> Delete a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog DELETE_PARTITION <var>partition_id</var>
-close_dialog
-</example>
-
-<sect> Resize a partition
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-name_progress_bar <var>some/debconf/template</var>
-open_dialog RESIZE_PARTITION <var>partition_id</var> <var>new_size</var>
-read_line new_id
-close_dialog
-</example>
-This command resizes a partition. As usualy
-<var><tt>new_size</tt></var> is measured in bytes. $new_id is the new
-id that the partition receives. The resizing is not supported always.
-If it fails $new_id will be the same as
-<var><tt>partition_id</tt></var>.
-
-<p> If the partition exists on the storage device and contains some
-file system, then the data in the partition will be preserved and the
-new partition table <em>will be written on the storage device</em>.
-When it is impossible to resize the file system, the partition will be
-left unresized. When the partition doesn't exist on the storage
-device, the new version of the partition table will not be written to
-it.
-
-<p> This command doesn't move the start of the partition but only its
-end.
-
-<p> The command <prgn>name_progress_bar</prgn> may be omitted. The
-debconf template must have type text. It will be used to give the user
-information of what is being done.
-
-<sect> Get resize range
-
-<p> Synopsis:
-<example>
-cd <var>device_directory</var>
-open_dialog GET_RESIZE_RANGE <var>partition_id</var>
-read_line minimal_size current_size maximal_size
-close_dialog
-</example>
-This command returns the minimal and the maximal size that can be
-achieved by using the command RESIZE_PARTITION. $minimal_size,
-$current_size and $maximal_size are measured in bytes.
-
-
-<chapt> Bugs and limitations
-
-<p> All files and directories are assumed to not contain spaces in
-their names.
-
-<p> If the partition table supports extended and logical partitions
-the user won't be shown free spaces whose size is less than one
-cylinder.
-
-</book>
-
-<!-- Local variables: -->
-<!-- coding: iso-8859-1 -->
-<!-- End: -->
diff --git a/doc/devel/partman/style-common.xsl b/doc/devel/partman/style-common.xsl
new file mode 120000
index 000000000..b6e795c56
--- /dev/null
+++ b/doc/devel/partman/style-common.xsl
@@ -0,0 +1 @@
+../internals/style-common.xsl
\ No newline at end of file
diff --git a/doc/devel/partman/style-html.xsl b/doc/devel/partman/style-html.xsl
new file mode 120000
index 000000000..592c2e736
--- /dev/null
+++ b/doc/devel/partman/style-html.xsl
@@ -0,0 +1 @@
+../internals/style-html.xsl
\ No newline at end of file
--
2.18.0
Reply to: