Introduction.xml.in

<?xml version="1.0" encoding="utf-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xl="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xml:id="VDG-Introduction"
         version="5.1">

  <title>Introduction</title>

  <section xml:id="VDG-Introduction-Introduction">
    <title>Introduction</title>

    <?dbhtml-include href="analytics.html"?>

    <para>
      I was motivated to write this book because I felt the quality
      of the information regarding commonly used functionality in
      virtual disk operation was lacking certain specific clear
      examples. The information that is available is not contained
      in a central location. Some concepts of the qemu system aren't
      covered at all. FAQs lead on to having an answer to a
      particular query, but many lead you to off site resources,
      some of which are no longer available on the Internet.
    </para>

    <para>
      What I hope to provide is a book which will demonstrate the
      core concepts of virtual disk management. This book will
      concern itself primarily with the <command>qemu-img</command>
      tool and common GNU/Linux disk utility tools like
      <command>fdisk</command>, <command>parted</command>, and
      <command>resize2fs</command>. Most importantly to me, in the
      case of non-trivial examples, I hope to identify what the
      relevant technical concepts are and how they work up to the
      final result of each example.
    </para>
  </section>

  <section xml:id="VDG-Introduction-Conventions">
    <title>Typographical Conventions</title>

    <para>
      The following describes the typographical conventions used
      throughout this book.
    </para>

    <variablelist>
      <varlistentry>
        <term>References</term>
        <listitem>
          <para>
            References to other sections will look like this: <xref
            linkend="VDG-Troubleshooting"/>. The format is:
            <emphasis>Chapter/section title</emphasis> followed by the
            page number in [brackets].
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Footnotes</term>
        <listitem>
          <para>
            References to footnotes<footnote><para>Hello! I am a
            footnote.</para></footnote> appear as small superscripted
            numbers flowing inline with the current discussion.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Terminology &amp; Emphasis</term>
        <listitem>
          <para>
            The introduction of a new or alternative term, as well as
            phrases which have been given emphasis, are formatted in
            italics:
            <itemizedlist>
              <listitem>
                <para>The disk image has been <firstterm>sparsified</firstterm></para>
              </listitem>
              <listitem>
                <para>You should <emphasis>always</emphasis> wear clean socks</para>
              </listitem>
            </itemizedlist>
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Commands &amp; Options</term>
        <listitem>
          <para>
            The name of commands are formatted in bold, an option you
            would give to a command is formatted in a monospaced
            sequence, for example: give the <option>-ltrsh</option> options
            to the <command>ls</command> command.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
      <term>Filesystem Paths</term>
      <listitem>
        <para>
          Names or paths to files, directories, and devices on the
          filesystem are formatted in a monospaced sequence:
          <filename class="directory">/dev/loop0p1</filename>
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Examples</term>
      <listitem>
        <para>
          Examples are formatted in a gray box with a title bar
          which provides the example number and title.
        </para>
        <example>
          <title>An example of examples</title>
          <screen>[~/vdg] 18:38:17  (master)
