X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;ds=sidebyside;f=ucw%2Fdoc%2Fdocsys.txt;h=b855749acea7e02c158d1cf108724bcbb41e7089;hb=dbe3b315edac25079fcbfe4df20e80b534f2a7a1;hp=40789d6cdbbc32b06bbdf9c6a85116c2bd600690;hpb=c276c5a388203611d78a7d5a942b3657737c5b11;p=libucw.git

diff --git a/ucw/doc/docsys.txt b/ucw/doc/docsys.txt
index 40789d6c..b855749a 100644
--- a/ucw/doc/docsys.txt
+++ b/ucw/doc/docsys.txt
@@ -4,7 +4,7 @@ The documentation system
 ////
 Warning: if you read this file in plain-text, keep in mind the markup
 had to be escaped to show in the result as the thing you should type.
-You should ignore all backspaces here, or better, read the html
+You should ignore all backslashes here, or better, read the html
 version.
 ////
 
@@ -12,6 +12,16 @@ The ucw documentation system is based on the
 http://www.methods.co.nz/asciidoc/[ASCIIDOC] documentation formatter.
 It supports all it's markup, but it was extended slightly.
 
+- <<markup,Markup extensions>>
+  * <<xrefs,Cross referencing>>
+  * <<symbols,Symbol formatting>>
+- <<extract,Header extraction>>
+  * <<scomm,Stand-alone comments>>
+  * <<defcomm,Definition comments>>
+- <<generics,Macro generics>>
+  * <<geext,Generics extraction>>
+  * <<gelink,Links to generics>>
+
 [[markup]]
 Markup extensions
 -----------------
@@ -36,16 +46,16 @@ Just write `\<<function(),caption>>` or
 Symbol formatting
 ~~~~~~~~~~~~~~~~~
 If you talk about function parameter, prefix its name with `@`. It
-will be typeset in monoscope italic font to mark it visually, like
+will be typeset in monospace italic font to mark it visually, like
 this: @parameter.
 
 If a word is suffixed by parenthesis without a space (eg. word()), it
-is considered to be a function name and is typeset in monoscope font.
+is considered to be a function name and is typeset in monospace font.
 
 You can prefix a function name by `@`, which makes it a link to that
 function (`\@function()` is equivalent to `\<<function()>>`).
 
-If you write NULL anywhere, it is recognized and typeset in monoscope.
+If you write NULL anywhere, it is recognized and typeset in monospace.
 
 [[extract]]
 Header extraction
@@ -81,10 +91,15 @@ Definition comments
 You can write comments documenting specific definition. Definition
 comment has the asterisks doubled. The multi-line version must be
 directly above the definition, the single-line on the same line right
-of the definition.
+of the definition or on a line before.
 
  void function(int parameter);  /** This is a function. **/
 
+or
+
+ /** This is a function. **/
+ void function(int parameter);
+
 or
 
  /**
@@ -107,3 +122,47 @@ these:
 
 There is a support for building a page with list of all symbols with
 links to them. Look into `ucw/doc/Makefile` to see how to request that.
+
+[[generics]]
+Support for macro generics
+--------------------------
+
+Some of the headers contain <<generic:,macro generics>>. Since the
+preprocessor macros look somewhat weird, the documentation extractor
+needs some help to understand them.
+
+[[geext]]
+Extraction of generics
+~~~~~~~~~~~~~~~~~~~~~~
+
+When extracting info from some header, the extractor needs to know,
+which prefix macros are used in the source file, to distinguish them
+from function calls. To inform it about them, append a comma separated
+list of such macros to the extraction command, like this:
+
+  !!filename PREFIX_MACRO_ONE,PREFIX_MACRO_TWO
+
+Then this will be correctly identified as a structure:
+
+  struct PREFIX_MACRO_ONE(struct_name) {
+    content;
+  };
+
+[[gelink]]
+Links to generics
+~~~~~~~~~~~~~~~~~
+
+Since the anchors for them are generated in a complicated manner and
+typing them in plain-text would convert them back to the original,
+with real parenthesis, there is a special pattern to create the
+symbolname part of the anchor. It looks like:
+
+  _GENERIC_LINK_|PREFIX_MACRO|symbol_name|
+
+So link to the above structure would look like:
+
+  <<struct__GENERIC_LINK_|PREFIX_MACRO_ONE|struct_name|,link text>>
+
+However, this is implemented only in the included header files (if it
+is needed, it will be implemented in the top-level documentation files
+too).