Some sherlock independent docs put into libucw

The originals are kept in place, need to decide what to do with them.

Made translatable by asciidoc

ucw docs: Mempool examples

Added three examples of how a mempool can be used:
* string trie
* rollback an action which may fail
* loading whole stdin

Doc. system: fix makefile, docs is phony target

Doc. system: fix build in libsonly distribution

For some reason, the DOCDIR variable did not work in runtree generation,
had to move it above it.

Doc. system: link docs under run directory

They are divided into modules, stored in run/doc/modulename. Only ucw
module exists now.

ucw docs: Mempool struct internals are private

Tells the user not to dig inside.

ucw docs: fix language error

Formatted has two "t"s.

ucw docs: fix language error

Monospace, not monoscope

Renamed cf_write_item() to cf_modify_item().

The old name was somewhat counter-intuitive.

More play: Added indirect heapsort.

Just for fun: Added heapsort to the sorting benchmark.

Forgot to adapt retros.c to the new MD5 interface.

Fix the fix of compilation

The LIKE_MALLOC flag should not be in the middle of return type.

Fix compilation after writing docs

TODO about documentation

ucw docs: Documented mempools

There were many comments in the header file, reusing them,
adding only a little bit and reformatting.

ucw docs: Some more in conf system

Documented something about loading the configuration by functions in
ucw/getopt.h.

Doc. system: Properly extract multiline definitions

Doc. system: escape apostrophes in def list

Asciidoc takes 'quoted' text as italic. Escape when part of the
definition.

ucw docs: preprocess conf.h

Reused some comments in ucw/conf.h for documentation, created structure
in the file. Some things still need to be documented in this header
file.

Doc. system: fix detection of pointer variables

The * before variable name stopped it from matching.

Doc. system: detect function typedefs

things like
typedef function(void)
were considered functions, not types.

Doc. system: stop pointer marks from boldifying

Sometimes two pointer asterisks in the definition made some part of it
bold, removing the asterisks. Escape them all.

ucw docs: configuration parser (example)

Just an example how to use it. The thorough documentation of the headers
and functions to follow.

Document the documentation system syntax

Maybe put it to a better place?

Doc. system: add support for typedefs

And a little cleanup/code compression at the occasion.

ucw docs: hashfunc reflects the syntax change

ucw docs: basecode reflects the syntax change

ucw docs: fastbufs reflect the syntax change

Change function() to @function() when a link should be created.

Doc. system: use @function() for function links

<<function()>> works too, this is just replacement of the old implicit
function(), which caused problems (the system wanted to put the links
everywhere).

Removed some hacks around the old problems, which are no longer needed.

ucw docs: fix function quoting

Merge branch 'dev-lib' of ssh://git.ucw.cz/projects/sherlock/GIT/sherlock into dev-lib

ucw. docs: Update hash documentation

More info about non-crypto hashes
Better links inside the page

Doc. system: Fix inline functions in description

They had { }, if it was on the first line.

Simpler handling of definitions.

Doc. system: deflists have different formatting

The asciidoc definition lists are used, the items are aligned in two
columns.

CGI.pm: More improvements to the cookie mechanism.

I am trying to make the parameters as close as possible to the
new standard (they make better sense and I want to keep the function
compatible with older versions of CGI.pm).

It also handles options with no values more gracefully.

CGI.pm: Cope with corrupted cookie headers.

Doc. system: Add type sections to definition list

The definitions, grouped by type, have section captions (Enums, Structs,
etc).

Doc. system: Definition list has visible name

The link is just the symbol name, the one-line header is bellow it now.

Doc. system: fix semicolons

They were sometimes missing at the end of one-line headers.

Doc. system: No body to func. header

Do not include body of inline functions even if the body is in the
single line.

Doc. system: use better anchors

The anchor names are based on the name and type of identifier, not a
dull nothing telling number.

Doc. system: fix ... in function parameters

Asciidoc tries to convert all ... strings into ellipsis character, which
is wrong in function parameters (it is 3 separate chars in reality,
besides this caused problems with xrefs, links, etc).

Merge branch 'dev-lib' of ssh://git.ucw.cz/projects/sherlock/GIT/sherlock into dev-lib

CGI.pm: Make cookie setting headers backwards-compatible.

Merge branch 'dev-lib' of ssh://git.ucw.cz/projects/sherlock/GIT/sherlock into dev-lib

Doc. system: depend on build scripts

So when a script or configuration changes, all parts of documentation
are updated.

CGI.pm: Export URL and parameter de-escaping functions.

ucw docs: more hash functions

I will add more when I find where they live

A couple of fixes to hash function documentation.

Doc. system: recognize typedefs of structs

Recognize patterns like this as a struct. Similar for enum.

typedef struct {
  something;
} name;

ucw docs: Hash routines

MD5 and SHA1 hashes.

ucw docs: update basecode

ASCII is only 7bits, this uses all 8.
Referencing a comment at the top of .c file.

Doc. system: fix definition duplicities

They were caused by appending to a deflist instead of overwriting. If
the original file was changed and documentation recompiled, new
definitions were added to the old ones.

ucw docs: base64 & base224

Documentation of base64 and base224 encoding. Describes the basecode
utility as well.

