- DB: update documentation, better intro page and contributor list

OSInside · Oct 5, 2011 · 4b5c9d0 · 4b5c9d0
1 parent 1275b24
commit 4b5c9d0
Show file tree

Hide file tree

Showing 10 changed files with 574 additions and 357 deletions.
diff --git a/doc/KIWI::config.sh.1 b/doc/KIWI::config.sh.1
@@ -2,12 +2,12 @@
 .\"     Title: kiwi::config.sh
 .\"    Author: Marcus Schäfer <ms (AT) suse.de>
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: Created: 09/16/2011
+.\"      Date: Created: 10/05/2011
 .\"    Manual: KIWI Manualpage
 .\"    Source: KIWI 4.97
 .\"  Language: English
 .\"
-.TH "KIWI::CONFIG\&.SH" "1" "Created: 09/16/2011" "KIWI 4\&.97" "KIWI Manualpage"
+.TH "KIWI::CONFIG\&.SH" "1" "Created: 10/05/2011" "KIWI 4\&.97" "KIWI Manualpage"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------

diff --git a/doc/KIWI::images.sh.1 b/doc/KIWI::images.sh.1
@@ -2,12 +2,12 @@
 .\"     Title: kiwi::images.sh
 .\"    Author: Marcus Schäfer <ms (AT) suse.de>
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: Created: 09/16/2011
+.\"      Date: Created: 10/05/2011
 .\"    Manual: KIWI Manualpage
 .\"    Source: KIWI 4.97
 .\"  Language: English
 .\"
-.TH "KIWI::IMAGES\&.SH" "1" "Created: 09/16/2011" "KIWI 4\&.97" "KIWI Manualpage"
+.TH "KIWI::IMAGES\&.SH" "1" "Created: 10/05/2011" "KIWI 4\&.97" "KIWI Manualpage"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------

diff --git a/doc/KIWI::kiwirc.1 b/doc/KIWI::kiwirc.1
@@ -2,12 +2,12 @@
 .\"     Title: kiwi::kiwirc
 .\"    Author: Robert Schweikert <rschweikert (AT) novell.com>
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: Created: 09/16/2011
+.\"      Date: Created: 10/05/2011
 .\"    Manual: KIWI Manualpage
 .\"    Source: >KIWI 4.97
 .\"  Language: English
 .\"
-.TH "KIWI::KIWIRC" "1" "Created: 09/16/2011" ">KIWI 4\&.97" "KIWI Manualpage"
+.TH "KIWI::KIWIRC" "1" "Created: 10/05/2011" ">KIWI 4\&.97" "KIWI Manualpage"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------

