2003-07-11 Casper S. Hornstrup <chorns@users.sourceforge.net>

* tutorials.xml: New entity taggingfunctions.
	* dev/advandev/taggingfunctions.xml: New file.

svn path=/trunk/rosdocs/; revision=5076

ChangeLog

@@ -1,8 +1,3 @@
-2003-05-28  Casper S. Hornstrup  <chorns@users.sourceforge.net>
-
-	* tutorials/user/intro/installiso.xml: Installation program can create
-	and delete partitions and format them with a FAT32 filesystem.
-
 2002-11-05  Casper S. Hornstrup  <chorns@users.sourceforge.net>
 
 	* ChangeLog: Added.

tutorials/ChangeLog

@@ -1,3 +1,13 @@
+2003-07-11  Casper S. Hornstrup  <chorns@users.sourceforge.net>
+
+	* tutorials.xml: New entity taggingfunctions.
+	* dev/advandev/taggingfunctions.xml: New file.
+
+2003-05-28  Casper S. Hornstrup  <chorns@users.sourceforge.net>
+
+	* user/intro/installiso.xml: Installation program can create
+	and delete partitions and format them with a FAT32 filesystem.
+
 2002-11-05  Casper S. Hornstrup  <chorns@users.sourceforge.net>
 
 	* dev/shcode/mailpatch.xml: Use "cvs diff -up" instead of "diff".

tutorials/dev/advandev/taggingfunctions.xml

@@ -0,0 +1,68 @@
+<chapter>
+<title>Tagging functions</title>
+
+<!--
+<artheader>
+   <title>Tagging functions</title>
+   <author>
+      <firstname>Casper</firstname>
+      <surname>Hornstrup</surname>
+      <affiliation>
+        <address>
+          <email>chorns@users.sourceforge.net</email>
+        </address>
+      </affiliation>
+   </author>
+</artheader>
+-->
+
+<abstract>
+<para>
+Explains what tags are and how to use them.
+</para>
+</abstract>
+
+<sect2>
+<title>TABLE OF CONTENTS</title>
+<itemizedlist>
+<listitem>1 Overview</listitem>
+<listitem>2 MS API compatibility</listitem>
+</itemizedlist>
+</sect2>
+
+<sect2>
+<title>1 Overview</title>
+<para>
+We define tagging a function as the process of associating metadata with a function. We define a tag to be a piece of information that has a well-defined meaning.
+A tag has one attribute - a name. The name of a tag always begin with the at sign (@) and it can include only the letters a-z and digits 0-9 and the underscore (_).
+Tagnames are case-insensitive. In the future a tag could have one more attribute - a value, but this is currently not needed.
+<para>
+In ReactOS, tags are currently only used to track compatibility with Microsoft APIs, but it could be used for so much more.
+Tags are applied to functions by including them in a comment just before the function. Eg. if you have a function called MyFunction,
+then you can tag it with the tag @mytag like this:
+<programlisting>
+/*
+ * @mytag
+ */
+VOID
+MyFunction()
+{
+}
+</programlisting>
+</para>
+
+</para>
+</sect2>
+
+<sect2>
+<title>2 Microsoft API compatibility</title>
+<para>
+Two tags are defined to track compatibility with Microsoft APIs. @implemented and @unimplemented.
+Apply @implemented to functions which match and behaves like a Microsoft API.
+Use @unimplemented to functions which match, but does not behave like a Microsoft API.
+The regenstat tool (located in reactos/tools/rgenstat) will parse the source code for these tags and generate an xml file containing functions that have these tags.
+The xml file can be processed by the rapistatus.xsl xml stylesheet (located in reactos/tools/rgenstat/web) to create an html file suitable for display using a browser.
+</para>
+</sect2>
+
+</chapter>

tutorials/tutorials.xml

@@ -16,6 +16,7 @@
   <!ENTITY cvsupd SYSTEM "dev/shcode/cvsupd.xml">
   <!ENTITY mailpatch SYSTEM "dev/shcode/mailpatch.xml">
   <!ENTITY archoverview SYSTEM "dev/advandev/archoverview.xml">
+  <!ENTITY taggingfunctions SYSTEM "dev/advandev/taggingfunctions.xml">
   <!ENTITY win32wine SYSTEM "dev/advandev/win32wine.xml">
   <!ENTITY introbochs SYSTEM "dev/bochtest/introbochs.xml">
   <!ENTITY getbochs SYSTEM "dev/bochtest/getbochs.xml">
@@ -91,6 +92,8 @@
 
       &archoverview;
 
+      &taggingfunctions;
+
       &win32wine;
 
     </part>