Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CEXTRC(5)		      File Formats Manual		     CEXTRC(5)

NAME
       cextrc -	C prototype/documentation extractor customization file format

SYNOPSIS
       NORMRC

DESCRIPTION
       The  programs  cextract(1)  and CDOCNAME(1) extract function prototypes
       from C source code and create header and	 documentation	files  respec-
       tively.	 The  NORMRC  customization files allow	users to specify which
       options are set for those programs, without having to  always  use  the
       command line.

       The  configuration  files  are read prior to the	parsing	of the command
       line options, as	well as	whenever the `-q' flag is encountered.

FORMAT
       The file	should be a normal text	file, with each	customization  command
       on a separate line.  Blank lines	and any	line beginning with a `#' will
       be ignored.

       Any command preceded by the string "doc-only " will  only  be  used  in
       documentation  mode,  and  any command preceded by "extract-only	" will
       only be used in extraction mode.

       Commands	which are preceded by either a `!' or the string "no-" or "no"
       will be interpreted as disabling	that option, if	appropriate.

COMMANDS
       The full	list of	configuration commands is given	below.

       ansi-code
	      If  dual-output  and merge-output	modes are not enabled, produce
	      output in	ANSI C format, with full  prototyping.	 This  command
	      does not do anything when	used in	documentation mode.

       break-after-types

       break-types
	      When  enabled,  a	 newline will be inserted between the function
	      type and the function name in the	function declarations.

       comments

       yank-comments
	      Extract the comment immediately before the function  definition,
	      and display it upon output.

       config-file: file
	      Read  in	the specified file and parse it	for configuration com-
	      mands.

       cpp-program: program
	      Specify which program is to be used as a C  preprocessor.	  This
	      program should resolve all C defines and while, hopefully, leav-
	      ing the comments intact.

       doc-mode
	      Enable documentation mode	with normal text output.  This is  the
	      default setting for CDOCNAME(1).

       define: expression
	      Pass  the	specified expression to	the C preprocessor with	a "-D"
	      string prepended to it.  This command is equivalent to the  `-D'
	      command line option.

       dual-output
	      Provide  output  in both ANSI and	K&R C formats, separated by an
	      "#if __STDC__" ... "#else" ... "#endif" construct.  This command
	      does  not	 do anything when used in documentation	mode or	if the
	      merge-output option is enabled.

       externs
	      Prepend an "extern" to each function description upon output.

       extract-mode
	      Enable extraction	mode and generate output which can be used  as
	      a	C header file defining the prototypes for all of the functions
	      which are	encountered.  The is the default mode for cextract(1).

       first-comments
	      Include in the output the	initial	comment	 encountered  in  each
	      file.

       filename

       prepend-filename
	      If  the  "first-comments"	option is enabled, prepend the name of
	      each file	to the output of initial comments.

       font % ##
	      Assign a troff font "##" to a given font type  `%',  when	 using
	      troff  documentation  mode.   The	possible font types are	`1' or
	      `t', `2' or `c', `3' or `n', and `4' or `p' for the title,  com-
	      ment,  name,  and	 parameter  list respectively.	The troff font
	      "##" is a	normal one or two character troff font,	such  as  "CO"
	      for Courier Oblique.

       header-string: string
	      When  in extraction mode,	enclose	the output within preprocessor
	      directives testing for the definition of string.	This method is
	      used  with many system header files, to insure that they are not
	      "#include"d more than once.  If this option  is  not  used,  the
	      output will be enclosed within a "#ifndef	__CEXTRACT__", "#endif
	      /* __CEXTRACT__ */" sequence instead.

       include:	directory
	      Pass the specified directory to the C preprocessor with  a  "-I"
	      string  prepended	to it.	This command is	equivalent to the `-I'
	      command-line option.

       merge-output
	      Merge the	ANSI and K&R output into a single line	of  output  to
	      make  it	take up	less space.  A macro is	used to	expand the pa-
	      rameter list for ANSI compilers.	This option overrides both the
	      dual-output  and	ansi-code  options.  There is no affect	if the
	      documentation mode is enabled.

       multi-comments

       multiple-comments
	      When extracting comments,	assume that consecutive	 comments  are
	      actually one single comment.  This allows	people that place com-
	      ment delimiters at the beginning and end of each	line  to  have
	      their comments properly captured.

       output-file: outfile
	      Store the	output in the specified	file.

       replace
	      Replace the first	string which matches a variable, type, or both
	      (as selected) with the second string.   The format is:
		   replace [all/type/variable] "string1" "string2"
	      For example, on Sun machines, the	automatic  "FILE"  replacement
	      could be accomplished using a command like:
		   replace type	"struct	_iobuf"	"FILE"
	      However,	this should not	need to	be entered by the average user
	      since it is handled automatically	 by  cextract(1),  as  is  the
	      varargs system.

       remove-names

       discard-names
	      Remove variable names from the prototype list prior to output.

       roff-mode

       troff-mode
	      Enable  documentation  mode  with	troff -ms format output.  This
	      option is	overridden by the doc-mode or extract-mode options.

       show-all

       show-anyway
	      When output is K&R C,  display  prototypes  in  comments.	  When
	      dual-output  is enabled, display comments	and prototypes in both
	      sections;	otherwise, display comments and	prototypes only	in the
	      ANSI C portion.  This option does	nothing	in documentation mode.

       single-comments
	      When  extracting	comments  from	a file,	take only one comment,
	      discarding all preceding comments.  This option is  the  reverse
	      of the multi-comments option.

       sort-all
	      Alphabetically  sort  all	of the functions from all of the files
	      before generating	output.

       sort-by-files
	      For each file processed, sort all	of the functions prior to out-
	      put.

       statics

       statics:	none

       statics:	any

       statics:	only
	      Select  the  method  for how static functions should be treated.
	      If "none"	is selected, statics will be ignored.	If  "only"  is
	      selected,	 non-static functions will be ignored.	Finally, "any"
	      indicates	that all functions will	be extracted.  If no selection
	      is  made,	it will	be the same as selecting "any" or (with	a pre-
	      ceding `!') "none".

       tab-width: width
	      Set the tab width	to be an integer  number  width.   This	 works
	      only during documentation	generation.

       undefine: name
	      Undefine	any previously defined macro.  If none is encountered,
	      pass the specified expression to the C preprocessor with a  "-U"
	      string  prepended	to it.	This command is	equivalent to the `-U'
	      command-line option.

       wrap-parameters:	#
	      If the length of the parameter list for a	function  would	 cause
	      it  to  exceed a given number of columns [72 by default],	a new-
	      line will	be inserted in place of	a space	character, so that the
	      function will not	exceed that given length.  The optional	number
	      after the	command	will override a	 negation  prefix  if  encoun-
	      tered.

FILES
       SYSCXTRC, $HOME/NORMRC, NORMRC
	      configuration files.

VMS
       Configuration files are also supported under VMS.  The default configu-
       ration  files  for  VMS	systems	 are   sys$library:cext.cnf,   sys$lo-
       gin:cext.cnf, and cext.cnf.

       Since  the  VMS	C compiler strips out comments,	the documentation mode
       and comment options are not very	useful.	 Using the GNU C  preprocessor
       instead might be	a possible solution.

SEE ALSO
       cextract(1), CDOCNAME(1)

AUTHOR
       Adam Bryant
       adb@bu.edu

       initial VMS port	by John	Carr
       jrcarr@iup.bitnet

			       3 September 1992			     CEXTRC(5)

NAME | SYNOPSIS | DESCRIPTION | FORMAT | COMMANDS | FILES | VMS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cextrc&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help