diff options
Diffstat (limited to 'doc/kfloppy/index.docbook')
| -rw-r--r-- | doc/kfloppy/index.docbook | 614 |
1 files changed, 614 insertions, 0 deletions
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 +--> |