From 5c50be33b86ec1b30ec52631d633c026546da23c Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Fri, 25 Apr 2014 11:39:03 +0100 Subject: [PATCH] Add to git. --- .cvsignore | 1 + Makefile+ | 68 ++++++++++++++++++ README | 24 +++++++ cdoc | 235 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ configure | 66 +++++++++++++++++ 5 files changed, 394 insertions(+) create mode 100644 .cvsignore create mode 100644 Makefile+ create mode 100644 README create mode 100755 cdoc create mode 100755 configure diff --git a/.cvsignore b/.cvsignore new file mode 100644 index 0000000..1964f99 --- /dev/null +++ b/.cvsignore @@ -0,0 +1 @@ +build-* \ No newline at end of file diff --git a/Makefile+ b/Makefile+ new file mode 100644 index 0000000..1320694 --- /dev/null +++ b/Makefile+ @@ -0,0 +1,68 @@ +# -*- Makefile -*- +# +# This is a make+ file. Make+ is a set of scripts which enhance GNU +# make and let you build RPMs, and other package types with just one +# control file. To build this package you will need to download make+ +# from this site: http://www.annexia.org/freeware/makeplus/ + +PACKAGE := cdoc +VERSION_MAJOR := 0 +VERSION_MINOR := 9.7 +VERSION := $(VERSION_MAJOR).$(VERSION_MINOR) + +SUMMARY := Simple documentation tool for C programs and libraries. +COPYRIGHT := GNU GPL +AUTHOR := Richard W.M. Jones + +define DESCRIPTION +cdoc is a simple documentation tool for C programs and libraries. It +takes inline embedded comments and turns them into manual pages. It +needs Perl to run. +endef + +RPM_REQUIRES := perl +RPM_GROUP := Development/Building + +all: build + +configure: + $(MP_CONFIGURE_START) + $(MP_CONFIGURE_END) + +build: + +test: + +install: + install -d $(DESTDIR)$(bindir) + install -m 0755 $(srcdir)/cdoc $(DESTDIR)$(bindir) + +define WEBSITE +<% include page_header.msp %> + +

cdoc - $(SUMMARY)

+ +

+$(DESCRIPTION) +

+ +

Download

