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.

diff --git a/build/Makebottom b/build/Makebottom
index 92bc47eab91ca65df7d7395418843610d5a0572c..f53b1f7961c7a8b144bcf0cbf525e5537a07be89 100644 (file)
--- a/build/Makebottom
+++ b/build/Makebottom
@@ -16,6 +16,7 @@ programs: $(PROGS)
 datafiles: $(DATAFILES)
 tests: $(TESTS)
 configs: $(addprefix run/$(CONFIG_DIR)/,$(CONFIGS))
+docs: runtree $(DOCS)
 
 tags:
        etags `find . -name "*.[ch]"`
@@ -191,6 +192,15 @@ $(DATAFILES): $(o)/%: $(s)/%
        $(Q)cp $^ $@
        $(Q)$(call symlink,$@,run/$(DATADIR))
 
+# Rules for documentation
+$(o)/%.html: $(o)/%.txt
+       $(M)"AD $< -> $@"
+       $(Q)asciidoc $<
+
+$(o)/%.txt: $(s)/%.txt
+       $(M)"ED $< -> $@"
+       $(Q)$(s)/build/extract-doc.pl $< $@ $(o)/depend.new $(s)
+
 # Default installation target
 
 default-install:

diff --git a/build/Maketop b/build/Maketop
index 5981decfaad774618f3545c285875f65eb450fe3..23d1510adab80077441c93ca042bacb8c3fc6e6b 100644 (file)
--- a/build/Maketop
+++ b/build/Maketop
@@ -72,6 +72,9 @@ distclean:: clean
 testclean::
        rm -f `find obj -name "*.test"`
 
+docclean::
+       rm -f $(DOCS) $(patsubst %.html,%.txt,$(DOCS))
+
 # Extra default rules (appended to by submakefiles)
 extras::
 