diff --git a/doc/docbook/kiwi-doc-contributors.xml b/doc/docbook/kiwi-doc-contributors.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                         "http://www.docbook.org/xml/4.5/docbookx.dtd">
+
+<chapter id="chap.contributors">
+  <title>Contributors</title>
+  <indexterm>
+    <primary>KIWI</primary>
+    <secondary>Contributors</secondary>
+  </indexterm>
+
+  <sect1 id="sec.contributors">
+    <title>Contributors to KIWI</title>
+      <info>
+        <authorgroup>
+          <author>
+            <affiliation>
+              <orgname>SUSE LINUX Products GmbH</orgname>
+            </affiliation>
+            <firstname>Marcus</firstname>
+            <surname>Sch??fer</surname>
+            <contrib>Project Lead, Design, Doc, Implementation</contrib>
+            <email>ms@suse.de</email>
+          </author>
+          <othercredit>
+            <affiliation>
+              <orgname>Dell</orgname>
+            </affiliation>
+            <firstname>Praveen</firstname>
+            <surname>Paladugu</surname>
+            <contrib>Implementation Centos/RHEL focus</contrib>
+            <email>Praveen_Paladugu@dell.com </email>
+          </othercredit>
+          <othercredit>
+            <affiliation>
+              <orgname>SUSE LINUX Products GmbH</orgname>
+            </affiliation>
+            <firstname>Thomas</firstname>
+            <surname>Schraitle</surname>
+            <contrib>Documentation, XSLT</contrib>
+            <email>toms@suse.de</email>
+          </othercredit>
+          <othercredit>
+            <affiliation>
+              <orgname>SUSE LINUX Products GmbH</orgname>
+            </affiliation>
+            <firstname>Adrian</firstname>
+            <surname>Schroeter</surname>
+            <contrib>Build Service integration</contrib>
+            <email>adrian@suse.de</email>
+          </othercredit>
+          <othercredit>
+            <affiliation>
+              <orgname>SUSE</orgname>
+            </affiliation>
+            <firstname>Robert</firstname>
+            <surname>Schweikert</surname>
+            <contrib>Design, Doc, Implementation</contrib>
+            <email>rjschwei@suse.com</email>
+          </othercredit>
+          <othercredit>
+            <affiliation>
+              <orgname>SUSE</orgname>
+            </affiliation>
+            <firstname>Dinar</firstname>
+            <surname>Valeev</surname>
+            <contrib>Implementation, Power architecture</contrib>
+            <email>dvaleev@suse.com</email>
+          </othercredit>
+        </authorgroup>
+      </info>
+   </sect1>
+</chapter>
diff --git a/doc/docbook/kiwi-doc-introduction.xml b/doc/docbook/kiwi-doc-introduction.xml
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                         "http://www.docbook.org/xml/4.5/docbookx.dtd">
+
+<chapter id="chap.introduction">
+  <title>Introduction</title>
+  <indexterm>
+    <primary>KIWI</primary>
+    <secondary>Introduction</secondary>
+  </indexterm>
+
+  <sect1 id="sec.introduction.whatiskiwi">
+    <title>What is KIWI?</title>
+      <para>KIWI is an image build system for Linux.</para>
+      <para>A Linux image may present itself in many different formats,
+    for example the <filename class="extension">*.iso</filename> file you
+    download to burn a distribution installation file to optical media is an
+    image. A file used by virtualization systems such as KVM, Xen, or VMware
+    is an image. The installation of a Linux system on your hard drive can be
+    turned into an image using the <command>dd</command> command.</para>
+    <para>Basically, you can think of an image as a Linux system in a file.
+    Depending on the type of the image you are dealing with you have different
+    options for using the image. For example you can burn an ISO image to
+    optical media and then boot your computer from the CD/DVD, or you can run
+    a Virtual Machine from the <filename class="extension">*.iso</filename>
+    file (image) stored on your hard drive.</para>
+  </sect1>
+  <sect1 id="sec.introduction.whatdoeskiwido">
+    <title>What does KIWI do?</title>
+      <para>KIWI builds images in a variety of formats.</para>
+      <para>As an image build tool, KIWI builds images in a relatively large
+    number of supported image formats. The details of the image creation
+    process are explained in the <xref linkend="chap.workflow"/> chapter. The
+    image format of the image produced by KIWI is defined within a
+    configuration file named <filename>config.xml</filename> as described in
+    <xref linkend="chap.description"/>.</para>
+  </sect1>
+  <sect1 id="sec.introduction.howtousekiwi">
+    <title>How do I use KIWI?</title>
+      <para>KIWI is a command line tool that is invoked with the
+    <command>kiwi</command> command in your shell. KIWI needs to be executed
+    as the <systemitem class="username">root</systemitem> user, as administrative privileges are
+    required for many operations that need to take place to create an image.
+    Therefore, when using KIWI you need to be aware of what you are doing and
+    a certain amount of caution is in order. Running KIWI on your system is
+    not inherently dangerous to your system, just keep in mind that you are
+    running as the <systemitem class="username">root</systemitem> user.</para>
+      <para>An image is created in a two step process as described in the
+    <xref linkend="chap.workflow"/> chapter. Use
+    <command>kiwi --prepare</command> for the first step and
+    <command>kiwi --create</command> for the second step. For user convenience
+    KIWI also has the <option>--build</option> that combines the
+    <emphasis>prepare</emphasis> and <emphasis>create</emphasis> steps.</para>
+      <para>Additional introductory information can also be found on the web at
+        <ulink
+          url="http://en.opensuse.org/SDB:KIWI_Cookbook_Start_Cooking"/>.
+     </para>
+  </sect1>
+</chapter>
diff --git a/doc/docbook/kiwi-doc-workflow.xml b/doc/docbook/kiwi-doc-workflow.xml
@@ -11,16 +11,21 @@
 
   <sect1 id="sec.workflow.introduction">
     <title>Introduction</title>
-      <para>The openSUSE KIWI Image System provides a complete operating
-    system image solution for Linux supported hardware platforms as well
-    as for virtualization systems like Xen, VMware, etc. The KIWI
-    architecture was designed as a two level system. The first stage,
-    based on a valid <emphasis>software package source</emphasis>,
-    creates a so called <emphasis>unpacked image</emphasis> according to
-    the provided image description. The second stage creates from a
-    required unpacked image an operating system image. The result of the
-    second stage is called a <emphasis>packed image</emphasis> or short
-    an image. </para>
+      <para>KIWI creates images in a two step process, as mentioned previously.
+    The first step, the <emphasis>prepare</emphasis> operation, generates a
+    so called <emphasis>unpacked image</emphasis> tree (directory)
+    based on the specified <emphasis>package sources (repositories)</emphasis>
+    in the <filename>config.xml</filename> configuration file. The
+    <filename>config.xml</filename> file is part of the
+    <emphasis>configuration directory (tree)</emphasis> that describes the
+    image to be created by KIWI. The second step, the
+    <emphasis>create</emphasis> operation, creates the
+    <emphasis>packed image</emphasis> or <emphasis>image</emphasis> in the
+    specified format based on the unpacked image and the
+    <emphasis>boot image</emphasis> description specified in the
+    <filename>config.xml</filename> file. The boot image description is
+    supplied by KIWI.
+    <!--insert xref to install chapter here, when we have it--> </para>
 
 
     <figure id="fig.imageservingarch">