+ + + +<% include page_footer.msp %> +endef + +upload_website: + scp $(PACKAGE)-$(VERSION).tar.gz $(PACKAGE)-$(VERSION)-1.*.rpm \ + $(PACKAGE)-$(VERSION).bin.tar.gz \ + 10.0.0.248:annexia.org/freeware/$(PACKAGE)/ + scp index.html \ + 10.0.0.248:annexia.org/freeware/$(PACKAGE)/index.msp + +.PHONY: build configure test upload_website diff --git a/README b/README new file mode 100644 index 0000000..729daaa --- /dev/null +++ b/README @@ -0,0 +1,24 @@ +cdoc is a perldoc-like documentation tool for C. + +It is very simple to use. Basically you just need to add the following +in front of your function prototypes in header files: + +/* Function: foo - foobar a baz + * Function: foo_p + * + * The @code{foo} function foobars a baz. It takes one parameter, the + * pointer to the @code{baz} structure. + * + * @code{foo_p} returns true if the parameter @code{baz} has been foobarred. + * + * See also: @ref{baz(3)}, @ref{frobnicate(3)}. + */ +extern void foo (baz *); +extern int foo_p (baz *); + +More advanced examples of the syntax can be found in the c2lib, pthrlib +and other packages at http://www.annexia.org/freeware/ + +To turn your header files into manpages, type: cdoc *.h + +It was written by Richard W.M. Jones (rich@annexia.org). diff --git a/cdoc b/cdoc new file mode 100755 index 0000000..b327e55 --- /dev/null +++ b/cdoc @@ -0,0 +1,235 @@ +#!/usr/bin/perl -w +# -*- cperl -*- + +# cdoc - generate man pages for C code +# Copyright (C) 2000 Bibliotech Ltd., Unit 2-3, 50 Carnwath Road, +# London, SW6 3EG, United Kingdom. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +# $Id: cdoc,v 1.4 2001/02/16 17:02:15 rich Exp $ + +use strict; + +my $arg; + +my $date = `date +'%B %d, %Y'`; +$date =~ s/[\r\n]+$//; + +my $author; +my $version; +my $license; + +while ($arg = shift @ARGV) + { + my ($type, $header_file); + + if ($arg eq "--help" || $arg eq "-?" || $arg eq "-h") + { + print STDERR + "cdoc [--options ...] files ...\n", + "Options are:\n", + " --author \"Author name\" Details for the AUTHOR section\n", + " --version package-version Details for the VERSION section\n", + " --license \"License data\" Details for the LICENSE section\n"; + exit 1; + } + elsif ($arg eq "--author") + { + $author = shift @ARGV; + next; + } + elsif ($arg eq "--version") + { + $version = shift @ARGV; + next; + } + elsif ($arg eq "--license") + { + $license = shift @ARGV; + next; + } + elsif ($arg =~ /(.*)\.h$/) + { + header: + $type = "header file"; + $header_file = $1; + open FILE, "<$arg" + or die "$arg: cannot open file: $!"; + } + else + { + print STDERR "$arg: unknown file type: assuming it's a header file"; + goto header; + } + + while () + { + s/[\n\r]+$//; + + # Look for intro line. + if (m(^\s*/\*\s*(Function|Variable):\s*(.*?)\s+-\s+(.*))o) + { + my $manpage = $2; + my $name_text = $3; + + my @functions = (); + push @functions, { name => $manpage }; + + my $description = ""; + my $bugs = ""; + my $history = ""; + my $see_also = ""; + my $returns = ""; + my $section = \$description; + + # Read the rest of the comment block. + while () + { + s/[\n\r]+$//; + s/^\s*\*\s*//; # Remove leading " * ". + + last if m(^/)o; # End of comment block? + + if (m(^(Function|Variable):\s*(.*))o) + { + push @functions, { name => $2 }; + } + elsif (m(^Bugs:\s*(.*))o) + { + $section = \$bugs; + $$section .= $1 . " "; + } + elsif (m(^History:\s*(.*))o) + { + $section = \$history; + $$section .= $1 . " "; + } + elsif (m(^See also:\s*(.*))o) + { + $section = \$see_also; + $$section .= $1 . " "; + } + elsif (m(^Returns:\s*(.*))o) + { + $section = \$returns; + $$section .= $1 . " "; + } + elsif (m/^\s*$/) + { + $$section .= "\n"; + } + else + { + $$section .= $_; + $$section .= " "; + } + } + + # Mark up the sections. + $description = mark_up ($description); + $bugs = mark_up ($bugs); + $history = mark_up ($history); + $see_also = mark_up ($see_also); + $returns = mark_up ($returns); + + # Read the functions which should follow, one per line, in order. + my $fn; + foreach $fn (@functions) + { + $_ = ; + + if (!$_ || !m($fn->{name})) + { + print STDERR "$arg: could not find prototype of variable/function: $fn->{name}\n"; + exit 1; + } + + s/[\n\r]+$//; + s/^extern\s+//; + $fn->{prototype} = $_; + } + + # Now we're in a situation to produce the manual page. + print "cdoc: creating $manpage.3\n"; + + open MANPAGE, ">$manpage.3" + or die "$manpage.3: cannot open file: $!"; + + my $names = join ", ", map { $_->{name} } @functions; + + print MANPAGE + ".TH $manpage 3 \"$date\" \"GNU\" \"Programmer's Manual\"\n", + ".SH NAME\n", + "$names \\- $name_text\n", + ".SH SYNOPSIS\n", + ".nf\n", + ".B #include <$header_file.h>\n", + ".sp\n"; + + foreach (@functions) + { + print MANPAGE ".BI \"$_->{prototype}\"\n"; + } + + print MANPAGE + ".fi\n", + ".SH DESCRIPTION\n", + "$description\n"; + + print MANPAGE ".SH RETURNS\n$returns\n" if $returns; + print MANPAGE ".SH BUGS\n$bugs\n" if $bugs; + print MANPAGE ".SH AUTHOR\n$author\n" if $author; + print MANPAGE ".SH LICENSE\n$license\n" if $license; + print MANPAGE ".SH VERSION\n$version\n" if $version; + print MANPAGE ".SH HISTORY\n$history\n" if $history; + print MANPAGE ".SH SEE ALSO\n$see_also\n" if $see_also; + + close MANPAGE; + + # Links for other pages. + my @other_pages = @functions; + shift @other_pages; + + foreach $fn (@other_pages) + { + print "cdoc: creating $fn->{name}.3\n"; + + open MANPAGE, ">$fn->{name}.3" + or die "$fn->{name}.3: cannot open file: $!"; + + print MANPAGE + ".so man3/$manpage.3\n"; + + close MANPAGE; + } + } + } + + close FILE; + } + +exit; + +sub mark_up + { + local $_ = shift; + + s/\n/\n.PP\n/ogs; + s/\@code{(.*?)}/\\fB$1\\fP/ogs; + s/\@ref{(.*?)}/\\fB$1\\fP/ogs; # Should be able to handle this better. XXX + + return $_; + } diff --git a/configure b/configure new file mode 100755 index 0000000..04d9db0 --- /dev/null +++ b/configure @@ -0,0 +1,66 @@ +#!/bin/sh - +# +# This is make+. Make+ is a set of scripts which enhance GNU make and +# let you build RPMs, and other packages types with just one control +# file. Read more at http://www.annexia.org/freeware/makeplus/ +# +# The original author is Richard W.M. Jones . +# +# This software has been explicitly placed in the PUBLIC DOMAIN. You +# do not need any sort of license or agreement to use or copy this +# software. You may also copyright this software yourself, and/or +# relicense it under any terms you want, at any time and at no cost. +# This allows you (among other things) to include this software with +# other packages so that the user does not need to download and +# install make+ separately. + +mp_options="" + +usage () +{ + cat <