Fossil SCM

Cherrypick [9b960af129], was supposed to have been checked into trunk in the first place

andygoth 2016-11-04 23:18 trunk

Commit bbafc013aa7348f836ccdbfd0c8935dafdc2b15f

Parent e5b62edb284c1e1…

1 file changed +93 -85

M src/makeheaders.html

+93 -85

		--- src/makeheaders.html
		+++ src/makeheaders.html
		@@ -4,11 +4,11 @@
4	4	<h1 align=center>The Makeheaders Program</h1>
5	5
6	6
7	7	<p>
8	8	This document describes <em>makeheaders</em>,
9		-a tool that automatically generates ``<code>.h</code>''
	9	+a tool that automatically generates “<code>.h</code>”
10	10	files for a C or C++ programming project.
11	11	</p>
12	12
13	13
14	14	<h2>Table Of Contents</h2>
		@@ -67,11 +67,11 @@
67	67	<ul>
68	68	<li> Typedefs.
69	69	<li> Structure, union and enumeration declarations.
70	70	<li> Function and procedure prototypes.
71	71	<li> Preprocessor macros and #defines.
72		-<li> ``extern'' variable declarations.
	72	+<li> “<code>extern</code>” variable declarations.
73	73	</ul>
74	74	</p>
75	75
76	76	<p>
77	77	Definitions in C, on the other hand, include these kinds of things:
		@@ -89,13 +89,13 @@
89	89	is the <em>interface</em> and the definition is the <em>implementation</em>.
90	90	</p>
91	91
92	92	<p>
93	93	In C programs, it has always been the tradition that declarations are
94		-put in files with the ``<code>.h</code>'' suffix and definitions are
95		-placed in ``<code>.c</code>'' files.
96		-The .c files contain ``<code>#include</code>'' preprocessor statements
	94	+put in files with the “<code>.h</code>” suffix and definitions are
	95	+placed in “<code>.c</code>” files.
	96	+The .c files contain “<code>#include</code>” preprocessor statements
97	97	that cause the contents of .h files to be included as part of the
98	98	source code when the .c file is compiled.
99	99	In this way, the .h files define the interface to a subsystem and
100	100	the .c files define how the subsystem is implemented.
101	101	</p>
		@@ -262,11 +262,11 @@
262	262
263	263	<p>
264	264	A similar option is -H. Like the lower-case -h option, big -H
265	265	generates a single include file on standard output. But unlike
266	266	small -h, the big -H only emits prototypes and declarations that
267		-have been designated as ``exportable''.
	267	+have been designated as “exportable”.
268	268	The idea is that -H will generate an include file that defines
269	269	the interface to a library.
270	270	More will be said about this in section 3.4.
271	271	</p>
272	272
		@@ -293,13 +293,13 @@
293	293	then you can supply an empty header filename, like this:
294	294	<pre>
295	295	makeheaders alpha.c beta.c gamma.c:
296	296	</pre>
297	297	In this example, makeheaders will scan the three files named
298		-``alpha.c'',
299		-``beta.c'' and
300		-``gamma.c''
	298	+“<code>alpha.c</code>”,
	299	+“<code>beta.c</code>” and
	300	+“<code>gamma.c</code>”
301	301	but because of the colon on the end of third filename
302	302	it will only generate headers for the first two files.
303	303	Unfortunately,
304	304	it is not possible to get makeheaders to process any file whose
305	305	name contains a colon.
		@@ -309,14 +309,14 @@
309	309	In a large project, the length of the command line for makeheaders
310	310	can become very long.
311	311	If the operating system doesn't support long command lines
312	312	(example: DOS and Win32) you may not be able to list all of the
313	313	input files in the space available.
314		-In that case, you can use the ``-f'' option followed
	314	+In that case, you can use the “<code>-f</code>” option followed
315	315	by the name of a file to cause makeheaders to read command line
316	316	options and filename from the file instead of from the command line.
317		-For example, you might prepare a file named ``mkhdr.dat''
	317	+For example, you might prepare a file named “<code>mkhdr.dat</code>”
318	318	that contains text like this:
319	319	<pre>
320	320	src/alpha.c:hdr/alpha.h
321	321	src/beta.c:hdr/beta.h
322	322	src/gamma.c:hdr/gamma.h
		@@ -327,18 +327,18 @@
327	327	makeheaders -f mkhdr.dat
328	328	</pre>
329	329	</p>
330	330
331	331	<p>
332		-The ``-local'' option causes makeheaders to
333		-generate of prototypes for ``static'' functions and
	332	+The “<code>-local</code>” option causes makeheaders to
	333	+generate of prototypes for “<code>static</code>” functions and
334	334	procedures.
335	335	Such prototypes are normally omitted.
336	336	</p>
337	337
338	338	<p>
339		-Finally, makeheaders also includes a ``-doc'' option.
	339	+Finally, makeheaders also includes a “<code>-doc</code>” option.
340	340	This command line option prevents makeheaders from generating any
341	341	headers at all.
342	342	Instead, makeheaders will write to standard output
343	343	information about every definition and declaration that it encounters
344	344	in its scan of source files.
		@@ -352,19 +352,21 @@
352	352	</p>
353	353
354	354	<p>
355	355	If you forget what command line options are available, or forget
356	356	their exact name, you can invoke makeheaders using an unknown
357		-command line option (like ``--help'' or ``-?'')
	357	+command line option (like “<code>--help</code>” or
	358	+“<code>-?</code>”)
358	359	and it will print a summary of the available options on standard
359	360	error.
360		-If you need to process a file whose name begins with ``-'',
361		-you can prepend a ``./'' to its name in order to get it
	361	+If you need to process a file whose name begins with
	362	+“<code>-</code>”,
	363	+you can prepend a “<code>./</code>” to its name in order to get it
362	364	accepted by the command line parser.
363		-Or, you can insert the special option ``--'' on the command
364		-line to cause all subsequent command line arguments to be treated as
365		-filenames even if their names beginn with ``-''.
	365	+Or, you can insert the special option “<code>--</code>” on the
	366	+command line to cause all subsequent command line arguments to be treated as
	367	+filenames even if their names begin with “<code>-</code>”.
366	368	</p>
367	369
368	370	<a name="H0006"></a>
369	371	<h2>3.0 Preparing Source Files For Use With Makeheaders</h2>
370	372
		@@ -379,30 +381,31 @@
379	381
380	382	<a name="H0007"></a>
381	383	<h3>3.1 The Basic Setup</h3>
382	384
383	385	<p>
384		-The simpliest way to use makeheaders is to put all definitions in
	386	+The simplest way to use makeheaders is to put all definitions in
385	387	one or more .c files and all structure and type declarations in
386	388	separate .h files.
387	389	The only restriction is that you should take care to chose basenames
388		-for your .h files that are different from the basenames for you
	390	+for your .h files that are different from the basenames for your
389	391	.c files.
390		-Recall that if your .c file is named (for example) ``alpha.c''
	392	+Recall that if your .c file is named (for example)
	393	+“<code>alpha.c</code>”
391	394	makeheaders will attempt to generate a corresponding header file
392		-named ``alpha.h''.
	395	+named “<code>alpha.h</code>”.
393	396	For that reason, you don't want to use that name for
394	397	any of the .h files you write since that will prevent makeheaders
395	398	from generating the .h file automatically.
396	399	</p>
397	400
398	401	<p>
399	402	The structure of a .c file intented for use with makeheaders is very
400	403	simple.
401		-All you have to do is add a single ``#include'' to the top
402		-of the file that sources the header file that makeheaders will generate.
403		-Hence, the beginning of a source file named ``alpha.c''
	404	+All you have to do is add a single “<code>#include</code>” to the
	405	+top of the file that sources the header file that makeheaders will generate.
	406	+Hence, the beginning of a source file named “<code>alpha.c</code>”