$ cat /etc/redhat-release
Fedora release 19 (Schrödinger’s Cat)</screen>
        </example>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Notes, Warnings, and Other Important Information</term>
      <listitem>
        <note>
          <para>
            A note will provide additional information relevant to
            the current discussion.
          </para>
        </note>
        <important>
          <para>
            Warnings and other important information which you
            should know before executing any commands will appear in
            an admonition such as this.
          </para>
        </important>
      </listitem>
    </varlistentry>
    </variablelist>
  </section>

  <section xml:id="VDG-Introduction-Units">
    <title>Units &amp; Prefixes</title>

    <para>
      Throughout this book you will see file sizes specified with an
      assortment of units. For example: 42 kB, 42 Mb, 42 GiB, 42 G, 42 GiB.
    </para>

    <para>
      Without an explanation this may seem confusing, random, and
      inconsistent. However, there is a method to this madness:

      <orderedlist>
        <listitem>
          <para>
            The unit used in discussion preceding/following an example
            is consistent with the convention used in the example
          </para>
        </listitem>
        <listitem>
          <para>
            Without any scope or context, binary prefixes are used
            (e.g., 1024 KiB, 35565 MiB)
          </para>
        </listitem>
      </orderedlist>
    </para>

    <para>
      For additional literature on why this necessary, I refer you to
      <xref linkend="VDG-Appendix-Units"/>
    </para>
  </section>


  <section xml:id="VDG-Introduction-Feedback">
    <title>Getting Help/Feedback</title>

    <para>
      If you find a typographical or any other error in this book, or
      if you have thought of a way to make this book better, I would
      love to hear from you! Please submit a report in GitHub

      <footnote>
	<para>
	  <link
              xl:href="https://github.com/tbielawa/Virtual-Disk-Guide/issues"/>
	</para>
	</footnote>

	. You can also read or clone the entire book's DocBook 5.1 XML
	source from GitHub.
    </para>

    <para>
      If you have a suggestion for improving the book, try to be as
      specific as possible when describing it. If you have found an
      error, please include the section number and some of the
      surrounding text so I can find it easily. I also recommend you
      review the suggestions in <xref linkend="VDG-Troubleshooting"/>.
    </para>

    <para>
      If you're submitting an error with an example, please try and
      include as much relevant information about your setup as
      possible. This includes (but is not limited to): your operating
      system and version, the version of the software the example
      happens with, if you are running the command as the root user or
      not, and the exact commands to run to reproduce the error.
    </para>
  </section>

  <section xml:id="VDG-Introduction-More-Versions">
    <title>Updates and Alternative Formats</title>

    <para>
      The latest version of this book is always available online for
      <emphasis role="bold">free</emphasis> in the following digital
      formats:

      <itemizedlist>
	<listitem>
	  <para>
	    PDF
	  </para>
	</listitem>
        <listitem>
          <para>
	    HTML Single Page
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      If you find this book useful, please consider supporting the
      author by purchasing a hard-copy. Visit the publisher's website
      at <link xl:href="http://scribesguides.com/"/> for purchasing
      options and links to alternative formats.
    </para>

    <para>
      This book was generated from commit <link
      xl:href="https://github.com/tbielawa/Virtual-Disk-Guide/commit/GENERATION_COMMIT_HASH"><literal>GENERATION_COMMIT_HASH</literal></link>

      <footnote>
	<para>
	  <link xl:href="https://github.com/tbielawa/Virtual-Disk-Guide/commit/GENERATION_COMMIT_HASH"/>
	</para>
      </footnote>

      on GENERATION_TIMESTAMP.
    </para>
  </section>

  <section xml:id="VDG-Introduction-About-The-Author">
    <title>About The Author</title>

    <para>
      Tim Bielawa (or <firstterm>Shaggy</firstterm> if you knew him in
      college) has been a system administrator since his humble
      beginnings in 2007. Back then he was working in the Systems
      Staff Group in the West Virginia University Computer Science
      Department.
    </para>

    <para>
      Now-a-days Tim works at Red Hat, Inc., makers of Red Hat
      Enterprise Linux, and sponsors of the Fedora Project. Tim has
      been involved in Open Source communities for around a decade,
      and a contributor/maintainer for about half that time. In his
      spare time he enjoys writing documentation

      <footnote>
	<para>
	  Docs on lnx.cx: <link xl:href="http://lnx.cx/docs/"/>
	</para>
      </footnote>

      , solving interesting problems (and blogging

      <footnote>
	<para>My blog, Technitribe: <link
	xl:href="https://blog.lnx.cx"/>
	</para>
      </footnote>

      about them), and building things

      <footnote>
	<para>
	  GitHub: tbielawa <link xl:href="https://github.com/tbielawa/"/>
	</para>
      </footnote>
      .
    </para>

    <para>
      <package>bitmath</package> is a Python library Tim wrote which
      simplifies a lot of work required to manipulate (add, subtract,
      convert) prefix units (MiB, kB, TB, etc). Much of the
      inspiration for writing the <package>bitmath</package> library
      came directly from working on this
      book. <package>bitmath</package> is loaded with features:
      converting between units, arithmetic, best human-readable
      representation, rich comparison, sorting, the list of features
      goes on. Check out the bitmath docs

      <footnote>
	<para>
	  Read the bitmath docs online: <link
	  xl:href="https://bitmath.readthedocs.org/en/latest/"/>
	</para>
      </footnote>

      or GitHub project

      <footnote>
	<para>
	  bitmath on GitHub.com: <link
	  xl:href="https://github.com/tbielawa/bitmath"/>
	</para>
      </footnote>

      for more information on getting started.
    </para>
  </section>
</chapter>