From: Andre Noll Date: Mon, 15 Jun 2020 17:16:50 +0000 (+0200) Subject: web: Convert QUICK_START to markdown syntax. X-Git-Tag: v0.2.0~2^2~6 X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=975357d614c27b81fbd65162a72d66d3b1a16a57;p=osl.git web: Convert QUICK_START to markdown syntax. This file is rather simple and we don't need doxygen to convert it to html. After this, the quick start document becomes part of the main page. Although this patch modifies almost every line of QUICK_START, the changes to the actual contents have been kept to a minimum. --- diff --git a/Makefile b/Makefile index bdf78a2..bc0d6ed 100644 --- a/Makefile +++ b/Makefile @@ -150,12 +150,14 @@ www: web/index.html web/osl.png web/doxygen/index.html web/osl.png: web/osl.pdf Makefile convert -scale 200x200 $< $@ -web/index.html: oslfsck.1 web/index.html.in INSTALL README +web/index.html: oslfsck.1 web/index.html.in INSTALL README QUICK_START sed -e '/@README@/,$$d' web/index.html.in > $@ markdown < README >> $@ sed -e '1,/@README@/d' -e '/@INSTALL@/,$$d' web/index.html.in >> $@ markdown < INSTALL >> $@ - sed -e '1,/@INSTALL@/d' -e '/@MAN_PAGE@/,$$d' web/index.html.in >> $@ + sed -e '1,/@INSTALL@/d' -e '/@QUICK_START@/,$$d' web/index.html.in >> $@ + markdown < QUICK_START >> $@ + sed -e '1,/@QUICK_START@/d' -e '/@MAN_PAGE@/,$$d' web/index.html.in >> $@ groff -m man -Thtml -P -l oslfsck.1 | sed -e '1,/^/d; /^<\/body>/,$$d' >> $@ sed -e '1,/@MAN_PAGE@/d' web/index.html.in >> $@ diff --git a/QUICK_START b/QUICK_START index cbb55a1..39666ab 100644 --- a/QUICK_START +++ b/QUICK_START @@ -1,154 +1,133 @@ -/** \mainpage OSL Quick start - This document describes the steps which have to be performed in order to create and use an osl table. The code sniplets in this section -are taken from the file \ref osltar.c in the source distribution. +are taken from the file `osltar.c` in the source distribution. -The complete API reference is contained in the file \ref osl.h. +The complete API reference is contained in the file `osl.h.` -- Define an enum that assigns descriptive names to the columns +Define an enum that assigns descriptive names to the columns of your table. Example: -\verbatim - -enum osltar_columns { - OTC_NAME, - OTC_DATA, - NUM_OT_COLUMNS -}; - -\endverbatim - -The last element is is useful because the number of columns -of your table must be specified later, see below. - -- Define an array of struct osl_column_description, one -array member per column: - -\verbatim - -struct osl_column_description tar_table_cols[] = { - [OTC_NAME] = { - .storage_type = OSL_MAPPED_STORAGE, - .storage_flags = OSL_RBTREE | OSL_UNIQUE, - .name = "filename", - .compare_function = string_compare, - }, - [OTC_DATA] = { - .storage_type = OSL_MAPPED_STORAGE, - .name = "data", - }, -}; - -\endverbatim - -Three different storage types are available which may be -selected on a per-column basis: \ref OSL_DISK_STORAGE, \ref -OSL_MAPPED_STORAGE, and \ref OSL_NO_STORAGE. - -For columns of type OSL_MAPPED_STORAGE and OSL_NO_STORAGE an optional -rbtree is maintained by the osl library which allows to quickly lookup -rows by cell content. Whether or not an rbtree should be used must be -specified in the storage_flags field which should contain the bitwise -or of suitable \ref osl_storage_flags. - -If a column has an associated rbtree, i.e. if the OSL_RBTREE flag -is set in the storage flags for the column, the compare_function -field must be initialized to point to a function of type \ref -osl_compare_func. In this example, \ref string_compare() is used, -which is just a wrapper for strcmp() that interprets osl objects as -C-strings and calls strcmp() on the object data. - -- Define a struct \ref osl_table_description and initialize -it with the number of columns of your table and the column -descriptions: - -\verbatim - -struct osl_table_description tar_table_desc = { - .name = "tar_table", - .num_columns = NUM_OT_COLUMNS, - .column_descriptions = tar_table_cols, - .dir = "/tmp/osltest" -}; - -\endverbatim - -- Create the table by calling \ref osl_create_table(): - -\verbatim - -ret = osl_create_table(&tar_table_desc); - -\endverbatim - -- Open the newly created table by calling osl_open_table: - -\verbatim - -struct osl_table *table; -ret = osl_open_table(&tar_table_desc, &table); - -\endverbatim - -- To add a new row to the table, you must define an array of struct -osl_object of length NUM_OT_COLUMNS which holds the contents of the -new row. Note that an osl object is just a blob: It consists of a -data pointer and a size value. Once the array has been initialized, -pass it to \ref osl_add_row() together with the table handle obtained -from osl_open_table(): - -\verbatim - -struct osl_object objs[NUM_OT_COLUMNS]; -/* ...init the array... */ -ret = osl_add_row(table, objs); - -\endverbatim - -- Close the table with \ref osl_close_table(). - -\verbatim - -osl_close_table(table, OSL_MARK_CLEAN); - -\endverbatim - -The storage type of both columns of the table in this example -is OSL_MAPPED_STORAGE, so you can later open the table again -and retrieve its contents: - -\verbatim - -ret = osl_get_row(table, OTC_NAME, &obj, &row); -if (ret < 0) { - fprintf(stderr, "osl_get_row(%s): %s\n", name, - osl_strerror(-ret)); - return ret; -} -ret = osl_get_object(table, row, OTC_DATA, &obj); - -\endverbatim - -The call to \ref osl_get_row() uses the rbtree of the OTC_NAME -column to find the row whose object in the OTC_NAME column -matches the given object obj. If a row was found, it is -passed to \ref osl_get_object() which returns the object of -the OTC_DATA column of this row. - +
+	enum osltar_columns {
+		OTC_NAME,
+		OTC_DATA,
+		NUM_OT_COLUMNS
+	};
+
+ +The last element is is useful because the number of columns of your +table must be specified later, see below. + +Define an array of struct osl_column_description, one array member +per column: + +
+	struct osl_column_description tar_table_cols[] = {
+		[OTC_NAME] = {
+			.storage_type = OSL_MAPPED_STORAGE,
+			.storage_flags = OSL_RBTREE | OSL_UNIQUE,
+			.name = "filename",
+			.compare_function = string_compare,
+		},
+		[OTC_DATA] = {
+			.storage_type = OSL_MAPPED_STORAGE,
+			.name = "data",
+		},
+	};
+
+ +Three different storage types are available which may be selected +on a per-column basis: `OSL_DISK_STORAGE`, `OSL_MAPPED_STORAGE`, and +`OSL_NO_STORAGE`. + +For columns of type `OSL_MAPPED_STORAGE` and `OSL_NO_STORAGE` an +optional rbtree is maintained by the osl library which allows to +quickly lookup rows by cell content. Whether or not an rbtree should +be used must be specified in the `storage_flags` field which should +contain the bitwise or of suitable `osl_storage_flags`. + +If a column has an associated rbtree, i.e. if the `OSL_RBTREE` flag +is set in the storage flags for the column, the `compare_function` +field must be initialized to point to a function of type +`osl_compare_func`. In this example, `string_compare()` is used, +which is just a wrapper for `strcmp()` that interprets osl objects +as C-strings and calls `strcmp()` on the object data. + +Define a struct `osl_table_description` and initialize it with +the number of columns of your table and the column descriptions: + +
+	struct osl_table_description tar_table_desc = {
+		.name = "tar_table",
+		.num_columns = NUM_OT_COLUMNS,
+		.column_descriptions = tar_table_cols,
+		.dir = "/tmp/osltest"
+	};
+
+ +Create the table by calling `osl_create_table()`: + +
+	ret = osl_create_table(&tar_table_desc);
+
+ +Open the newly created table by calling `osl_open_table()`: + +
+	struct osl_table *table;
+	ret = osl_open_table(&tar_table_desc, &table);
+
+ +To add a new row to the table, you must define an array of struct +osl_object of length `NUM_OT_COLUMNS` which holds the contents of +the new row. Note that an osl object is just a blob: It consists of +a data pointer and a size value. Once the array has been initialized, +pass it to `osl_add_row()` together with the table handle obtained from +`osl_open_table()`: + +
+	struct osl_object objs[NUM_OT_COLUMNS];
+	/* ...init the array... */
+	ret = osl_add_row(table, objs);
+
+ +Close the table with `osl_close_table()`. + +
+	osl_close_table(table, OSL_MARK_CLEAN);
+
+ +The storage type of both columns of the table in this example is +`OSL_MAPPED_STORAGE`, so you can later open the table again and +retrieve its contents: + +
+	ret = osl_get_row(table, OTC_NAME, &obj, &row);
+	if (ret < 0) {
+		fprintf(stderr, "osl_get_row(%s): %s\n", name,
+			osl_strerror(-ret));
+		return ret;
+	}
+	ret = osl_get_object(table, row, OTC_DATA, &obj);
+
+ +The call to `osl_get_row()` uses the rbtree of the `OTC_NAME` +column to find the row whose object in the `OTC_NAME` column +matches the given object `obj`. If a row was found, it is +passed to `osl_get_object()` which returns the object of +the `OTC_DATA` column of this row. This concludes the quick start document. Of course, libosl contains many more public functions than those used above. For details on the -C-API, look at the file \ref osl.h which contains the declarations of -all public functions and the complete documentation of the public part -of the library. +C-API, look at the file `osl.h` which contains the declarations of +all public functions and the complete documentation of the public +part of the library. The "examples" subdirectory of the source distribution contains the full code of the above example and another -small program which illustrates the use of columns of -type OSL_NO_STORAGE. Larger applications using libosl are paraslash, a network audio -streaming system, and adu -, the advanced disk usage tool. - -*/ +small program which illustrates the use of columns of type +`OSL_NO_STORAGE`. Larger applications using libosl are paraslash, +a network audio streaming system, and adu, the advanced +disk usage tool. diff --git a/web/Doxyfile b/web/Doxyfile index 5e69f3c..37ea597 100644 --- a/web/Doxyfile +++ b/web/Doxyfile @@ -766,7 +766,6 @@ INPUT_ENCODING = UTF-8 FILE_PATTERNS = osl.h \ osltar.c \ - QUICK_START # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. diff --git a/web/header.html b/web/header.html index 2f824d9..f81f793 100644 --- a/web/header.html +++ b/web/header.html @@ -33,7 +33,7 @@ [README] [Download] [INSTALL] - [Quick Start] + [Quick Start] [API] [License] [Contact] diff --git a/web/index.html.in b/web/index.html.in index 359772f..e783e7f 100644 --- a/web/index.html.in +++ b/web/index.html.in @@ -25,7 +25,7 @@ [README] [Download] [INSTALL] - [Quick Start] + [Quick Start] [API] [License] [Contact] @@ -86,6 +86,16 @@
+
+

+ QUICK START +

+
+ + @QUICK_START@ + +
+

License