--- wikisrc/users/jruoho/Attic/doc.mdwn	2010/04/05 06:48:02	1.5
+++ wikisrc/users/jruoho/Attic/doc.mdwn	2010/04/05 07:04:35	1.6
@@ -11,9 +11,17 @@ The conventions used for markup transiti
 Problems:
 
 * All documents must be HTML ready (the eternal <, >, &, etc.).
-* There seems to be no easy way to define custom macros.
+* There seems to be no easy way to define custom macros (cf. &os;, etc.).
+* Only the H1-headers are enumerated in the table of conents.
+* Headers are not enumerated in the body text.
 
-# Part I. About NetBSD
+Benefits:
+
+* Much, much clearer syntax compared to XML. The *Markdown* almost resembles
+  plain text. This should be a big benefit in lowering the barriers of entry
+  to documentation.
+
+# About NetBSD
 
 [[!toc]]
 
@@ -48,41 +56,76 @@ The full source to the NetBSD kernel and
 supported platforms; please see the details on the official site of the
 [NetBSD Project](http://www.NetBSD.org/ "NetBSD").
 
-The basic features of NetBSD are:
+* Code quality and correctness
+* Portability to a wide range of hardware
+* Secure defaults
+* Adherence to industry standards
+* Research and innovation
+
+These characteristics bring also indirect advantages. For example, if you work
+on just one platform you could think that you're not interested in portability.
+But portability is tied to code quality; without a well written and well
+organized code base it would be impossible to support a large number of
+platforms. And code quality is the base of any good and solid software system,
+though surprisingly few people seem to understand it.
+
+One of the key characteristics of NetBSD is that its developers are not
+satisfied with partial implementations. Some systems seem to have the
+philosophy of *if it works, it's right*. In that light NetBSD's philosophy
+could be described as *it doesn't work unless it's right*. Think about how
+many overgrown programs are collapsing under their own weight and "features"
+and you'll understand why NetBSD tries to avoid this situation at all costs.
 
-    <itemizedlist>
-      <listitem>
-        <para>Code quality and correctness</para>
-      </listitem>
-
-      <listitem>
-        <para>Portability to a wide range of hardware</para>
-      </listitem>
-
-      <listitem>
-        <para>Secure defaults</para>
-      </listitem>
-
-      <listitem>
-        <para>Adherence to industry standards</para>
-      </listitem>
-
-      <listitem>
-        <para>Research and innovation</para>
-      </listitem>
-    </itemizedlist>
-
-    <para>These characteristics bring also indirect advantages.
-      For example, if you work on just one platform you could think that
-      you're not interested in portability.
-      But portability is tied to code quality; without a well written and
-      well organized code base it would be impossible to support a large
-      number of platforms.
-      And code quality is the base of any good and solid software system,
-      though surprisingly few people seem to understand it.</para>
+### Supported platforms
 
+NetBSD supports many platforms, including the popular PC platform (i386 and
+amd64), SPARC and UltraSPARC, Alpha, Amiga, Atari, and m68k and PowerPC
+based Apple Macintosh machines. Technical details for all of them can be
+found on [the NetBSD site](http://www.NetBSD.org/ports "NetBSD Ports").
 
-### Supported platforms
 ### NetBSD's target users
+
+The NetBSD site states that: *the NetBSD Project provides a freely available
+and redistributable system that professionals, hobbyists, and researchers
+can use in whatever manner they wish*. It is also an ideal system if you
+want to learn Unix, mainly because of its adherence to standards (one of the
+project goals) and because it works equally well on the latest PC hardware
+as well as on hardware which is considered obsolete by many other operating
+systems. To learn and use Unix you don't need to buy expensive hardware; you
+can use that old PC or Mac in your attic. It is important to note that
+although NetBSD runs on old hardware, modern hardware is well supported and
+care has been taken to ensure that supporting old machines does not inhibit
+performance on modern hardware.  In addition, if you need a Unix system
+which runs consistently on a variety of platforms, NetBSD is probably your
+best choice.
+
 ### Applications for NetBSD
+
+Aside from the standard Unix productivity tools, editors, formatters, C/C++
+compilers and debuggers and so on that are included with the base system,
+there is a huge collection of packages (currently over 8,000) that can be
+installed both from source and in pre-compiled form. All the packages that
+you expect to find on a well configured system are available for NetBSD for
+free.  The framework that makes this possible, pkgsrc, also includes a
+number of commercial applications.  In addition, NetBSD provides binary
+emulation for various other *nix operating systems, allowing you to run
+non-native applications.  Linux emulation is probably the most relevant
+example.  You can run the Linux versions of
+
+* Firefox
+* the Adobe Flash player plugin
+* Acrobat Reader
+* many other programs
+
 ### How to get NetBSD
+
+NetBSD is an Open Source operating system, and as such it is freely
+available for download from [ftp.NetBSD.org](ftp://ftp.NetBSD.org
+"ftp.NetBSD.org") and its [mirrors](http://www.NetBSD.org/mirrors/
+"NetBSD mirrors").
+
+There is no "official" supplier of NetBSD CD-ROMs but there are various
+resellers.  You can find the most up to date list on the relevant
+[page](http://www.NetBSD.org/sites/cdroms.html "CD-ROMs") on the NetBSD
+site.
+