tdeutils/doc/kfloppy/index.docbook

<?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 "tdeutils">
  <!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>ctmcginnis@compuserve.com</email>
</address></affiliation> </author>

<author>
<firstname>Nicolas</firstname>
<surname>Goutte</surname>
<affiliation><address><email>goutte@kde.org</email>
</address></affiliation> </author>

<othercredit role="developer">
<firstname>Bernd</firstname>
<othername>Johannes</othername>
<surname>Wuebben</surname>
<affiliation><address><email>wuebben@math.cornell.edu</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="developer">
<firstname>Chris</firstname>
<surname>Howells</surname>
<affiliation><address><email>howells@kde.org</email></address></affiliation>
<contrib>Developer (User Interface re-design)</contrib>
</othercredit>

<othercredit role="developer">
<firstname>Adriaan</firstname>
<surname>de Groot</surname>
<affiliation><address><email>groot@kde.org</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>lauri@kde.org</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>wuebben@math.cornell.edu</email></para>

<para>&kfloppy; Formatter Program Copyright 2002 Adriaan de Groot
<email>groot@kde.org</email></para>

<para>&kfloppy; Formatter Program Copyright 2004, 2005 Nicolas Goutte
<email>goutte@kde.org</email></para>

<para>Documentation Copyright 2000 by Thad McGinnis
<email>ctmcginnis@compuserve.com</email>.</para>

<para>Documentation Copyright 2005 by Nicolas Goutte
<email>goutte@kde.org</email>.</para>

<para>This version of the &kfloppy; Handbook is based on the original by
David Rugge <email>davidrugge@mindspring.com</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>