404	407	might look something like this:
405	408	</p>
406	409
407	410	<pre>
408	411	/*
		@@ -415,14 +418,14 @@
415	418
416	419	<p>
417	420	Your manually generated header files require no special attention at all.
418	421	Code them as you normally would.
419	422	However, makeheaders will work better if you omit the
420		-``#if'' statements people often put around the outside of
	423	+“<code>#if</code>” statements people often put around the outside of
421	424	header files that prevent the files from being included more than once.
422		-For example, to create a header file named ``beta.h'', many
423		-people will habitually write the following:
	425	+For example, to create a header file named “<code>beta.h</code>”,
	426	+many people will habitually write the following:
424	427
425	428	<pre>
426	429	#ifndef BETA_H
427	430	#define BETA_H
428	431
		@@ -435,11 +438,11 @@
435	438	Remember that the header files you write will never really be
436	439	included by any C code.
437	440	Instead, makeheaders will scan your header files to extract only
438	441	those declarations that are needed by individual .c files and then
439	442	copy those declarations to the .h files corresponding to the .c files.
440		-Hence, the ``#if'' wrapper serves no useful purpose.
	443	+Hence, the “<code>#if</code>” wrapper serves no useful purpose.
441	444	But it does make makeheaders work harder, forcing it to put
442	445	the statements
443	446
444	447	<pre>
445	448	#if !defined(BETA_H)
		@@ -465,11 +468,11 @@
465	468	</p>
466	469
467	470	<p>
468	471	Note that
469	472	the wildcard expression used in the above example,
470		-``<code>*.[ch]</code>'',
	473	+“<code>*.[ch]</code>”,
471	474	will expand to include all .h files in the current directory, both
472	475	those entered manually be the programmer and others generated automatically
473	476	by a prior run of makeheaders.
474	477	But that is not a problem.
475	478	The makeheaders program will recognize and ignore any files it
		@@ -489,14 +492,14 @@
489	492	<p><li>
490	493	When a function is defined in any .c file, a prototype of that function
491	494	is placed in the generated .h file of every .c file that
492	495	calls the function.</p>
493	496
494		-<P>If the ``static'' keyword of C appears at the beginning
495		-of the function definition, the prototype is suppressed.
496		-If you use the ``LOCAL'' keyword where you would normally
497		-say ``static'', then a prototype is generated, but it
	497	+<P>If the “<code>static</code>” keyword of C appears at the
	498	+beginning of the function definition, the prototype is suppressed.
	499	+If you use the “<code>LOCAL</code>” keyword where you would normally
	500	+say “<code>static</code>”, then a prototype is generated, but it
498	501	will only appear in the single header file that corresponds to the
499	502	source file containing the function. For example, if the file
500	503	<code>alpha.c</code> contains the following:
501	504	<pre>
502	505	LOCAL int testFunc(void){
		@@ -509,24 +512,26 @@
509	512	LOCAL int testFunc(void);
510	513	</pre>
511	514	However, no other generated header files will contain a prototype for
512	515	<code>testFunc()</code> since the function has only file scope.</p>
513	516
514		-<p>When the ``LOCAL'' keyword is used, makeheaders will also
515		-generate a #define for LOCAL, like this:
	517	+<p>When the “<code>LOCAL</code>” keyword is used, makeheaders will
	518	+also generate a #define for LOCAL, like this:
516	519	<pre>
517	520	#define LOCAL static
518	521	</pre>
519	522	so that the C compiler will know what it means.</p>
520	523
521		-<p>If you invoke makeheaders with a ``-local'' command-line
522		-option, then it treats the ``static'' keyword like
523		-``LOCAL'' and generates prototypes in the header file
524		-that corresponds to the source file containing the function defintiion.</p>
	524	+<p>If you invoke makeheaders with a “<code>-local</code>”
	525	+command-line option, then it treats the “<code>static</code>”
	526	+keyword like “<code>LOCAL</code>” and generates prototypes in the
	527	+header file that corresponds to the source file containing the function
	528	+definition.</p>
525	529
526	530	<p><li>
527		-When a global variable is defined in a .c file, an ``extern''
	531	+When a global variable is defined in a .c file, an
	532	+“<code>extern</code>”
528	533	declaration of that variable is placed in the header of every
529	534	.c file that uses the variable.
530	535	</p>
531	536
532	537	<p><li>
		@@ -550,12 +555,12 @@
550	555
551	556	<p><li>
552	557	When a structure, union or enumeration declaration appears in a .h
553	558	file, makeheaders will automatically
554	559	generate a typedef that allows the declaration to be referenced without
555		-the ``struct'', ``union'' or ``enum''
556		-qualifier.
	560	+the “<code>struct</code>”, “<code>union</code>” or
	561	+“<code>enum</code>” qualifier.
557	562	In other words, if makeheaders sees the code:
558	563	<pre>
559	564	struct Examp { /* ... */ };
560	565	</pre>
561	566	it will automatically generate a corresponding typedef like this:
		@@ -572,13 +577,13 @@
572	577	</ul>
573	578
574	579	<p>
575	580	As a final note, we observe that automatically generated declarations
576	581	are ordered as required by the ANSI-C programming language.
577		-If the declaration of some structure ``X'' requires a prior
578		-declaration of another structure ``Y'', then Y will appear
579		-first in the generated headers.
	582	+If the declaration of some structure “<code>X</code>” requires a
	583	+prior declaration of another structure “<code>Y</code>”, then Y will
	584	+appear first in the generated headers.
580	585	</p>
581	586
582	587	<a name="H0009"></a>
583	588	<h3>3.3 How To Avoid Having To Write Any Header Files</h3>
584	589
		@@ -611,18 +616,18 @@
611	616	<pre>
612	617	#if INTERFACE
613	618	#endif
614	619	</pre>
615	620	Thus any structure definitions that appear after the
616		-``#if INTERFACE'' but before the corresponding
617		-``#endif'' are eligable to be copied into the
	621	+“<code>#if INTERFACE</code>” but before the corresponding
	622	+“<code>#endif</code>” are eligable to be copied into the
618	623	automatically generated
619	624	.h files of other .c files.
620	625	</p>
621	626
622	627	<p>
623		-If you use the ``#if INTERFACE'' mechanism in a .c file,
	628	+If you use the “<code>#if INTERFACE</code>” mechanism in a .c file,
624	629	then the generated header for that .c file will contain a line
625	630	like this:
626	631	<pre>
627	632	#define INTERFACE 0
628	633	</pre>
		@@ -637,15 +642,15 @@
637	642	</p>
638	643
639	644	<p>
640	645	Note that you don't have to use this approach exclusively.
641	646	You can put some declarations in .h files and others within the
642		-``#if INTERFACE'' regions of .c files.
	647	+“<code>#if INTERFACE</code>” regions of .c files.
643	648	Makeheaders treats all declarations alike, no matter where they
644	649	come from.
645	650	You should also note that a single .c file can contain as many
646		-``#if INTERFACE'' regions as desired.
	651	+“<code>#if INTERFACE</code>” regions as desired.
647	652	</p>
648	653
649	654	<a name="H0010"></a>
650	655	<h3>3.4 Designating Declarations For Export</h3>
651	656
		@@ -664,11 +669,11 @@
664	669	like this, but makeheaders does.
665	670	</p>
666	671
667	672	<p>
668	673	Using makeheaders, it is possible to designate routines and data
669		-structures as being for ``export''.
	674	+structures as being for “<code>export</code>”.
670	675	Exported objects are visible not only to other files within the
671	676	same library or subassembly but also to other
672	677	libraries and subassemblies in the larger program.
673	678	By default, makeheaders only makes objects visible to other members
674	679	of the same library.
		@@ -690,14 +695,14 @@