diff --git a/build/extract-doc.pl b/build/extract-doc.pl
new file mode 100755 (executable)
index 0000000..5f5280d
--- /dev/null
+++ b/build/extract-doc.pl
@@ -0,0 +1,91 @@
+#!/usr/bin/perl
+use strict;
+use warnings;
+
+my( $inname, $outname, $depname, $basedir ) = @ARGV;
+if( defined $inname ) {
+       open IN, $inname or die "Could not read $inname ($!)\n";
+} else {
+       open IN, "<&STDIN" or die "Could not read stdin ($!)\n";
+}
+if( defined $outname ) {
+       open OUT, ">$outname" or die "Could not write $outname ($!)\n";
+} else {
+       open OUT, ">&STDOUT" or die "Could not write to stdout ($!)\n";
+}
+my $hasdep;
+if( defined $depname ) {
+       open DEP, ">>$depname" or die "Could not write $depname ($!)\n";
+       $hasdep = 1;
+}
+
+print DEP "$outname:" if( $hasdep );
+
+sub process( $ ) {
+       my $file = shift;
+       open FILE, $file or die "Could nod read $file ($!)\n";
+       my $line;
+       my $active;
+       my $verbatim;
+       my $buff;
+       my $head;
+       while( defined( $line = <FILE> ) ) {
+               chomp $line;
+               if( $verbatim ) {
+                       if( $line =~ /\*\// ) {
+                               $verbatim = 0;
+                       } else {
+                               $line =~ s/^\s*\* ?//;
+                               print OUT "$line\n";
+                       }
+               } elsif( $active ) {
+                       if( $line =~ /END\*\// ) {
+                               print OUT "$buff\n";
+                       } elsif( $line =~ /\*\// ) {
+                               $active = 0;
+                       } else {
+                               $line =~ s/^\s*\* ?//;
+                               $line =~ s/^\s*$/+/;
+                               $buff .= "$line\n";
+                       }
+               } else {
+                       if( ( $line =~ /\S/ ) && ( defined $buff ) ) {
+                               chomp $line;
+                               $line =~ s/^\s*//;
+                               $line =~ s/\/\/.*//;
+                               $head .= "\n$line";
+                               if( $head =~ /;/ ) {
+                                       $head =~ s/\/\*.*?\*\///gs;
+                                       $head =~ s/\s+/ /g;
+                                       $head =~ s/;.*/;/;
+                                       print OUT "- + +++$head+++ +\n+\n$buff\n";
+                                       $head = undef;
+                                       $buff = undef;
+                               }
+                       } elsif( $line =~ /\/\*VERBATIM/ ) {
+                               $verbatim = 1;
+                       } elsif( $line =~ /\/\*DOC/ ) {
+                               $active = 1;
+                       }
+               }
+       }
+       close FILE;
+}
+
+my $line;
+while( defined( $line = <IN> ) ) {
+       chomp $line;
+       if( my( $fname ) = ( $line =~ /^!!\s*(.*\S)/ ) ) {
+               $fname = "$basedir/$fname" if( ( $fname !~ /^\// ) && defined $basedir );
+               process( $fname );
+               print DEP " $fname" if( $hasdep );
+       } else {
+               print OUT "$line\n";
+       }
+}
+
+print DEP "\n" if( $hasdep );
+
+close IN;
+close OUT;
+close DEP;

diff --git a/ucw/Makefile b/ucw/Makefile
index bd513a551ebefd0e28d3855a4b995d913e48321d..5d2ce0c2d748f2cf9279037a7740ec3a44d973df 100644 (file)
--- a/ucw/Makefile
+++ b/ucw/Makefile
@@ -68,6 +68,7 @@ include $(s)/ucw/getopt/Makefile
 endif
 
 include $(s)/ucw/sorter/Makefile
+include $(s)/ucw/doc/Makefile
 
 LIBUCW_MOD_PATHS=$(addprefix $(o)/ucw/,$(LIBUCW_MODS))
 

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
new file mode 100644 (file)
index 0000000..69146fd
--- /dev/null
+++ b/ucw/doc/Makefile
@@ -0,0 +1,5 @@
+# Makefile for the UCW GetOpt Library (c) 2007 Pavel Charvat <pchar@ucw.cz>
+
+DIRS+=ucw/doc
+
+DOCS+=$(addprefix $(o)/ucw/doc/,fastbuf.html)

diff --git a/ucw/doc/fastbuf.txt b/ucw/doc/fastbuf.txt
new file mode 100644 (file)
index 0000000..df803a0
--- /dev/null
+++ b/ucw/doc/fastbuf.txt
@@ -0,0 +1,12 @@
+Fastbufs
+========
+
+Fastbufs are stream and file abstractions. They work with normal
+files, network sockets, memory buffers or just any file descriptor. It
+should be easy to implement other types by providing functions to
+refill and read the buffer.
+
+Apart from abstraction, they are very fast.
+
+The main iclude file is +ucw/fastbuf.h+: +
+!!ucw/fastbuf.h

diff --git a/ucw/fastbuf.h b/ucw/fastbuf.h
index 07e893f17917af5e694b99381a44b99c64a7a4ce..4fb02bb6b9ac3b6658992ee42aa2cf6645ab2183 100644 (file)
--- a/ucw/fastbuf.h
+++ b/ucw/fastbuf.h
@@ -94,8 +94,18 @@ struct cf_section;
 extern struct cf_section fbpar_cf;
 extern struct fb_params fbpar_def;
 
+/*DOC
+ * Opens a file.
+ */
 struct fastbuf *bopen_file(const char *name, int mode, struct fb_params *params);      /* Use params==NULL for defaults */
-struct fastbuf *bopen_file_try(const char *name, int mode, struct fb_params *params);
+/*DOC
+ * Tries to open a file (does not die, if it isn't sucessful).
+ */
+struct fastbuf /*BLAXLA*/ *bopen_file_try(const /*BAX*/ char *name, int mode, struct fb_params *params);
+/*DOC
+ * Opens a temporary file.
+ * It is placed with other temp filenames and deleted when closed.
+ */
 struct fastbuf *bopen_tmp_file(struct fb_params *params);
 struct fastbuf *bopen_fd_name(int fd, struct fb_params *params, const char *name);
 static inline struct fastbuf *bopen_fd(int fd, struct fb_params *params)