Warning, /utilities/kfloppy/doc/index.docbook is written in an unsupported language. File is not indexed.

 <?xml version="1.0" ?>
 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.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 id="kfloppy" lang="&language;">
 <bookinfo>
 
 <title>The &kfloppy; Formatter Handbook</title>
 
 <authorgroup>
 <author>
 <firstname>Thad</firstname>
 <surname>McGinnis</surname>
 <affiliation><address>&Thad.McGinnis.mail;
 </address></affiliation> </author>
 
 <author>
 <firstname>Nicolas</firstname>
 <surname>Goutte</surname>
 <affiliation><address>&Nicolas.Goutte.mail;
 </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>&Chris.Howells.mail;</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="developer">
 <firstname>Wolfgang</firstname>
 <surname>Bauer</surname>
 <affiliation><address><email>wbauer@tmo.at</email></address></affiliation>
 <contrib>Developer (Port to KF5)</contrib>
 </othercredit>
 
 <othercredit role="reviewer">
 <firstname>Lauri</firstname>
 <surname>Watts</surname>
 <contrib>Reviewer</contrib>
 <affiliation><address>&Lauri.Watts.mail;</address></affiliation>
 </othercredit>
 
 <!-- TRANS:ROLES_OF_TRANSLATORS -->
 </authorgroup>
 
 <date>2016-03-23</date>
 <releaseinfo>5.0 (Applications 16.04)</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>File Systems</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 be 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 are 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 a popup menu with actions to open this handbook,
 report a bug, switch the application language and display author and version of
 &kfloppy; and &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 options available at the command
 line.</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>--license</option></command></term>
 <listitem>
 <para>Shows license information for &kfloppy; in the terminal window</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><command>kfloppy <option>--version</option></command></term>
 <listitem>
 <para>Lists version information for &kfloppy;. Also available
 through <command>kfloppy <option>-v</option></command> </para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><command>kfloppy <option><replaceable>device</replaceable></option></command></term>
 <listitem><para>Device to format.</para>
 <para>This will directly format the given device using the saved settings.
 Only supported at the moment are /dev/fd0 and /dev/fd1.</para></listitem>
 </varlistentry>
 </variablelist> 
 
 </chapter> 
 
 <chapter id="credits">
 <title>Credits and License</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;
 &Nicolas.Goutte.mail;</para>
 
 <para>&kfloppy; Formatter Program Copyright 2015, 2016 Wolfgang Bauer
 <email>wbauer@tmo.at</email></para>
 
 <para>Documentation Copyright 2000 by &Thad.McGinnis;
 &Thad.McGinnis.mail;.</para>
 
 <para>This version of the &kfloppy; Handbook is based on the original by
 &David.Rugge; <email>davidrugge@mindspring.com</email></para>
 
 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
 &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 chance 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
 -->