@@ -47,21 +52,41 @@
       </mediaobjectco>
     </figure>
 
-  <para>Because this document contains conceptual information about an
-    image system, it is important to understand what an operating system
-    image is all about. A normal installation process is starting from a
-    given installation source and installs single pieces of software
-    until the system is complete. During this process manual user
-    intervention may be required. However, an operating system image
-    represents an already completed <emphasis>installation</emphasis>,
-    encapsulated as a file and optionally includes the configuration for
-    a specific task. Such an operating system starts working as soon as
-    the image has been brought to a system storage device, no matter if
-    this is a volatile or non volatile storage. The process of creating
-    an image takes place without user interaction. This means, all
-    requirements of the encapsulated system have to be fulfilled before
-    the image is created. All of this information is stored in the
-      <emphasis>image description</emphasis>. </para>
+  <para>Prior to building an image with KIWI it is important to understand
+    the make up of an image and the general concepts of a Linux system from
+    boot to running system.</para>
+  <para>A regular installation of a Linux system starts from a given
+    installation source, this could be an installation CD/DVD, a PXE boot
+    environment, or an install media that accesses the Internet to retrieve
+    software for installation. In many installation user interaction with an
+    installer takes place to collect data such as
+    <emphasis>software to be installed</emphasis>,
+    <emphasis>timezone</emphasis>, and <emphasis>user</emphasis> information.
+    Once all information is collected the installer installs the necessary and
+    specified software onto the computer at hand based on the available
+    software sources (repositories). Often a final configuration procedure
+    takes place after the install process is complete. This configuration
+    process contains automated setup functions and may include user
+    interaction.</para>
+  <para>Opposed to a regular install process described above, an image
+    is a <emphasis>completed installation</emphasis> of a Linux system in a
+    file. The image represents an operational system. The behavior of the
+    image varies depending on the image type and image configuration. It is
+    possible to create images that just run inside a virtual environment and
+    do not requires any configuration at start up, as all the configuration
+    information is already encoded in the image. It is possible to create
+    images that automatically configure themselves in a designated
+    environment. Further it is possible to create images that follow an
+    interactive configuration procedure when booted for the first time. An
+    image can also be created to employ any combination of configuration
+    options. The image creation process itself occurs without user interaction.
+    All information that is needed to create the image is encoded in the
+    <filename>config.xml</filename> file and optionally in the
+    <filename>config.sh</filename> and <filename>images.sh</filename> scripts
+    as well as the optional <emphasis>overlay tree (directory)</emphasis>
+    called <filename>root</filename>. The configuration information is stored
+    in the so called <emphasis>image description</emphasis> or
+    <emphasis>configuration directory</emphasis>.</para>
   </sect1>
 
   <sect1 id="sec.workflow.bootprocess">

diff --git a/doc/docbook/kiwi-doc.xml b/doc/docbook/kiwi-doc.xml
@@ -55,7 +55,7 @@
     </mediaobject>
   </bookinfo>
 
-  <!--<xi:include href="kiwi-doc-intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>-->
+  <xi:include href="kiwi-doc-introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
   <xi:include href="kiwi-doc-workflow.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
   <xi:include href="kiwi-doc-description.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
   <xi:include href="kiwi-doc-appliance.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

diff --git a/doc/kiwi.1 b/doc/kiwi.1
@@ -2,12 +2,12 @@
 .\"     Title: kiwi
 .\"    Author: Marcus Schaefer <ms (AT) suse.de>
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: Created: 09/16/2011
+.\"      Date: Created: 10/05/2011
 .\"    Manual: KIWI Manualpage
 .\"    Source: KIWI 4.97
 .\"  Language: English
 .\"
-.TH "KIWI" "1" "Created: 09/16/2011" "KIWI 4\&.97" "KIWI Manualpage"
+.TH "KIWI" "1" "Created: 10/05/2011" "KIWI 4\&.97" "KIWI Manualpage"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------