690	695
691	696	<p>
692	697	But trouble quickly arises when we attempt to devise a mechanism for
693	698	telling makeheaders which prototypes it should export and which it should
694	699	keep local.
695		-The built-in ``static'' keyword of C works well for prohibiting
696		-prototypes from leaving a single source file, but because C doesn't
	700	+The built-in “<code>static</code>” keyword of C works well for
	701	+prohibiting prototypes from leaving a single source file, but because C doesn't
697	702	support a linkage hierarchy, there is nothing in the C language to help us.
698		-We'll have to invite our own keyword: ``EXPORT''
	703	+We'll have to invite our own keyword: “<code>EXPORT</code>”
699	704	</p>
700	705
701	706	<p>
702	707	Makeheaders allows the EXPORT keyword to precede any function or
703	708	procedure definition.
		@@ -726,15 +731,15 @@
726	731	<pre>
727	732	#if EXPORT_INTERFACE
728	733	#endif
729	734	</pre>
730	735	will become part of the exported interface.
731		-The ``#if EXPORT_INTERFACE'' mechanism can be used in either
732		-.c or .h files.
733		-(The ``#if INTERFACE'' can also be used in both .h and .c files,
734		-but since it's use in a .h file would be redundant, we haven't mentioned
735		-it before.)
	736	+The “<code>#if EXPORT_INTERFACE</code>” mechanism can be used in
	737	+either .c or .h files.
	738	+(The “<code>#if INTERFACE</code>” can also be used in both .h and
	739	+.c files, but since it's use in a .h file would be redundant, we haven't
	740	+mentioned it before.)
736	741	</p>
737	742
738	743	<a name="H0011"></a>
739	744	<h3>3.5 Local declarations processed by makeheaders</h3>
740	745
		@@ -742,11 +747,11 @@
742	747	Structure declarations and typedefs that appear in .c files are normally
743	748	ignored by makeheaders.
744	749	Such declarations are only intended for use by the source file in which
745	750	they appear and so makeheaders doesn't need to copy them into any
746	751	generated header files.
747		-We call such declarations ``private''.
	752	+We call such declarations “<code>private</code>”.
748	753	</p>
749	754
750	755	<p>
751	756	Sometimes it is convenient to have makeheaders sort a sequence
752	757	of private declarations into the correct order for us automatically.
		@@ -764,12 +769,13 @@
764	769	within
765	770	<pre>
766	771	#if LOCAL_INTERFACE
767	772	#endif
768	773	</pre>
769		-A ``LOCAL_INTERFACE'' block works very much like the
770		-``INTERFACE'' and ``EXPORT_INTERFACE''
	774	+A “<code>LOCAL_INTERFACE</code>” block works very much like the
	775	+“<code>INTERFACE</code>” and
	776	+“<code>EXPORT_INTERFACE</code>”
771	777	blocks described above, except that makeheaders insures that the
772	778	objects declared in a LOCAL_INTERFACE are only visible to the
773	779	file containing the LOCAL_INTERFACE.
774	780	</p>
775	781
		@@ -777,11 +783,12 @@
777	783	<h3>3.6 Using Makeheaders With C++ Code</h3>
778	784
779	785	<p>
780	786	You can use makeheaders to generate header files for C++ code, in
781	787	addition to C.
782		-Makeheaders will recognize and copy both ``class'' declarations
	788	+Makeheaders will recognize and copy both “<code>class</code>”
	789	+declarations
783	790	and inline function definitions, and it knows not to try to generate
784	791	prototypes for methods.
785	792	</p>
786	793
787	794	<p>
		@@ -805,20 +812,20 @@
805	812	C++ input. Makeheaders will recognize that its source code is C++
806	813	by the suffix on the source code filename. Simple ".c" or ".h" suffixes
807	814	are assumed to be ANSI-C. Anything else, including ".cc", ".C" and
808	815	".cpp" is assumed to be C++.
809	816	The name of the header file generated by makeheaders is derived from
810		-by the name of the source file by converting every "c" to "h" and
	817	+the name of the source file by converting every "c" to "h" and
811	818	every "C" to "H" in the suffix of the filename.
812	819	Thus the C++ source
813		-file ``alpha.cpp'' will induce makeheaders to
814		-generate a header file named ``alpha.hpp''.
	820	+file “<code>alpha.cpp</code>” will induce makeheaders to
	821	+generate a header file named “<code>alpha.hpp</code>”.
815	822	</p>
816	823
817	824	<p>
818	825	Makeheaders augments class definitions by inserting prototypes to
819		-methods were appropriate. If a method definition begins with one
	826	+methods where appropriate. If a method definition begins with one
820	827	of the special keywords <b>PUBLIC</b>, <b>PROTECTED</b>, or
821	828	<b>PRIVATE</b> (in upper-case to distinguish them from the regular
822	829	C++ keywords with the same meaning) then a prototype for that
823	830	method will be inserted into the class definition. If none of
824	831	these keywords appear, then the prototype is not inserted. For
		@@ -867,11 +874,11 @@
867	874	<h4>3.6.1 C++ Limitations</h4>
868	875
869	876	<p>
870	877	Makeheaders does not understand more recent
871	878	C++ syntax such as templates and namespaces.
872		-Perhaps these issued will be addressed in future revisions.
	879	+Perhaps these issues will be addressed in future revisions.
873	880	</p>
874	881
875	882	<a name="H0013"></a>
876	883	<h3>3.7 Conditional Compilation</h3>
877	884
		@@ -879,13 +886,13 @@
879	886	The makeheaders program understands and tracks the conditional
880	887	compilation constructs in the source code files it scans.
881	888	Hence, if the following code appears in a source file
882	889	<pre>
883	890	#ifdef UNIX
884		- # define WORKS_WELL 1
	891	+ # define WORKS_WELL 1
885	892	#else
886		- # define WORKS_WELL 0
	893	+ # define WORKS_WELL 0
887	894	#endif
888	895	</pre>
889	896	then the next patch of code will appear in the generated header for
890	897	every .c file that uses the WORKS_WELL constant:
891	898	<pre>
		@@ -918,12 +925,12 @@
918	925	<p>
919	926	Makeheaders does not understand the old K&R style of function
920	927	and procedure definitions.
921	928	It only understands the modern ANSI-C style, and will probably
922	929	become very confused if it encounters an old K&R function.
923		-You should take care to avoid putting K&R function defintions
924		-in your code, therefore.
	930	+Therefore you should take care to avoid putting K&R function definitions
	931	+in your code.
925	932	</p>
926	933
927	934	<p>
928	935	Makeheaders does not understand when you define more than one
929	936	global variable with the same type separated by a comma.
		@@ -993,35 +1000,35 @@
993	1000	in the code, it is not necessary to make a corresponding change
994	1001	in a separate document. Just rerun the documentation generator.
995	1002	</ul>
996	1003	The makeheaders program does not generate program documentation itself.
997	1004	But you can use makeheaders to parse the program source code, extract
998		-the information that is relavant to the documentation and to pass this
	1005	+the information that is relevant to the documentation and to pass this
999	1006	information to another tool to do the actual documentation preparation.
1000	1007	</p>
1001	1008
1002	1009	<p>
1003		-When makeheaders is run with the ``-doc'' option, it emits
1004		-no header files at all.
	1010	+When makeheaders is run with the “<code>-doc</code>” option, it
	1011	+emits no header files at all.
1005	1012	Instead, it does a complete dump of its internal tables to standard
1006		-outputs in a form that is easily parsed.
	1013	+output in a form that is easily parsed.
