Danny Robson (danny at blubinc.com) wrote a paragraph intro for each of

the Haiku kits, thanks for this contribution!
the book is now chunked in multiple files


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@16493 a95241bf-73f2-0310-859d-f6bbb57e9c96

src/documentation/haiku_book/Haiku_Book.xml

@@ -25,7 +25,7 @@
 <!ENTITY license SYSTEM "../license.xml">
 
 <!-- Text Macros -->
-<!ENTITY haikuorg '<ulink url="http://www.haiku-os.org">Haiku</ulink>'>
+<!ENTITY haikuorg '<ulink url="http://www.haiku-os.org/">Haiku</ulink>'>
 <!ENTITY haiku "Haiku">
 
 ]>
@@ -34,10 +34,12 @@
 	<bookinfo>
 		<title>Haiku Book</title>
 		<pubdate>2005-05-16</pubdate>
+		<authorgroup>
 			<author>
 				<firstname>Jerome</firstname>
 				<surname>Duval</surname>
     		</author>
+		</authorgroup>
 
     	<abstract>
 			<para>
@@ -47,7 +49,7 @@
 	 
 		<revhistory>
 			<revision>
-	 <revnumber>1.0</revnumber>
+				<revnumber>1.00</revnumber>
 				<date>2005-05-16</date>
 				<authorinitials>kor</authorinitials>
 				<revremark>Initial version.</revremark>
@@ -76,5 +78,4 @@
 		The License 
 	-->
 	&license;
-
 </book>

src/documentation/haiku_book/Jamfile

@@ -2,13 +2,24 @@ SubDir HAIKU_TOP src documentation haiku_book ;
 
 Doc2HTML 
 	Haiku_Book.xml
-	: 
+	: index.html
-	: http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
+	: http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl
 	: Haiku_Book
+	:
+	: -stringparam use.id.as.filename 1
 	;
 
+# Single most ugly string manipulation ever ...
 rule FRelGristFiles 
 {
+	#local targets = $(1) ;
+
+	#local fallbackgrist = $(2:J=!) ;
+	#local gristval = $(SOURCE_GRIST:E=$(fallbackgrist)) ;
+
+	#local sourcegrist = $(targets:G=gristval) ;
+	#return $(targets:G=$(gristval)) ;
+
 	return $(<:G=$(SOURCE_GRIST:E)$(>:J=!)) ;
 }
 
@@ -28,12 +39,56 @@ translationkit.xml ;
 
 Includes [ FGristFiles Haiku_Book.xml ] 
 	: [ FGristFiles $(chapter_files) ] <src!documentation>license.xml ;
-SEARCH on [ FGristFiles $(chapter_files) ] = [ FDirName $(SUB_DIR) ] ;
+SEARCH on [ FGristFiles $(chapter_files) ] = [ FDirName $(SUBDIR) ] ;
 
 local app_files = intro.xml messaging.xml scripting.xml Application.xml ;
 Includes [ FGristFiles appkit.xml ] : [ FRelGristFiles $(app_files) : app ] ;
-SEARCH on [ FRelGristFiles $(app_files) : app ] = [ FDirName $(SUB_DIR) app ] ;
+SEARCH on [ FRelGristFiles $(app_files) : app ] = [ FDirName $(SUBDIR) app ] ;
+
+local device_files = intro.xml Joystick.xml SerialPort.xml ;
+Includes [ FGristFiles devicekit.xml ] : [ FRelGristFiles $(device_files) : device ] ;
+SEARCH on [ FRelGristFiles $(device_files) : device ] = [ FDirName $(SUBDIR) device ] ;
+
+local game_files = intro.xml ;
+Includes [ FGristFiles gamekit.xml ] : [ FRelGristFiles $(game_files) : game ] ;
+SEARCH on [ FRelGristFiles $(game_files) : game ] = [ FDirName $(SUBDIR) game ] ;
+
+local interface_files = intro.xml ;
+Includes [ FGristFiles interfacekit.xml ] : [ FRelGristFiles $(interface_files) : interface ] ;
+SEARCH on [ FRelGristFiles $(interface_files) : interface ] = [ FDirName $(SUBDIR) interface ] ;
 
 local kern_files = intro.xml threads.xml ports.xml sems.xml ;
 Includes [ FGristFiles kernelkit.xml ] : [ FRelGristFiles $(kern_files) : kernel ] ;
