--- sh.scpp 2004/01/01 16:54:20 1.25
+++ sh.scpp 2004/02/12 16:06:27 1.26
@@ -1,7 +1,6 @@
##
## scpp -- Sharing C Pre-Processor
## Copyright (c) 1999-2004 Ralf S. Engelschall <rse@engelschall.com>
-## Originally written for GNU Pth
##
## This file is part of shtool and free software; you can redistribute
## it and/or modify it under the terms of the GNU General Public
@@ -247,3 +246,157 @@
rm -f $output
rm -f $tmpfile $tmpfile.* >/dev/null 2>&1
+shtool_exit 0
+
+##
+## manual page
+##
+
+=pod
+
+=head1 NAME
+
+B<shtool scpp> - B<GNU shtool> C source file pre-processor
+
+=head1 SYNOPSIS
+
+B<shtool scpp>
+[B<-v>|B<--verbose>]
+[B<-p>|B<--preserve>]
+[B<-f>|B<--filter> I<filter>]
+[B<-o>|B<--output> I<ofile>]
+[B<-t>|B<--template> I<tfile>]
+[B<-M>|B<--mark> I<mark>]
+[B<-D>|B<--define> I<dname>]
+[B<-C>|B<--class> I<cname>]
+I<file> [I<file> ...]
+
+=head1 DESCRIPTION
+
+This command is an additional ANSI C source file pre-processor for sharing
+cpp(1) code segments, internal variables and internal functions. The intention
+for this comes from writing libraries in ANSI C. Here a common shared internal
+header file is usually used for sharing information between the library
+source files.
+
+The operation is to parse special constructs in I<file>s, generate a few
+things out of these constructs and insert them at position I<mark> in I<tfile>
+by writing the output to I<ofile>. Additionally the I<file>s are never touched
+or modified. Instead the constructs are removed later by the cpp(1) phase of
+the build process. The only prerequisite is that every I<file> has a
+``C<#include ">I<ofile>C<">'' at the top.
+
+This command provides the following features: First it avoids namespace
+pollution and reduces prototyping efforts for internal symbols by recognizing
+functions and variables which are defined with the storage class identifier
+``I<cname>''. For instance if I<cname> is ``intern'', a function ``C<intern
+void *foobar(int quux)>'' in one of the I<file>s is translated into both a
+``C<#define foobar __foobar>'' and a ``C<extern void *foobar(int quux);>'' in
+I<ofile>. Additionally a global ``C<#define> I<cname> C</**/>'' is also
+created in I<ofile> to let the compiler silently ignore this additional
+storage class identifier.
+
+Second, the library source files usually want to share C<typedef>s,
+C<#define>s, etc. over the source file boundaries. To achieve this one can
+either place this stuff manually into I<tfile> or use the second feature of
+B<scpp>: All code in I<file>s encapsulated with ``C<#if >I<dname> ...
+C<#endif>'' is automatically copied to I<ofile>. Additionally a global
+``C<#define> I<dname> C<0>'' is also created in I<ofile> to let the compiler
+silently skip this parts (because it was already found in the header).
+
+=head1 OPTIONS
+
+The following command line options are available.
+
+=over 4
+
+=item B<-v>, B<--verbose>
+
+Display some processing information.
+
+=item B<-p>, B<--preserve>
+
+Preserves I<ofile> independent of the generated ``#line'' lines. This is
+useful for Makefiles if the real contents of I<ofile> will not change,
+just line numbers. Default is to overwrite.
+
+=item B<-f>, B<--filter> I<filter>
+
+Apply one or more pre-processing sed(1) I<filter> commands (usually of
+type ``C<s/.../.../>'') to each input file before their input is parsed.
+This option can occur multiple times.
+
+=item B<-o>, B<--output> I<ofile>
+
+Output file name. Default is C<lib.h>.
+
+=item B<-t>, B<--template> I<tfile>
+
+Template file name. Default is C<lib.h.in>.
+
+=item B<-M>, B<--mark> I<mark>
+
+Mark to be replaced by generated constructs. Default is C<%%MARK%%>.
+
+=item B<-D>, B<--define> I<dname>
+
+FIXME. Default is C<cpp>.
+
+=item B<-C>, B<--class> I<cname>
+
+FIXME. Default is C<intern>.
+
+=back
+
+=head1 EXAMPLE
+
+ # Makefile
+ SRCS=foo_bar.c foo_quux.c
+ foo_p.h: foo_p.h.in
+ shtool scpp -o foo_p.h -t foo_p.h.in \
+ -M %%MARK%% -D cpp -C intern $(SRCS)
+
+ /* foo_p.h.in */
+ #ifndef FOO_P_H
+ #define FOO_P_H
+ %%MARK%%
+ #endif /* FOO_P_H */
+
+ /* foo_bar.c */
+ #include "foo_p.h"
+ #if cpp
+ #define OURS_INIT 4711
+ #endif
+ intern int ours;
+ static int myone = 0815;
+ intern int bar(void)
+ {
+ ours += myone;
+ }
+
+ /* foo_quux.c */
+ #include "foo_p.h"
+ int main(int argc, char *argv[])
+ {
+ int i;
+ ours = OURS_INIT
+ for (i = 0; i < 10; i++) {
+ bar();
+ printf("ours now %d\n", ours);
+ }
+ return 0;
+ }
+
+=head1 HISTORY
+
+The B<GNU shtool> B<scpp> command was originally written by Ralf S.
+Engelschall E<lt>rse@engelschall.comE<gt> in 1999 for B<GNU shtool>.
+Its was prompted by the need to have a pre-processing facility
+in the B<GNU pth> project.
+
+=head1 SEE ALSO
+
+shtool(1), cpp(1).
+
+=cut
+
|
