2 files changed, 618 insertions, 0 deletions
diff --git a/doc/kfloppy/Makefile.am b/doc/kfloppy/Makefile.am
new file mode 100644
index 0000000..085981d
--- /dev/null
+++ b/doc/kfloppy/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kfloppy/index.docbook b/doc/kfloppy/index.docbook
new file mode 100644
index 0000000..9915f80
--- /dev/null
+++ b/doc/kfloppy/index.docbook
@@ -0,0 +1,614 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kfloppy;">
+  <!ENTITY package "kdeutils">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY BSD "<trademark>BSD</trademark>">
+  <!ENTITY Minix "<trademark>Minix</trademark>">
+]>
+<!-- ### TODO Is BSD a trademark or a registrated trademark ? -->
+<!-- ### TODO Is Minix a trademark or a registrated trademark ? -->
+
+<!-- ### TODO Unify use of "disk", "floppy", "diskette", "floppy disk" (and "floppy drive") -->
+
+<book lang="&language;">
+<bookinfo>
+
+<title>The &kfloppy; Formatter Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Thad</firstname>
+<surname>McGinnis</surname>
+<affiliation><address><email>[email protected]</email>
+</address></affiliation> </author>
+
+<author>
+<firstname>Nicolas</firstname>
+<surname>Goutte</surname>
+<affiliation><address><email>[email protected]</email>
+</address></affiliation> </author>
+
+<othercredit role="developer">
+<firstname>Bernd</firstname>
+<othername>Johannes</othername>
+<surname>Wuebben</surname>
+<affiliation><address><email>[email protected]</email></address></affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>Chris</firstname>
+<surname>Howells</surname>
+<affiliation><address><email>[email protected]</email></address></affiliation>
+<contrib>Developer (User Interface re-design)</contrib>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>Adriaan</firstname>
+<surname>de Groot</surname>
+<affiliation><address><email>[email protected]</email></address></affiliation>
+<contrib>Developer (Add BSD support)</contrib>
+</othercredit>
+
+<othercredit role="reviewer">
+<firstname>Lauri</firstname>
+<surname>Watts</surname>
+<contrib>Reviewer</contrib>
+<affiliation><address><email>[email protected]</email></address></affiliation>
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2005-06-01</date>
+<releaseinfo>3.5</releaseinfo>
+
+<copyright>
+<year>2000</year>
+<holder>Thad McGinnis</holder>
+</copyright>
+
+<copyright>
+<year>2005</year>
+<holder>Nicolas Goutte</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<abstract><para>&kfloppy; Formatter is a utility that provides a
+straightforward graphical means to format 3.5" and 5.25" floppy
+disks.</para></abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kfloppy</keyword>
+<keyword>floppy</keyword>
+<keyword>format</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&kfloppy; Formatter is a utility that provides a straightforward
+graphical means to format 3.5" and 5.25" floppy disks. </para>
+
+<note><para>&kfloppy; depends on external programs and therefore
+currently works <emphasis>only</emphasis> with &Linux; and &BSD;. Depending if you are
+using &kfloppy; on &Linux; or on &BSD;, &kfloppy; has slightly different
+features.</para></note>
+
+<caution><para>Make sure that your floppy disk is <emphasis>not</emphasis>
+mounted.  &kfloppy; cannot format a mounted floppy disk.</para></caution>
+
+</chapter>
+
+<chapter id="usingkfloppy">
+<title>Using &kfloppy;</title>
+
+<para>Starting &kfloppy; opens a single window by which the user may
+choose appropriate settings and control the formatting process.  These
+options and controls are detailed below.</para>
+
+<caution><para>Make sure that your floppy disk is <emphasis>not</emphasis>
+mounted.  &kfloppy; cannot format a mounted floppy disk.</para></caution>
+
+<sect1 id="controlsettings">
+<title>Control Settings</title>
+
+<para>The settings are chosen by means of three drop down boxes located
+at the top left center of &kfloppy;.</para>
+
+<sect2 id="selectdrive">
+<title>Floppy Drive</title>
+
+<para>Clicking on the top drop down box, which is labeled
+<guilabel>Floppy drive:</guilabel>, offers the user the following
+two choices:</para>
+
+<itemizedlist>
+<listitem><para>Primary</para></listitem>
+<listitem><para>Secondary</para></listitem>
+</itemizedlist>
+
+<para>Clicking on the second drop down box from the top, which is labeled
+<guilabel>Size:</guilabel>, offers the user the following
+four choices:</para>
+
+<itemizedlist>
+<listitem><para>3.5" 1.44MB</para></listitem>
+<listitem><para>3.5" 720KB</para></listitem>
+<listitem><para>5.25" 1.2MB</para></listitem>
+<listitem><para>5.25" 360KB</para></listitem>
+</itemizedlist>
+
+<para>The &Linux; version of &kfloppy; has also a choice of size named:</para>
+
+<itemizedlist>
+<listitem><para>Auto-Detect</para></listitem>
+</itemizedlist>
+
+<!-- ### TODO: typical floppy disk of a PC has not the hardware to support
+Mac 800KB floppies at all, not only formatting. -->
+<note>
+<para>The 800KB disk format used by <hardware>&Mac; floppy drives</hardware> cannot be
+supported on <hardware>PC floppy drives</hardware> since they are not capable of formatting
+disks in that fashion.</para>
+</note>
+</sect2>
+
+<sect2 id="filesystems">
+<title><guilabel>File Systems</guilabel></title>
+
+<para>The third drop down box, labeled File System, offers the user the
+following choices, if they are applicable:</para>
+
+<variablelist>
+<varlistentry>
+<term>Dos</term>
+<listitem>
+<para>This selection will have &kfloppy; place the MS-DOS/&Windows; type
+of file system on the diskette.  The user will most likely want to
+choose this system if she or he will be using the diskette with those
+operating systems as they do not recognize other system types.
+(This is supported for &Linux; and &BSD;.)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry> 
+<term>ext2</term>
+<listitem>
+<para>This selection will have &kfloppy; place the type of file system
+on the diskette which is most commonly used with &Linux;, however
+seldomly on floppy disks.
+(This is supported for &Linux; and &BSD;.)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>UFS</term>
+<listitem>
+<para>This selection will have &kfloppy; place the type of file system
+on the diskette which is most commonly used with <trademark class="registered">FreeBSD</trademark>.  The user will
+likely want to choose this system if he or she will only be using the
+floppy disk with <trademark class="registered">FreeBSD</trademark>.
+(This is supported for &BSD; only.)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Minix</term>
+<listitem>
+<para>This selection will have &kfloppy; place the type of file system
+on the diskette which often used on floppy disks used with &Linux;,
+(This is supported for &Linux; only.)</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+</sect1>
+
+<sect1 id="formatting-options">
+<title>Formatting Options</title>
+<para>Within the outline of a box in the left center of &kfloppy; the user
+may find a set of five formatting options.  The top two are a pair of radio
+buttons.</para> <note><para>This term (radio buttons) indicates a set of options among
+which only one can be selected - in the same way that only one preset
+channel selection may be set on a car radio.</para></note><para>The
+bottom two options are for labeling the diskette.  All are explained
+below:</para>
+
+<sect2>
+<title>Formatting Method</title>
+<para>&kfloppy; can format a disk in the following two ways:</para>
+<para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Quick Format</guilabel></term>
+<listitem>
+<para>This simply puts the new file system on the disk.</para>
+<warning><para>All data on the disk will be lost, even if the data itself will not erased.</para></warning>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Zero out and quick format</guilabel></term>
+<listitem>
+<para>This format first puts zeros on the disk and then creates the new file system.</para>
+<warning><para>All data on the disk will be erased.</para></warning>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Full Format</guilabel></term>
+<listitem>
+<para>A full format reallocates the tracks and sectors, puts the selected
+file system on the disk, and then verifies the format, blocking out any bad
+sectors it finds.</para>
+<warning><para>All data on the disk will be erased.</para></warning>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+</sect2>
+
+<sect2>
+<title>Verify Integrity</title>
+
+<para>This tells &kfloppy; to check that the formatting was correctly
+written to the floppy.  This allows bad sectors to be identified.
+</para>
+
+<note><para>If bad sectors a found during the verify phase of a Full Format,
+the formatting is aborted and the file system is not written!
+</para></note>
+
+</sect2>
+
+<sect2>
+<title>Volume Label</title>
+
+<para>The bottom two features allow the user to add (or change) a
+label to the diskette.  If the <guilabel>Volume label:</guilabel> check
+box is selected then the user can enter a name (label) for the
+diskette that is to be formatted in the text box located immediately
+below.  When the diskette is subsequently formatted the label will be
+written to the diskette.</para>
+
+<note><para>Due to a limitation of the DOS file system, a label can only be
+at most 11 characters long. For simplification, &kfloppy; assumes that
+this limit is true for all file systems.</para></note>
+
+<note><para>The file system &Minix; cannot have any volume label. In this
+case, &kfloppy; will ignore the volume label.</para></note>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="buttons">
+<title>The Buttons</title>
+<para>There are three buttons located vertically along the right side of
+&kfloppy;. </para>
+
+<variablelist>
+<varlistentry>
+<term><guibutton>Format</guibutton></term>
+<listitem>
+<para>This button
+initiates the formatting process.  Once the user is sure that all the
+settings are correct he or she may begin the process by clicking on
+this button.
+There will be a change in the two long rectangular boxes
+that span the bottom of &kfloppy;.</para>
+
+<para>The upper box is a status indicator that gives information about the
+process underway, especially the error encountered during the processing.</para>
+
+<para>The lower box is a progress bar.  This displays both graphically
+and numerically the progress of first the formatting and then the
+verification.  Before starting it appears to be empty - showing only
+the figure 0% in the center.  As each process
+takes place the progress is tracked graphically as the box fills from
+left to right.  At the same time the number in the center will
+increase reflecting the precise percentage of the process that has
+been completed.</para>
+
+<note><para>As &kfloppy; uses external programs to format the floppy disk,
+it has to rely on these programs to give the right information for
+being able to display the progress bar. Unfortunately, this is not the
+case. Especially, the programs writing the file systems do not return
+enough data, so that the progress bar will remain at 0%.</para></note>
+
+<important>
+<para>Make sure that your floppy disk is <emphasis>not</emphasis> mounted.
+&kfloppy; cannot format a mounted floppy disk.</para>
+</important>
+
+<note><para>&kfloppy; does <emphasis>not</emphasis> unmount the
+floppy by itself, as this could mean that the user may overwrite a floppy
+disk with important data on it.</para></note>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Help</guibutton></term>
+<listitem>
+<para>This invokes the &kde; help system starting at the &kfloppy; help pages
+(this document).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Report Bug</guibutton></term>
+<listitem>
+<para>Report a problem to the &kde; team.</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>About KFloppy</guibutton></term>
+<listitem>
+<para>This displays version and author information of &kfloppy;.</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>About KDE</guibutton></term>
+<listitem>
+<para>This displays version and author information of KDE.</para>
+</listitem> 
+</varlistentry>
+
+
+<varlistentry>
+<term><guibutton>Quit</guibutton></term>
+<listitem>
+<para>Clicking on this button will close &kfloppy;.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+</chapter>
+
+<chapter id="command-line">
+<title>Command line options</title>
+
+<para>Though &kfloppy; may most often be started from the &kde; program menu,
+or a desktop icon, it can also be opened at the command line prompt of a
+terminal window.  There are a few options that are available when doing
+this.  They are:</para> 
+
+<variablelist>
+<varlistentry>
+<term><command>kfloppy <option>--help</option></command></term>
+<listitem><para>This lists the most basic options available at the command
+line.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>kfloppy <option>--help-qt</option></command></term>
+<listitem><para>This lists the options available for changing the way
+&kfloppy; interacts with &Qt;.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry> 
+<term><command>kfloppy <option>--help-kde</option></command></term>
+<listitem>
+<para>This lists the options available for changing the way &kfloppy;
+interacts with KDE.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>kfloppy <option>--help-all</option></command></term>
+<listitem>
+<para>This lists all of the command line options.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>kfloppy <option>--author</option></command></term>
+<listitem>
+<para>Lists &kfloppy;'s author in the terminal window</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>kfloppy <option>--version</option></command></term>
+<listitem>
+<para>Lists version information for &Qt;, &kde;, and &kfloppy;. Also available
+through <command>kfloppy <option>-V</option></command> </para>
+</listitem>
+</varlistentry>
+</variablelist> 
+
+</chapter> 
+
+<chapter id="credits">
+<title>Credits and Licenses</title>
+
+<!-- ### TODO: verify the copyright dates -->
+<!-- ### TODO: make the copyright list prettier -->
+<para>&kfloppy; Formatter Program Copyright 1997 - 2000 Bernd Johannes Wuebben
+<email>[email protected]</email></para>
+
+<para>&kfloppy; Formatter Program Copyright 2002 Adriaan de Groot
+<email>[email protected]</email></para>
+
+<para>&kfloppy; Formatter Program Copyright 2004, 2005 Nicolas Goutte
+<email>[email protected]</email></para>
+
+<para>Documentation Copyright 2000 by Thad McGinnis
+<email>[email protected]</email>.</para>
+
+<para>Documentation Copyright 2005 by Nicolas Goutte
+<email>[email protected]</email>.</para>
+
+<para>This version of the &kfloppy; Handbook is based on the original by
+David Rugge <email>[email protected]</email></para>
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<appendix id="neededprogs">
+<title>Needed External Programs</title>
+
+<para>As already written earlier in this handbook, &kfloppy; works
+with the help of external programs to do the different formatting tasks.</para>
+
+<note><para>If one of the programs is missing, &kfloppy; tries to work nevertheless.
+However the corresponding option will not be available.</para></note>
+
+<variablelist>
+<varlistentry>
+<term><command>fdformat</command></term>
+<listitem><para>This program is needed for low-level formatting,
+on &Linux; and on &BSD;. If it is missing,
+<guilabel>Full format</guilabel> will be disabled.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>dd</command></term>
+<listitem><para>This program is needed for zeroing-out,
+on &Linux; and on &BSD;. If it is missing,
+<guilabel>Zero out and quick format</guilabel> will be disabled.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>mkdosfs</command></term>
+<listitem><para>This program is needed for DOS formatting,
+on &Linux;.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>newfs_msdos</command></term>
+<listitem><para>This program is needed for DOS formatting,
+on &BSD;.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>newfs</command></term>
+<listitem><para>This program is needed for UFS formatting,
+on &BSD;.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>mke2fs</command></term>
+<listitem><para>This program is needed for ext2 formatting,
+on &Linux; and on &BSD;.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>mkfs.minix</command></term>
+<listitem><para>This program is needed for &Minix; formatting,
+on &Linux;.
+</para></listitem>
+</varlistentry>
+</variablelist>
+
+</appendix>
+<appendix id="usergivendevices">
+<title>User-Given Devices</title>
+
+<sect1 id="ugdintro">
+<title>Introduction</title>
+
+<para>"User Given Devices" is the work title of a still experimental feature of
+&kfloppy;. It allows the user to give a device name and to use it nearly
+as if it was a <hardware>floppy drive</hardware>.</para>
+
+<para>This feature is mainly intended as a work-around for users having
+<hardware>USB floppy drives</hardware> of any kind
+(including <trademark>ZIP</trademark> disk drives) or any other non-legacy
+<hardware>floppy drives</hardware>.</para>
+
+<note><para>Unfortunately at the time of writing this documentation, the feature
+is not very user friendly, as it does not offer any help to the user on how
+a device is called and &kfloppy; does not even remember the device name from
+call to call. (This is partially a security, as the device of the
+<hardware>floppy drive</hardware> might change between reboots.)</para></note>
+
+<note><para>As this feature was developed under &Linux;, the &BSD; version
+of &kfloppy; offers less choices than &kfloppy; under &Linux;.</para></note>
+
+</sect1>
+
+<sect1 id="ugdmain">
+<title>Using It</title>
+
+<!-- Note to reviewers: "PRimary" and "Secondary" are the default items in the combobox -->
+<para>Using "User Given Devices" is quite simple, you just need to enter
+a device name, for example <replaceable>/dev/sdz4</replaceable>
+in the <guilabel>Floppy drive:</guilabel> combobox instead of
+selecting Primary or Secondary.</para>
+
+<note>
+<para>You need to enter the <filename class="directory">/dev/</filename>
+part of the device for two reasons:</para>
+<itemizedlist>
+<listitem>
+<para>It is how &kfloppy; recognizes the "User Given Devices" mode.</para>
+</listitem>
+<listitem>
+<para>It is a security, to avoid that the user writes anything in the combobox
+that is by change a device name.</para>
+</listitem>
+</itemizedlist>
+</note>
+
+<para>Unfortunately, using any device instead of a floppy device has a few
+consequences. The major one is that <guilabel>Full Format</guilabel> cannot be
+selected anymore. Doing so will result in a error message box when trying to
+start the format. However you can use <guilabel>Zero out and quick format</guilabel>
+instead. It will not format the device, just zeroing it out, but in practice it is
+nearly the same; especially all data on the device will be erased.</para>
+
+<warning><para>Be careful when entering the device name. &kfloppy; will pass
+the device name as is to the external programs. Especially it does not check
+(and the external programs do not check either) if the device is a
+<hardware>floppy drive</hardware> device. If you give your any of your main
+disk partitions as device, it will be accepted. (If the partition is mounted
+or if you cannot write on this device, you
+will probably get an error message nevertheless, avoiding the worst.)</para></warning>
+
+<note><para>Even if you can specify a floppy device like
+<filename>/dev/fd0u2880</filename>, &kfloppy; will refuse to make a 
+<guilabel>Full Format</guilabel> on it.</para></note>
+
+<para>On &Linux;, you can select any file system that you want. On &BSD;,
+only UFS is currently supported (and not tested at time of writing this
+documentation).</para>
+
+<para>When you are ready to format, click on the <guibutton>Format</guibutton>
+button as usual. You will get a message box asking you to verify the device name.
+</para>
+
+<warning><para>This is the last chance to check the device name before formating.
+After it, it is too late.</para></warning>
+
+</sect1>
+
+</appendix>
+
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+// vim:ts=2:sw=2:tw=78:noet
+-->