-SEARCH on [ FRelGristFiles $(kern_files) : kernel ] = [ FDirName $(SUB_DIR) kernel ] ;
+SEARCH on [ FRelGristFiles $(kern_files) : kernel ] = [ FDirName $(SUBDIR) kernel ] ;
+
+local mail_files = intro.xml ;
+Includes [ FGristFiles mailkit.xml ] : [ FRelGristFiles $(mail_files) : mail ] ;
+SEARCH on [ FRelGristFiles $(mail_files) : mail ] = [ FDirName $(SUBDIR) mail ] ;
+
+local media_files = intro.xml ;
+Includes [ FGristFiles mediakit.xml ] : [ FRelGristFiles $(media_files) : media ] ;
+SEARCH on [ FRelGristFiles $(media_files) : media ] = [ FDirName $(SUBDIR) media ] ;
+
+local midi_files = intro.xml ;
+Includes [ FGristFiles midikit.xml ] : [ FRelGristFiles $(midi_files) : midi ] ;
+SEARCH on [ FRelGristFiles $(midi_files) : midi ] = [ FDirName $(SUBDIR) midi ] ;
+
+local network_files = intro.xml ;
+Includes [ FGristFiles networkkit.xml ] : [ FRelGristFiles $(network_files) : network ] ;
+SEARCH on [ FRelGristFiles $(network_files) : network ] = [ FDirName $(SUBDIR) network ] ;
+
+local opengl_files = intro.xml ;
+Includes [ FGristFiles openglkit.xml ] : [ FRelGristFiles $(opengl_files) : opengl ] ;
+SEARCH on [ FRelGristFiles $(opengl_files) : opengl ] = [ FDirName $(SUBDIR) opengl ] ;
+
+local storage_files = intro.xml ;
+Includes [ FGristFiles storagekit.xml ] : [ FRelGristFiles $(storage_files) : storage ] ;
+SEARCH on [ FRelGristFiles $(storage_files) : storage ] = [ FDirName $(SUBDIR) storage ] ;
+
+local support_files = intro.xml ;
+Includes [ FGristFiles supportkit.xml ] : [ FRelGristFiles $(support_files) : support ] ;
+SEARCH on [ FRelGristFiles $(support_files) : support ] = [ FDirName $(SUBDIR) support ] ;
+
+local translation_files = intro.xml ;
+Includes [ FGristFiles translationkit.xml ] : [ FRelGristFiles $(translation_files) : translation ] ;
+SEARCH on [ FRelGristFiles $(translation_files) : translation ] = [ FDirName $(SUBDIR) translation ] ;

src/documentation/haiku_book/app/Application.xml

@@ -6,5 +6,4 @@
 
 <sect1 id="app-Application">
 	<title>BApplication</title>
-
 </sect1>

src/documentation/haiku_book/app/intro.xml

@@ -10,6 +10,7 @@
 	<para>
 		Application Kit is about classes needed to interact with other applications or the screen. Information about it is available in several topics :
 	</para>
+
 	<itemizedlist>
 		<listitem><para>
 			<xref linkend="app-messaging"/> helps to send and receive data from other processes.
@@ -21,5 +22,4 @@ Application Kit is about classes needed to interact with other applications or t
 			<xref linkend="app-Application"/> describes an application object. Each application creates one instance to register with the system.
 		</para></listitem>
 	</itemizedlist>
-
 </sect1>

src/documentation/haiku_book/appkit.xml

@@ -7,6 +7,5 @@
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="app/messaging.xml" />
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="app/scripting.xml" />
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="app/Application.xml" />
-
 </chapter>
 

src/documentation/haiku_book/device/Joystick.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="device-Joystick">
+	<title>BJoystick</title>
+</sect1>

src/documentation/haiku_book/device/SerialPort.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="device-SerialPort">
+	<title>BSerialPort</title>
+</sect1>

src/documentation/haiku_book/device/intro.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="device-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>Device Kit</emphasis> provides a collection of classes which provide a programmer a convenient interface with hardware devices attached to the computer. These classes free one from dealing with extraneous details, instead focusing on the device itself.
+	</para>
+
+	<itemizedlist>
+		<listitem><para>
+			<xref linkend="device-SerialPort"/> facilitates usage of an RS-232 port.
+		</para></listitem>
+		<listitem><para>
+			<xref linkend="device-Joystick"/> allows polling of any joystick or gamepad.
+		</para></listitem>
+	</itemizedlist>
+</sect1>
+

