add example

build/documentation/README.md

@@ -1,4 +1,4 @@
-# Documentation HOW-TO
+# Documentation HOWTO
 
 **HTML Tidy** provides several types of documentation to suit different purposes. This
 document describes how to generate the following:

build/documentation/tidy_docs.dox

@@ -17,16 +17,79 @@
 \section content Contents
 
 - \ref tidy5_cmd
+- \ref tidy5_lib
 - \ref building_tidy
 - \ref history
     
     
+    
+    
 \page tidy5_cmd `tidy5` command
 
 <pre>
 \htmlinclude tidy5.cmd.txt
 </pre>
 
+\page tidy5_lib tidy5lib
+
+- \b TidyLib is easy to integrate. Because of the near universal adoption of C linkage, a C interface may be called from a great number of programming languages.
+
+- \b TidyLib was designed to use opaque types in the public interface. This allows the application to just pass an integer around and the need to transform data types in different languages is minimized. As a results it’s straight-forward to write very thin library wrappers for C++, Pascal, and COM/ATL.
+
+- \b TidyLib eats its own dogfood. HTML Tidy links directly to TidyLib.
+
+- \b TidyLib is Thread Safe and Re-entrant. Because there are many uses for HTML Tidy - from content validation, content scraping, conversion to XHTML - it was important to make TidyLib run reasonably well within server applications as well as client side.
+
+- \b TidyLib uses adaptable I/O. As part of the larger integration strategy it was decided to fully abstract all I/O. This means a (relatively) clean separation between character encoding processing and shovelling bytes back and forth. Internally, the library reads from sources and writes to sinks. This abstraction is used for both markup and configuration “files”. Concrete implementations are provided for file and memory I/O, and new sources and sinks may be provided via the public interface.
+
+\code{.c}
+#include <tidy.h>;
+#include <buffio.h>;
+#include <stdio.h>;
+#include <errno.h>;
+
+int main(int argc, char **argv )
+{
+  const char* input = "<title>Foo</title><p>Foo!";
+  TidyBuffer output = {0};
+  TidyBuffer errbuf = {0};
+  int rc = -1;
+  Bool ok;
+
+  TidyDoc tdoc = tidyCreate();                     // Initialize "document"
+  printf( "Tidying:\t%s\n", input );
+
+  ok = tidyOptSetBool( tdoc, TidyXhtmlOut, yes );  // Convert to XHTML
+  if ( ok )
+    rc = tidySetErrorBuffer( tdoc, &errbuf );      // Capture diagnostics
+  if ( rc >= 0 )
+    rc = tidyParseString( tdoc, input );           // Parse the input
+  if ( rc >= 0 )
+    rc = tidyCleanAndRepair( tdoc );               // Tidy it up!
+  if ( rc >= 0 )
+    rc = tidyRunDiagnostics( tdoc );               // Kvetch
+  if ( rc > 1 )                                    // If error, force output.
+    rc = ( tidyOptSetBool(tdoc, TidyForceOutput, yes) ? rc : -1 );
+  if ( rc >= 0 )
+    rc = tidySaveBuffer( tdoc, &output );          // Pretty Print
+
+  if ( rc >= 0 )
+  {
+    if ( rc > 0 )
+      printf( "\nDiagnostics:\n\n%s", errbuf.bp );
+    printf( "\nAnd here is the result:\n\n%s", output.bp );
+  }
+  else
+    printf( "A severe error (%d) occurred.\n", rc );
+
+  tidyBufFree( &output );
+  tidyBufFree( &errbuf );
+  tidyRelease( tdoc );
+  return rc;
+}
+\endcode
+
+
 \page building_tidy Building Tidy
 
 \section Prerequisites