Merge branch 'dev-lib' of ssh://git.ucw.cz/projects/sherlock/GIT/sherlock into dev-lib

Doc. systems: definitions are grouped by type

They are grouped together by type. First are enums and structs, then
functions, then variables and preprocessor defines go last.

Doc. system: typo in warn message

b224 is deprecated by basecode

Move ucw utils to subdirectory

Doc. system: definitions are sorted

According to the symbol name.

Doc. system: export type and name do deflists

Doc. system: fix semicolon handling

No need for the hack in extracting loop, now put into formatting.

Fix the regexp in formatting part.

Doc. system: detect type of definition

Just heuristics, detects type of the symbol and the name of the symbol.

It is used to add semicolon to inline functions what do not have one,
but more use of the detection is expected.

ucw. docs: update to use doc. system features

* Automatic formatting of NULL
* use `word` instead of +word+
* use <<links>> instead of xrefs

UCW docs: split definitions off the main index

Doc. system: fix function anchors

Only last character of their name was used to create the anchor.

Moved some utils from utils/ to ucw/

Some of the utilities do not need sherlock (and are not anyhow related
to it), so they were moved to libucw:

    * b224 (base224 encoder/decoder)
    * daemon-helper (replacement for start-stop-daemon)
    * hex (hex dumper)
    * rotate-log (log rotator)
    * urltool (url manipulating tool)

Introduced a CONFIG_UCW_UTILS config switch which controls compilation
of these utilities.

Originally by Michal, with minor changes by MJ:

    * basecode.test is added to TESTS only if CONFIG_UCW_UTILS is set.
    * Changed the order of Makefile sections and Set statements to
      a more logical one.

Doc. system: Hack around Makefile inexpressiveness.

Doc. system: Renamed doc utilities to match local conventions.

First, we do not use filename extensions for scripts which are not "compiled"
(e.g., the scripts that are a part of the build system).

Second, we prefer to build the naming hierarchy from the opposite end.

Doc. system: Make doc target messages more similar to the others.

Doc. system: Avoid ":=" rules in makefiles.

Fixed a typo: indeces -> indices.

libucw documentation: index

Lists modules and definitions

Doc. system: build rules for indeces and deflists

Doc system: build system for deflists and indeces

Makefile rules for building documentation indeces

Doc. system: dependencies bug

They should be appended, not overwritten, this would trash all previous
dependencies

Doc. system: fix deflist asciidoc formatting

Collisions with automatic function references
Disallowed characters in captions which were needed

Doc. system: definition list formatter

Doc. system: links to files without anchors

<<filename:>> and <<filename:,caption>>

Doc. system: file names with more chars allowed

Filenames in <<file:id>> referencies could not contain characters like
'/' or '.'. Now they can contain quite anything.

Documentation system: teach extractor dump defs

If provided with another file name, it dumps all definitions with
filename, id number and text

Documentation system: @word@ is not func. param.

So leave it as is

Documentation: keep ; at the end of functions

And replace { at the end of inline functions with ;

Add a description of extract-doc.pl script

Documentation system: file xrefs

<<file:link>> and <<file:link,text>> links to other files work now.

Documentation system: null-macro not needed

It is done by replacement, no need for a macro definition

Documentation system: <<f()>> links

The <:f()> function links were replaced by ones more similar to existing
cross-reference links.

<<f(params)>> -- link to function
<<f(params),text>> -- with user-provided link text
<<file:f(params)>>,<<file:f(params),text>> -- link to a function in
  different file

Furtheremore, the documentation config was split into backend specific
(xhtml at this moment only) and backend independent parts.

Doc: NULL is now detected and typeset properly.

Less complicated syntax of function references

<file:function(params)>
<file:function(params):link text>
<:funciton(params)>
<:function(params):link text>

NULL detection (turned to be <tt>ed)

Configure: Fixed a bug in error handling.

Update documentation of fastbufs.

The back-ends should be fully covered now, the front-ends still remain
documented very sparsely.

Documentation of fb-atomic has been moved from the source to the header
file and asciidoc'ed.

I have also added a simple menu with links to all sections.

Documentation system: manual function links

Things like this now works
>>f>:function(parameters)<<< - link to function in local file
>>f>:function(parameters):custom link text<<< - similar, named
>>f>file:function(parameters)<<< - into different file
>>f>file:function(parameters):custom text<<<

File is written without suffix (eg. no file.html, just file).

Documentation system: generate anchors/ids for functions

When a function documentation is found, a fun_name_of_the_function
anchor (id html attribute) is added to it so links can jump there.

Documentation system: detect functions by name()

Functions are detected, set in <tt> font and turned to links.

Libucw: Documentation of more fastbuf headers.

Libucw: documentation of fastbuf.h

Documentation system: Structures are input verbatim.

Enhanced documentation system.

Comments are now

/**
 * Function comment.
 **/
void function(void);

or void function(void); /** Function comment **/

/***
 * Verbatim comment.
 ***/

or /*** Verbatim comment ***/

@param marks a function parameter.

It understands structures (to level 1, nested functions are flattened.
Is it needed?).

Created documentation system.

`make docs' compiles documentation.

It uses asciidoc and is enriched by taking data directly from source code.
Some tests are done with ucw/doc/fastbuf.txt and ucw/fastbuf.h.

Created documentation is saved into the obj dir.