src/documentation/haiku_book/devicekit.xml

@@ -3,5 +3,9 @@
 <chapter id="st-devicekit">
 	<title>The Device Kit</title>
 
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="device/intro.xml" />
+
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="device/Joystick.xml" />
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="device/SerialPort.xml" />
 </chapter>
 

src/documentation/haiku_book/game/intro.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="game-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>Game Kit</emphasis> consists of a number of classes which provide:
+		<itemizedlist>
+			<listitem>Fast, but low level, 2D graphics functionality</listitem>
+			<listitem>Convenient sound effect loading, management and playback</listitem>
+		</itemizedlist>
+	</para>
+</sect1>

src/documentation/haiku_book/gamekit.xml

@@ -2,6 +2,6 @@
 
 <chapter id="st-gamekit">
 	<title>The Game Kit</title>
-
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="game/intro.xml" />
 </chapter>
 

src/documentation/haiku_book/interface/intro.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="interface-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>Interface Kit</emphasis> is the core of the window drawing, clicking-dragging, typing, scrolling, GUI world of Haiku. Any application which wants to use any widget will use this set of classes to manage their windows and respond to user/system feedback.
+	</para>
+</sect1>

src/documentation/haiku_book/interfacekit.xml

@@ -2,6 +2,6 @@
 
 <chapter id="st-interfacekit">
 	<title>The Interface Kit</title>
-
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="interface/intro.xml" />
 </chapter>
 

src/documentation/haiku_book/kernel/intro.xml

@@ -10,6 +10,7 @@
 	<para>
 		Kernel Kit is about classes needed to interact with the kernel. Information about it is available in several topics :
 	</para>
+
 	<itemizedlist>
 		<listitem><para>
 			<xref linkend="kern-threads"/> helps to perform tasks.
@@ -21,5 +22,4 @@ Kernel Kit is about classes needed to interact with the kernel. Information abou
 			<xref linkend="kern-sems"/> helps to synchronize threads.
 		</para></listitem>
 	</itemizedlist>
-
 </sect1>

src/documentation/haiku_book/mail/intro.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="mail-intro">
+	<title>Introduction</title>
+
+	<para> The <emphasis>Mail Kit</emphasis> encompasses all email activities on Haiku, providing means for, but not limited to:
+		<itemizedlist>
+			<listitem>Sending and receiving of email</listitem>
+			<listitem>Interfacing for the manipulation of email messages and attachments</listitem>
+			<listitem>Manipulating email account information</listitem>
+		</itemizedlist>  
+	</para>
+</sect1>
+

src/documentation/haiku_book/mailkit.xml

@@ -3,5 +3,6 @@
 <chapter id="st-mailkit">
 <title>The Mail Kit</title>
 
-</chapter>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="mail/intro.xml" />
 
+</chapter>

src/documentation/haiku_book/media/intro.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="media-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>Media Kit</emphasis> controls the heart of the Haiku media playback, recording and transformation. It contains classes in two main areas:
+		<itemizedlist>
+			<listitem>Application: The consumption and production of media. Encoding, decoding and playback.</listitem>
+			<listitem>Node: Direct manipulation of media nodes which process the media</listitem>
+		</itemizedlist>
+	</para>
+</sect1>

src/documentation/haiku_book/mediakit.xml

@@ -3,5 +3,6 @@
 <chapter id="st-mediakit">
 	<title>The Media Kit</title>
 
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="media/intro.xml" />
 </chapter>
 

src/documentation/haiku_book/midi/intro.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="midi-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>Midi Kit</emphasis> provides classes capable of understanding the MIDI file format and synthesising the sounds described within. Furthermore, it also provides mechanisms for communicating with MIDI compliant hardware via messages.
+
+		<note>There are two versions of the Midi Kit, the latter reportedly much more up-to-date and more compatible with other applications. Though sadly it is undocumented. For more information consult the headers (At least until such time as this document is further updated).
+		</note>
+	</para>
+</sect1>

src/documentation/haiku_book/midikit.xml