1007	1014	This output can then be used by another program (the implementation
1008	1015	of which is left as an exercise to the reader) that will use the
1009	1016	information to prepare suitable documentation.
1010	1017	</p>
1011	1018
1012	1019	<p>
1013		-The ``-doc'' option causes makeheaders to print information
1014		-to standard output about all of the following objects:
	1020	+The “<code>-doc</code>” option causes makeheaders to print
	1021	+information to standard output about all of the following objects:
1015	1022	<ul>
1016		-<li> C++ Class declarations
	1023	+<li> C++ class declarations
1017	1024	<li> Structure and union declarations
1018	1025	<li> Enumerations
1019	1026	<li> Typedefs
1020	1027	<li> Procedure and function definitions
1021	1028	<li> Global variables
1022		-<li> Preprocessor macros (ex: ``#define'')
	1029	+<li> Preprocessor macros (ex: “<code>#define</code>”)
1023	1030	</ul>
1024	1031	For each of these objects, the following information is output:
1025	1032	<ul>
1026	1033	<li> The name of the object.
1027	1034	<li> The type of the object. (Structure, typedef, macro, etc.)
		@@ -1029,11 +1036,12 @@
1029	1036	an EXPORT_INTERFACE block) or local (contained with LOCAL_INTERFACE).
1030	1037	<li> A flag to indicate if the object is declared in a C++ file.
1031	1038	<li> The name of the file in which the object was declared.
1032	1039	<li> The complete text of any block comment that preceeds the declarations.
1033	1040	<li> If the declaration occurred inside a preprocessor conditional
1034		- (``#if'') then the text of that conditional is provided.
	1041	+ (“<code>#if</code>”) then the text of that conditional is
	1042	+ provided.
1035	1043	<li> The complete text of a declaration for the object.
1036	1044	</ul>
1037	1045	The exact output format will not be described here.
1038	1046	It is simple to understand and parse and should be obvious to
1039	1047	anyone who inspects some sample output.
		@@ -1042,11 +1050,11 @@
1042	1050	<a name="H0016"></a>
1043	1051	<h2>5.0 Compiling The Makeheaders Program</h2>
1044	1052
1045	1053	<p>
1046	1054	The source code for makeheaders is a single file of ANSI-C code,
1047		-less than 3000 lines in length.
	1055	+approximately 3000 lines in length.
1048	1056	The program makes only modest demands of the system and C library
1049	1057	and should compile without alteration on most ANSI C compilers
1050	1058	and on most operating systems.
1051	1059	It is known to compile using several variations of GCC for Unix
1052	1060	as well as Cygwin32 and MSVC 5.0 for Win32.
1053	1061

	--- src/makeheaders.html
	+++ src/makeheaders.html
	@@ -4,11 +4,11 @@
4	<h1 align=center>The Makeheaders Program</h1>
5
6
7	<p>
8	This document describes <em>makeheaders</em>,
9	a tool that automatically generates ``<code>.h</code>''
10	files for a C or C++ programming project.
11	</p>
12
13
14	<h2>Table Of Contents</h2>
	@@ -67,11 +67,11 @@
67	<ul>
68	<li> Typedefs.
69	<li> Structure, union and enumeration declarations.
70	<li> Function and procedure prototypes.
71	<li> Preprocessor macros and #defines.
72	<li> ``extern'' variable declarations.
73	</ul>
74	</p>
75
76	<p>
77	Definitions in C, on the other hand, include these kinds of things:
	@@ -89,13 +89,13 @@
89	is the <em>interface</em> and the definition is the <em>implementation</em>.
90	</p>
91
92	<p>
93	In C programs, it has always been the tradition that declarations are
94	put in files with the ``<code>.h</code>'' suffix and definitions are
95	placed in ``<code>.c</code>'' files.
96	The .c files contain ``<code>#include</code>'' preprocessor statements
97	that cause the contents of .h files to be included as part of the
98	source code when the .c file is compiled.
99	In this way, the .h files define the interface to a subsystem and
100	the .c files define how the subsystem is implemented.
101	</p>
	@@ -262,11 +262,11 @@
262
263	<p>
264	A similar option is -H. Like the lower-case -h option, big -H
265	generates a single include file on standard output. But unlike
266	small -h, the big -H only emits prototypes and declarations that
267	have been designated as ``exportable''.
268	The idea is that -H will generate an include file that defines
269	the interface to a library.
270	More will be said about this in section 3.4.
271	</p>
272
	@@ -293,13 +293,13 @@
293	then you can supply an empty header filename, like this:
294	<pre>
295	makeheaders alpha.c beta.c gamma.c:
296	</pre>
297	In this example, makeheaders will scan the three files named
298	``alpha.c'',
299	``beta.c'' and
300	``gamma.c''
301	but because of the colon on the end of third filename
302	it will only generate headers for the first two files.
303	Unfortunately,
304	it is not possible to get makeheaders to process any file whose
305	name contains a colon.
	@@ -309,14 +309,14 @@
309	In a large project, the length of the command line for makeheaders
310	can become very long.
311	If the operating system doesn't support long command lines
312	(example: DOS and Win32) you may not be able to list all of the
313	input files in the space available.
314	In that case, you can use the ``-f'' option followed
315	by the name of a file to cause makeheaders to read command line
316	options and filename from the file instead of from the command line.
317	For example, you might prepare a file named ``mkhdr.dat''
318	that contains text like this:
319	<pre>
320	src/alpha.c:hdr/alpha.h
321	src/beta.c:hdr/beta.h
322	src/gamma.c:hdr/gamma.h
	@@ -327,18 +327,18 @@
327	makeheaders -f mkhdr.dat
328	</pre>
329	</p>
330
331	<p>
332	The ``-local'' option causes makeheaders to
333	generate of prototypes for ``static'' functions and
334	procedures.
335	Such prototypes are normally omitted.
336	</p>
337
338	<p>
339	Finally, makeheaders also includes a ``-doc'' option.
340	This command line option prevents makeheaders from generating any
341	headers at all.
342	Instead, makeheaders will write to standard output
343	information about every definition and declaration that it encounters
344	in its scan of source files.
	@@ -352,19 +352,21 @@
352	</p>
353
354	<p>
355	If you forget what command line options are available, or forget
356	their exact name, you can invoke makeheaders using an unknown
357	command line option (like ``--help'' or ``-?'')

358	and it will print a summary of the available options on standard
359	error.
360	If you need to process a file whose name begins with ``-'',
361	you can prepend a ``./'' to its name in order to get it

362	accepted by the command line parser.
363	Or, you can insert the special option ``--'' on the command
364	line to cause all subsequent command line arguments to be treated as
365	filenames even if their names beginn with ``-''.
366	</p>
367
368	<a name="H0006"></a>
369	<h2>3.0 Preparing Source Files For Use With Makeheaders</h2>
370
	@@ -379,30 +381,31 @@
379
380	<a name="H0007"></a>
381	<h3>3.1 The Basic Setup</h3>
382
383	<p>
384	The simpliest way to use makeheaders is to put all definitions in
385	one or more .c files and all structure and type declarations in
386	separate .h files.
387	The only restriction is that you should take care to chose basenames
388	for your .h files that are different from the basenames for you
389	.c files.
390	Recall that if your .c file is named (for example) ``alpha.c''

391	makeheaders will attempt to generate a corresponding header file
392	named ``alpha.h''.
393	For that reason, you don't want to use that name for
394	any of the .h files you write since that will prevent makeheaders
395	from generating the .h file automatically.
396	</p>
397
398	<p>
399	The structure of a .c file intented for use with makeheaders is very
400	simple.
401	All you have to do is add a single ``#include'' to the top
402	of the file that sources the header file that makeheaders will generate.
403	Hence, the beginning of a source file named ``alpha.c''
404	might look something like this:
405	</p>
406
407	<pre>
408	/*
	@@ -415,14 +418,14 @@
415
416	<p>
417	Your manually generated header files require no special attention at all.
418	Code them as you normally would.
419	However, makeheaders will work better if you omit the
420	``#if'' statements people often put around the outside of
421	header files that prevent the files from being included more than once.
422	For example, to create a header file named ``beta.h'', many
423	people will habitually write the following:
424
425	<pre>
426	#ifndef BETA_H
427	#define BETA_H
428
	@@ -435,11 +438,11 @@
435	Remember that the header files you write will never really be
436	included by any C code.
437	Instead, makeheaders will scan your header files to extract only
438	those declarations that are needed by individual .c files and then
439	copy those declarations to the .h files corresponding to the .c files.
440	Hence, the ``#if'' wrapper serves no useful purpose.
441	But it does make makeheaders work harder, forcing it to put
442	the statements
443
444	<pre>
445	#if !defined(BETA_H)
	@@ -465,11 +468,11 @@
465	</p>
466
467	<p>
468	Note that
469	the wildcard expression used in the above example,
470	``<code>*.[ch]</code>'',
471	will expand to include all .h files in the current directory, both
472	those entered manually be the programmer and others generated automatically
473	by a prior run of makeheaders.
474	But that is not a problem.
475	The makeheaders program will recognize and ignore any files it
	@@ -489,14 +492,14 @@
489	<p><li>
490	When a function is defined in any .c file, a prototype of that function
491	is placed in the generated .h file of every .c file that
492	calls the function.</p>
493
494	<P>If the ``static'' keyword of C appears at the beginning
495	of the function definition, the prototype is suppressed.
496	If you use the ``LOCAL'' keyword where you would normally
497	say ``static'', then a prototype is generated, but it
498	will only appear in the single header file that corresponds to the
499	source file containing the function. For example, if the file
500	<code>alpha.c</code> contains the following:
501	<pre>
502	LOCAL int testFunc(void){
	@@ -509,24 +512,26 @@
509	LOCAL int testFunc(void);
510	</pre>
511	However, no other generated header files will contain a prototype for
512	<code>testFunc()</code> since the function has only file scope.</p>
513
514	<p>When the ``LOCAL'' keyword is used, makeheaders will also
515	generate a #define for LOCAL, like this:
516	<pre>
517	#define LOCAL static
518	</pre>
519	so that the C compiler will know what it means.</p>
520
521	<p>If you invoke makeheaders with a ``-local'' command-line
522	option, then it treats the ``static'' keyword like
523	``LOCAL'' and generates prototypes in the header file
524	that corresponds to the source file containing the function defintiion.</p>

525
526	<p><li>
527	When a global variable is defined in a .c file, an ``extern''

528	declaration of that variable is placed in the header of every
529	.c file that uses the variable.
530	</p>
531
532	<p><li>
	@@ -550,12 +555,12 @@
550
551	<p><li>
552	When a structure, union or enumeration declaration appears in a .h
553	file, makeheaders will automatically
554	generate a typedef that allows the declaration to be referenced without
555	the ``struct'', ``union'' or ``enum''
556	qualifier.
557	In other words, if makeheaders sees the code:
558	<pre>
559	struct Examp { /* ... */ };
560	</pre>
561	it will automatically generate a corresponding typedef like this:
	@@ -572,13 +577,13 @@
572	</ul>
573
574	<p>
575	As a final note, we observe that automatically generated declarations
576	are ordered as required by the ANSI-C programming language.
577	If the declaration of some structure ``X'' requires a prior
578	declaration of another structure ``Y'', then Y will appear
579	first in the generated headers.
580	</p>
581
582	<a name="H0009"></a>
583	<h3>3.3 How To Avoid Having To Write Any Header Files</h3>
584
	@@ -611,18 +616,18 @@
611	<pre>
612	#if INTERFACE
613	#endif
614	</pre>
615	Thus any structure definitions that appear after the
616	``#if INTERFACE'' but before the corresponding
617	``#endif'' are eligable to be copied into the
618	automatically generated
619	.h files of other .c files.
620	</p>
621
622	<p>
623	If you use the ``#if INTERFACE'' mechanism in a .c file,
624	then the generated header for that .c file will contain a line
625	like this:
626	<pre>
627	#define INTERFACE 0
628	</pre>
	@@ -637,15 +642,15 @@
637	</p>
638
639	<p>
640	Note that you don't have to use this approach exclusively.
641	You can put some declarations in .h files and others within the
642	``#if INTERFACE'' regions of .c files.
643	Makeheaders treats all declarations alike, no matter where they
644	come from.
645	You should also note that a single .c file can contain as many
646	``#if INTERFACE'' regions as desired.
647	</p>
648
649	<a name="H0010"></a>
650	<h3>3.4 Designating Declarations For Export</h3>
651
	@@ -664,11 +669,11 @@
664	like this, but makeheaders does.
665	</p>
666
667	<p>
668	Using makeheaders, it is possible to designate routines and data
669	structures as being for ``export''.
670	Exported objects are visible not only to other files within the
671	same library or subassembly but also to other
672	libraries and subassemblies in the larger program.
673	By default, makeheaders only makes objects visible to other members
674	of the same library.
	@@ -690,14 +695,14 @@
690
691	<p>
692	But trouble quickly arises when we attempt to devise a mechanism for
693	telling makeheaders which prototypes it should export and which it should
694	keep local.
695	The built-in ``static'' keyword of C works well for prohibiting
696	prototypes from leaving a single source file, but because C doesn't
697	support a linkage hierarchy, there is nothing in the C language to help us.
698	We'll have to invite our own keyword: ``EXPORT''
699	</p>
700
701	<p>
702	Makeheaders allows the EXPORT keyword to precede any function or
703	procedure definition.
	@@ -726,15 +731,15 @@
726	<pre>
727	#if EXPORT_INTERFACE
728	#endif
729	</pre>
730	will become part of the exported interface.
731	The ``#if EXPORT_INTERFACE'' mechanism can be used in either
732	.c or .h files.
733	(The ``#if INTERFACE'' can also be used in both .h and .c files,
734	but since it's use in a .h file would be redundant, we haven't mentioned
735	it before.)
736	</p>
737
738	<a name="H0011"></a>
739	<h3>3.5 Local declarations processed by makeheaders</h3>
740
	@@ -742,11 +747,11 @@
742	Structure declarations and typedefs that appear in .c files are normally
743	ignored by makeheaders.
744	Such declarations are only intended for use by the source file in which
745	they appear and so makeheaders doesn't need to copy them into any
746	generated header files.
747	We call such declarations ``private''.
748	</p>
749
750	<p>
751	Sometimes it is convenient to have makeheaders sort a sequence
752	of private declarations into the correct order for us automatically.
	@@ -764,12 +769,13 @@
764	within
765	<pre>
766	#if LOCAL_INTERFACE
767	#endif
768	</pre>
769	A ``LOCAL_INTERFACE'' block works very much like the
770	``INTERFACE'' and ``EXPORT_INTERFACE''

771	blocks described above, except that makeheaders insures that the
772	objects declared in a LOCAL_INTERFACE are only visible to the
773	file containing the LOCAL_INTERFACE.
774	</p>
775
	@@ -777,11 +783,12 @@
777	<h3>3.6 Using Makeheaders With C++ Code</h3>
778
779	<p>
780	You can use makeheaders to generate header files for C++ code, in
781	addition to C.
782	Makeheaders will recognize and copy both ``class'' declarations

783	and inline function definitions, and it knows not to try to generate
784	prototypes for methods.
785	</p>
786
787	<p>
	@@ -805,20 +812,20 @@
805	C++ input. Makeheaders will recognize that its source code is C++
806	by the suffix on the source code filename. Simple ".c" or ".h" suffixes
807	are assumed to be ANSI-C. Anything else, including ".cc", ".C" and
808	".cpp" is assumed to be C++.
809	The name of the header file generated by makeheaders is derived from
810	by the name of the source file by converting every "c" to "h" and
811	every "C" to "H" in the suffix of the filename.
812	Thus the C++ source
813	file ``alpha.cpp'' will induce makeheaders to
814	generate a header file named ``alpha.hpp''.
815	</p>
816
817	<p>
818	Makeheaders augments class definitions by inserting prototypes to
819	methods were appropriate. If a method definition begins with one
820	of the special keywords <b>PUBLIC</b>, <b>PROTECTED</b>, or
821	<b>PRIVATE</b> (in upper-case to distinguish them from the regular
822	C++ keywords with the same meaning) then a prototype for that
823	method will be inserted into the class definition. If none of
824	these keywords appear, then the prototype is not inserted. For
	@@ -867,11 +874,11 @@
867	<h4>3.6.1 C++ Limitations</h4>
868
869	<p>
870	Makeheaders does not understand more recent
871	C++ syntax such as templates and namespaces.
872	Perhaps these issued will be addressed in future revisions.
873	</p>
874
875	<a name="H0013"></a>
876	<h3>3.7 Conditional Compilation</h3>
877
	@@ -879,13 +886,13 @@
879	The makeheaders program understands and tracks the conditional
880	compilation constructs in the source code files it scans.
881	Hence, if the following code appears in a source file
882	<pre>
883	#ifdef UNIX
884	# define WORKS_WELL 1
885	#else
886	# define WORKS_WELL 0
887	#endif
888	</pre>
889	then the next patch of code will appear in the generated header for
890	every .c file that uses the WORKS_WELL constant:
891	<pre>
	@@ -918,12 +925,12 @@
918	<p>
919	Makeheaders does not understand the old K&R style of function
920	and procedure definitions.
921	It only understands the modern ANSI-C style, and will probably
922	become very confused if it encounters an old K&R function.
923	You should take care to avoid putting K&R function defintions
924	in your code, therefore.
925	</p>
926
927	<p>
928	Makeheaders does not understand when you define more than one
929	global variable with the same type separated by a comma.
	@@ -993,35 +1000,35 @@
993	in the code, it is not necessary to make a corresponding change
994	in a separate document. Just rerun the documentation generator.
995	</ul>
996	The makeheaders program does not generate program documentation itself.
997	But you can use makeheaders to parse the program source code, extract
998	the information that is relavant to the documentation and to pass this
999	information to another tool to do the actual documentation preparation.
1000	</p>
1001
1002	<p>
1003	When makeheaders is run with the ``-doc'' option, it emits
1004	no header files at all.
1005	Instead, it does a complete dump of its internal tables to standard
1006	outputs in a form that is easily parsed.
1007	This output can then be used by another program (the implementation
1008	of which is left as an exercise to the reader) that will use the
1009	information to prepare suitable documentation.
1010	</p>
1011
1012	<p>
1013	The ``-doc'' option causes makeheaders to print information
1014	to standard output about all of the following objects:
1015	<ul>
1016	<li> C++ Class declarations
1017	<li> Structure and union declarations
1018	<li> Enumerations
1019	<li> Typedefs
1020	<li> Procedure and function definitions
1021	<li> Global variables
1022	<li> Preprocessor macros (ex: ``#define'')
1023	</ul>
1024	For each of these objects, the following information is output:
1025	<ul>
1026	<li> The name of the object.
1027	<li> The type of the object. (Structure, typedef, macro, etc.)
	@@ -1029,11 +1036,12 @@
1029	an EXPORT_INTERFACE block) or local (contained with LOCAL_INTERFACE).
1030	<li> A flag to indicate if the object is declared in a C++ file.
1031	<li> The name of the file in which the object was declared.
1032	<li> The complete text of any block comment that preceeds the declarations.
1033	<li> If the declaration occurred inside a preprocessor conditional
1034	(``#if'') then the text of that conditional is provided.

1035	<li> The complete text of a declaration for the object.
1036	</ul>
1037	The exact output format will not be described here.
1038	It is simple to understand and parse and should be obvious to
1039	anyone who inspects some sample output.
	@@ -1042,11 +1050,11 @@
1042	<a name="H0016"></a>
1043	<h2>5.0 Compiling The Makeheaders Program</h2>
1044
1045	<p>
1046	The source code for makeheaders is a single file of ANSI-C code,
1047	less than 3000 lines in length.
1048	The program makes only modest demands of the system and C library
1049	and should compile without alteration on most ANSI C compilers
1050	and on most operating systems.
1051	It is known to compile using several variations of GCC for Unix
1052	as well as Cygwin32 and MSVC 5.0 for Win32.
1053

	--- src/makeheaders.html
	+++ src/makeheaders.html
	@@ -4,11 +4,11 @@
4	<h1 align=center>The Makeheaders Program</h1>
5
6
7	<p>
8	This document describes <em>makeheaders</em>,
9	a tool that automatically generates “<code>.h</code>”
10	files for a C or C++ programming project.
11	</p>
12
13
14	<h2>Table Of Contents</h2>
	@@ -67,11 +67,11 @@
67	<ul>
68	<li> Typedefs.
69	<li> Structure, union and enumeration declarations.
70	<li> Function and procedure prototypes.
71	<li> Preprocessor macros and #defines.
72	<li> “<code>extern</code>” variable declarations.
73	</ul>
74	</p>
75
76	<p>
77	Definitions in C, on the other hand, include these kinds of things:
	@@ -89,13 +89,13 @@
89	is the <em>interface</em> and the definition is the <em>implementation</em>.
90	</p>
91
92	<p>
93	In C programs, it has always been the tradition that declarations are
94	put in files with the “<code>.h</code>” suffix and definitions are
95	placed in “<code>.c</code>” files.
96	The .c files contain “<code>#include</code>” preprocessor statements
97	that cause the contents of .h files to be included as part of the
98	source code when the .c file is compiled.
99	In this way, the .h files define the interface to a subsystem and
100	the .c files define how the subsystem is implemented.
101	</p>
	@@ -262,11 +262,11 @@
262
263	<p>
264	A similar option is -H. Like the lower-case -h option, big -H
265	generates a single include file on standard output. But unlike
266	small -h, the big -H only emits prototypes and declarations that
267	have been designated as “exportable”.
268	The idea is that -H will generate an include file that defines
269	the interface to a library.
270	More will be said about this in section 3.4.
271	</p>
272
	@@ -293,13 +293,13 @@
293	then you can supply an empty header filename, like this:
294	<pre>
295	makeheaders alpha.c beta.c gamma.c:
296	</pre>
297	In this example, makeheaders will scan the three files named
298	“<code>alpha.c</code>”,
299	“<code>beta.c</code>” and
300	“<code>gamma.c</code>”
301	but because of the colon on the end of third filename
302	it will only generate headers for the first two files.
303	Unfortunately,
304	it is not possible to get makeheaders to process any file whose
305	name contains a colon.
	@@ -309,14 +309,14 @@
309	In a large project, the length of the command line for makeheaders
310	can become very long.
311	If the operating system doesn't support long command lines
312	(example: DOS and Win32) you may not be able to list all of the
313	input files in the space available.
314	In that case, you can use the “<code>-f</code>” option followed
315	by the name of a file to cause makeheaders to read command line
316	options and filename from the file instead of from the command line.
317	For example, you might prepare a file named “<code>mkhdr.dat</code>”
318	that contains text like this:
319	<pre>
320	src/alpha.c:hdr/alpha.h
321	src/beta.c:hdr/beta.h
322	src/gamma.c:hdr/gamma.h
	@@ -327,18 +327,18 @@
327	makeheaders -f mkhdr.dat
328	</pre>
329	</p>
330
331	<p>
332	The “<code>-local</code>” option causes makeheaders to
333	generate of prototypes for “<code>static</code>” functions and
334	procedures.
335	Such prototypes are normally omitted.
336	</p>
337
338	<p>
339	Finally, makeheaders also includes a “<code>-doc</code>” option.
340	This command line option prevents makeheaders from generating any
341	headers at all.
342	Instead, makeheaders will write to standard output
343	information about every definition and declaration that it encounters
344	in its scan of source files.
	@@ -352,19 +352,21 @@
352	</p>
353
354	<p>
355	If you forget what command line options are available, or forget
356	their exact name, you can invoke makeheaders using an unknown
357	command line option (like “<code>--help</code>” or
358	“<code>-?</code>”)
359	and it will print a summary of the available options on standard
360	error.
361	If you need to process a file whose name begins with
362	“<code>-</code>”,
363	you can prepend a “<code>./</code>” to its name in order to get it
364	accepted by the command line parser.
365	Or, you can insert the special option “<code>--</code>” on the
366	command line to cause all subsequent command line arguments to be treated as
367	filenames even if their names begin with “<code>-</code>”.
368	</p>
369
370	<a name="H0006"></a>
371	<h2>3.0 Preparing Source Files For Use With Makeheaders</h2>
372
	@@ -379,30 +381,31 @@
381
382	<a name="H0007"></a>
383	<h3>3.1 The Basic Setup</h3>
384
385	<p>
386	The simplest way to use makeheaders is to put all definitions in
387	one or more .c files and all structure and type declarations in
388	separate .h files.
389	The only restriction is that you should take care to chose basenames
390	for your .h files that are different from the basenames for your
391	.c files.
392	Recall that if your .c file is named (for example)
393	“<code>alpha.c</code>”
394	makeheaders will attempt to generate a corresponding header file
395	named “<code>alpha.h</code>”.
396	For that reason, you don't want to use that name for
397	any of the .h files you write since that will prevent makeheaders
398	from generating the .h file automatically.
399	</p>
400
401	<p>
402	The structure of a .c file intented for use with makeheaders is very
403	simple.
404	All you have to do is add a single “<code>#include</code>” to the
405	top of the file that sources the header file that makeheaders will generate.
406	Hence, the beginning of a source file named “<code>alpha.c</code>”
407	might look something like this:
408	</p>
409
410	<pre>
411	/*
	@@ -415,14 +418,14 @@
418
419	<p>
420	Your manually generated header files require no special attention at all.
421	Code them as you normally would.
422	However, makeheaders will work better if you omit the
423	“<code>#if</code>” statements people often put around the outside of
424	header files that prevent the files from being included more than once.
425	For example, to create a header file named “<code>beta.h</code>”,
426	many people will habitually write the following:
427
428	<pre>
429	#ifndef BETA_H
430	#define BETA_H
431
	@@ -435,11 +438,11 @@
438	Remember that the header files you write will never really be
439	included by any C code.
440	Instead, makeheaders will scan your header files to extract only
441	those declarations that are needed by individual .c files and then
442	copy those declarations to the .h files corresponding to the .c files.
443	Hence, the “<code>#if</code>” wrapper serves no useful purpose.
444	But it does make makeheaders work harder, forcing it to put
445	the statements
446
447	<pre>
448	#if !defined(BETA_H)
	@@ -465,11 +468,11 @@
468	</p>
469
470	<p>
471	Note that
472	the wildcard expression used in the above example,
473	“<code>*.[ch]</code>”,
474	will expand to include all .h files in the current directory, both
475	those entered manually be the programmer and others generated automatically
476	by a prior run of makeheaders.
477	But that is not a problem.
478	The makeheaders program will recognize and ignore any files it
	@@ -489,14 +492,14 @@
492	<p><li>
493	When a function is defined in any .c file, a prototype of that function
494	is placed in the generated .h file of every .c file that
495	calls the function.</p>
496
497	<P>If the “<code>static</code>” keyword of C appears at the
498	beginning of the function definition, the prototype is suppressed.
499	If you use the “<code>LOCAL</code>” keyword where you would normally
500	say “<code>static</code>”, then a prototype is generated, but it
501	will only appear in the single header file that corresponds to the
502	source file containing the function. For example, if the file
503	<code>alpha.c</code> contains the following:
504	<pre>
505	LOCAL int testFunc(void){
	@@ -509,24 +512,26 @@
512	LOCAL int testFunc(void);
513	</pre>
514	However, no other generated header files will contain a prototype for
515	<code>testFunc()</code> since the function has only file scope.</p>
516
517	<p>When the “<code>LOCAL</code>” keyword is used, makeheaders will
518	also generate a #define for LOCAL, like this:
519	<pre>
520	#define LOCAL static
521	</pre>
522	so that the C compiler will know what it means.</p>
523
524	<p>If you invoke makeheaders with a “<code>-local</code>”
525	command-line option, then it treats the “<code>static</code>”
526	keyword like “<code>LOCAL</code>” and generates prototypes in the
527	header file that corresponds to the source file containing the function
528	definition.</p>
529
530	<p><li>
531	When a global variable is defined in a .c file, an
532	“<code>extern</code>”
533	declaration of that variable is placed in the header of every
534	.c file that uses the variable.
535	</p>
536
537	<p><li>
	@@ -550,12 +555,12 @@
555
556	<p><li>
557	When a structure, union or enumeration declaration appears in a .h
558	file, makeheaders will automatically
559	generate a typedef that allows the declaration to be referenced without
560	the “<code>struct</code>”, “<code>union</code>” or
561	“<code>enum</code>” qualifier.
562	In other words, if makeheaders sees the code:
563	<pre>
564	struct Examp { /* ... */ };
565	</pre>
566	it will automatically generate a corresponding typedef like this:
	@@ -572,13 +577,13 @@
577	</ul>
578
579	<p>
580	As a final note, we observe that automatically generated declarations
581	are ordered as required by the ANSI-C programming language.
582	If the declaration of some structure “<code>X</code>” requires a
583	prior declaration of another structure “<code>Y</code>”, then Y will
584	appear first in the generated headers.
585	</p>
586
587	<a name="H0009"></a>
588	<h3>3.3 How To Avoid Having To Write Any Header Files</h3>
589
	@@ -611,18 +616,18 @@
616	<pre>
617	#if INTERFACE
618	#endif
619	</pre>
620	Thus any structure definitions that appear after the
621	“<code>#if INTERFACE</code>” but before the corresponding
622	“<code>#endif</code>” are eligable to be copied into the
623	automatically generated
624	.h files of other .c files.
625	</p>
626
627	<p>
628	If you use the “<code>#if INTERFACE</code>” mechanism in a .c file,
629	then the generated header for that .c file will contain a line
630	like this:
631	<pre>
632	#define INTERFACE 0
633	</pre>
	@@ -637,15 +642,15 @@
642	</p>
643
644	<p>
645	Note that you don't have to use this approach exclusively.
646	You can put some declarations in .h files and others within the
647	“<code>#if INTERFACE</code>” regions of .c files.
648	Makeheaders treats all declarations alike, no matter where they
649	come from.
650	You should also note that a single .c file can contain as many
651	“<code>#if INTERFACE</code>” regions as desired.
652	</p>
653
654	<a name="H0010"></a>
655	<h3>3.4 Designating Declarations For Export</h3>
656
	@@ -664,11 +669,11 @@
669	like this, but makeheaders does.
670	</p>
671
672	<p>
673	Using makeheaders, it is possible to designate routines and data
674	structures as being for “<code>export</code>”.
675	Exported objects are visible not only to other files within the
676	same library or subassembly but also to other
677	libraries and subassemblies in the larger program.
678	By default, makeheaders only makes objects visible to other members
679	of the same library.
	@@ -690,14 +695,14 @@
695
696	<p>
697	But trouble quickly arises when we attempt to devise a mechanism for
698	telling makeheaders which prototypes it should export and which it should
699	keep local.
700	The built-in “<code>static</code>” keyword of C works well for
701	prohibiting prototypes from leaving a single source file, but because C doesn't
702	support a linkage hierarchy, there is nothing in the C language to help us.
703	We'll have to invite our own keyword: “<code>EXPORT</code>”
704	</p>
705
706	<p>
707	Makeheaders allows the EXPORT keyword to precede any function or
708	procedure definition.
	@@ -726,15 +731,15 @@
731	<pre>
732	#if EXPORT_INTERFACE
733	#endif
734	</pre>
735	will become part of the exported interface.
736	The “<code>#if EXPORT_INTERFACE</code>” mechanism can be used in
737	either .c or .h files.
738	(The “<code>#if INTERFACE</code>” can also be used in both .h and
739	.c files, but since it's use in a .h file would be redundant, we haven't
740	mentioned it before.)
741	</p>
742
743	<a name="H0011"></a>
744	<h3>3.5 Local declarations processed by makeheaders</h3>
745
	@@ -742,11 +747,11 @@
747	Structure declarations and typedefs that appear in .c files are normally
748	ignored by makeheaders.
749	Such declarations are only intended for use by the source file in which
750	they appear and so makeheaders doesn't need to copy them into any
751	generated header files.
752	We call such declarations “<code>private</code>”.
753	</p>
754
755	<p>
756	Sometimes it is convenient to have makeheaders sort a sequence
757	of private declarations into the correct order for us automatically.
	@@ -764,12 +769,13 @@
769	within
770	<pre>
771	#if LOCAL_INTERFACE
772	#endif
773	</pre>
774	A “<code>LOCAL_INTERFACE</code>” block works very much like the
775	“<code>INTERFACE</code>” and
776	“<code>EXPORT_INTERFACE</code>”
777	blocks described above, except that makeheaders insures that the
778	objects declared in a LOCAL_INTERFACE are only visible to the
779	file containing the LOCAL_INTERFACE.
780	</p>
781
	@@ -777,11 +783,12 @@
783	<h3>3.6 Using Makeheaders With C++ Code</h3>
784
785	<p>
786	You can use makeheaders to generate header files for C++ code, in
787	addition to C.
788	Makeheaders will recognize and copy both “<code>class</code>”
789	declarations
790	and inline function definitions, and it knows not to try to generate
791	prototypes for methods.
792	</p>
793
794	<p>
	@@ -805,20 +812,20 @@
812	C++ input. Makeheaders will recognize that its source code is C++
813	by the suffix on the source code filename. Simple ".c" or ".h" suffixes
814	are assumed to be ANSI-C. Anything else, including ".cc", ".C" and
815	".cpp" is assumed to be C++.
816	The name of the header file generated by makeheaders is derived from
817	the name of the source file by converting every "c" to "h" and
818	every "C" to "H" in the suffix of the filename.
819	Thus the C++ source
820	file “<code>alpha.cpp</code>” will induce makeheaders to
821	generate a header file named “<code>alpha.hpp</code>”.
822	</p>
823
824	<p>
825	Makeheaders augments class definitions by inserting prototypes to
826	methods where appropriate. If a method definition begins with one
827	of the special keywords <b>PUBLIC</b>, <b>PROTECTED</b>, or
828	<b>PRIVATE</b> (in upper-case to distinguish them from the regular
829	C++ keywords with the same meaning) then a prototype for that
830	method will be inserted into the class definition. If none of
831	these keywords appear, then the prototype is not inserted. For
	@@ -867,11 +874,11 @@
874	<h4>3.6.1 C++ Limitations</h4>
875
876	<p>
877	Makeheaders does not understand more recent
878	C++ syntax such as templates and namespaces.
879	Perhaps these issues will be addressed in future revisions.
880	</p>
881
882	<a name="H0013"></a>
883	<h3>3.7 Conditional Compilation</h3>
884
	@@ -879,13 +886,13 @@
886	The makeheaders program understands and tracks the conditional
887	compilation constructs in the source code files it scans.
888	Hence, if the following code appears in a source file
889	<pre>
890	#ifdef UNIX
891	# define WORKS_WELL 1
892	#else
893	# define WORKS_WELL 0
894	#endif
895	</pre>
896	then the next patch of code will appear in the generated header for
897	every .c file that uses the WORKS_WELL constant:
898	<pre>
	@@ -918,12 +925,12 @@
925	<p>
926	Makeheaders does not understand the old K&R style of function
927	and procedure definitions.
928	It only understands the modern ANSI-C style, and will probably
929	become very confused if it encounters an old K&R function.
930	Therefore you should take care to avoid putting K&R function definitions
931	in your code.
932	</p>
933
934	<p>
935	Makeheaders does not understand when you define more than one
936	global variable with the same type separated by a comma.
	@@ -993,35 +1000,35 @@
1000	in the code, it is not necessary to make a corresponding change
1001	in a separate document. Just rerun the documentation generator.
1002	</ul>
1003	The makeheaders program does not generate program documentation itself.
1004	But you can use makeheaders to parse the program source code, extract
1005	the information that is relevant to the documentation and to pass this
1006	information to another tool to do the actual documentation preparation.
1007	</p>
1008
1009	<p>
1010	When makeheaders is run with the “<code>-doc</code>” option, it
1011	emits no header files at all.
1012	Instead, it does a complete dump of its internal tables to standard
1013	output in a form that is easily parsed.
1014	This output can then be used by another program (the implementation
1015	of which is left as an exercise to the reader) that will use the
1016	information to prepare suitable documentation.
1017	</p>
1018
1019	<p>
1020	The “<code>-doc</code>” option causes makeheaders to print
1021	information to standard output about all of the following objects:
1022	<ul>
1023	<li> C++ class declarations
1024	<li> Structure and union declarations
1025	<li> Enumerations
1026	<li> Typedefs
1027	<li> Procedure and function definitions
1028	<li> Global variables
1029	<li> Preprocessor macros (ex: “<code>#define</code>”)
1030	</ul>
1031	For each of these objects, the following information is output:
1032	<ul>
1033	<li> The name of the object.
1034	<li> The type of the object. (Structure, typedef, macro, etc.)
	@@ -1029,11 +1036,12 @@
1036	an EXPORT_INTERFACE block) or local (contained with LOCAL_INTERFACE).
1037	<li> A flag to indicate if the object is declared in a C++ file.
1038	<li> The name of the file in which the object was declared.
1039	<li> The complete text of any block comment that preceeds the declarations.
1040	<li> If the declaration occurred inside a preprocessor conditional
1041	(“<code>#if</code>”) then the text of that conditional is
1042	provided.
1043	<li> The complete text of a declaration for the object.
1044	</ul>
1045	The exact output format will not be described here.
1046	It is simple to understand and parse and should be obvious to
1047	anyone who inspects some sample output.
	@@ -1042,11 +1050,11 @@
1050	<a name="H0016"></a>
1051	<h2>5.0 Compiling The Makeheaders Program</h2>
1052
1053	<p>
1054	The source code for makeheaders is a single file of ANSI-C code,
1055	approximately 3000 lines in length.
1056	The program makes only modest demands of the system and C library
1057	and should compile without alteration on most ANSI C compilers
1058	and on most operating systems.
1059	It is known to compile using several variations of GCC for Unix
1060	as well as Cygwin32 and MSVC 5.0 for Win32.
1061

Fossil SCM

Keyboard Shortcuts