@@ -3,5 +3,6 @@
 <chapter id="st-midikit">
 	<title>The Midi Kit</title>	
 	
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="midi/intro.xml" />
 </chapter>
 

src/documentation/haiku_book/network/intro.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="network-intro">
+	<title>Introduction</title>
+
+	<para> The <emphasis>Network Kit</emphasis> encompasses all user network functionality in Haiku, providing both the standard UNIX/POSIX socket implementation along with a number of convenience classes for simple buffering, address operations and endpoint manipulation.
+	</para>
+</sect1>
+

src/documentation/haiku_book/networkkit.xml

@@ -3,5 +3,6 @@
 <chapter id="st-networkkit">
 	<title>The Network Kit</title>
 
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="network/intro.xml" />
 </chapter>
 

src/documentation/haiku_book/opengl/intro.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="opengl-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>OpenGL Kit</emphasis> contains the Haiku OpenGL bindings and the BView subclass BGLView which manages the hardware interface and GL contexts.
+	</para>
+</sect1>
+

src/documentation/haiku_book/openglkit.xml

@@ -3,5 +3,6 @@
 <chapter id="st-openglkit">
 	<title>The OpenGL Kit</title>
 
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="opengl/intro.xml" />
 </chapter>
 

src/documentation/haiku_book/storage/intro.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="storage-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>Storage Kit</emphasis> deals with the manipulation, retrieval and creation of filesystem objects. This is enabled by the Haiku implementation of the POSIX filesystem functions (written in C) and a collection of C++ classes which are concerned with areas such as:
+		<itemizedlist>
+			<listitem><para> Entries/nodes </para></listitem>
+			<listitem><para> Volumes </para></listitem>
+			<listitem><para> Queries/Indices </para></listitem>
+			<listitem><para> Utility classes </para></listitem>
+		</itemizedlist>
+	</para>
+</sect1>

src/documentation/haiku_book/storagekit.xml

@@ -3,5 +3,6 @@
 <chapter id="st-storagekit">
 	<title>The Storage Kit</title>
 
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="storage/intro.xml" />
 </chapter>
 

src/documentation/haiku_book/support/intro.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="support-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>Support Kit</emphasis> is an assortment of easy to use classes which allow a programmer to quickly extend their applications without re-writing much common functionality. Many benefits can arrise from using these classes when one starts to extend an application in the future. Functionality includes:
+		<itemizedlist>
+			<listitem><para>
+				Threading utility classes:
+				<itemizedlist>
+					<listitem><para> BLocker and BAutoLock </para></listitem>
+					<listitem><para> "Thread Local Storage" </para></listitem>
+				</itemizedlist>
+			</para></listitem>
+			<listitem><para>
+				Archiving and IO:
+				<itemizedlist>
+					<listitem><para> BArchivable </para></listitem>
+					<listitem><para> BFlattenable </para></listitem>
+					<listitem><para> BDataIO and BPositionIO </para></listitem>
+					<listitem><para> BMemoryIO and BMallocIO </para></listitem>
+				</itemizedlist>
+			</para></listitem>
+			<listitem><para> BBlockCache </para></listitem>
+			<listitem><para> BList </para></listitem>
+			<listitem><para> BString </para></listitem>
+			<listitem><para> BStopWatch </para></listitem>
+			<listitem><para> Common types and constants </para></listitem>
+			<listitem><para> Error codes for all kits </para></listitem>
+		</itemizedlist> 
+	</para>
+</sect1>

src/documentation/haiku_book/supportkit.xml

@@ -3,5 +3,6 @@
 <chapter id="st-supportkit">
 	<title>The Support Kit</title>
 
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="support/intro.xml" />
 </chapter>
 

src/documentation/haiku_book/translation/intro.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<sect1 id="translation-intro">
+	<title>Introduction</title>
+
+	<para>
+		The <emphasis>Translation Kit</emphasis> gives the user the ability to convert media from one format into a number of target formats. To accomplish this it provides functionality in the form of BTranslatorRoster for the act, management and configuration of the translation and BTranslator for the creation of new translators between additional formats.
+	</para>
+</sect1>

src/documentation/haiku_book/translationkit.xml

@@ -3,5 +3,6 @@
 <chapter id="st-translationkit">
 	<title>The Translation Kit</title>
 
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="translation/intro.xml" />
 </chapter>