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

FreeBSD Manual Pages

  
 
  

home | help
cxref(1)		    General Commands Manual		      cxref(1)

NAME
       cxref - C Cross Referencing & Documenting tool.

SYNOPSIS
       cxref filename  [  ...  filename] [-Odirname] [-Nbasename] [-Rbasename]
       [-all-comments] [-no-comments]  [-verbatim-comments]  [-block-comments]
       [-xref[-all][-file][-func][-var][-type]]	[-warn[-all][-comment][-xref]]
       [-index[-all][-file][-func][-var][-type]] [-raw]	[-latex] [-html[-src]]
       [-rtf]  [-sgml]	[-Idirname]  [-Ddefine]	 [-Udefine] [-CPP cpp_program]
       [-- cpp_args ...	cpp_args]

       cxref filename  [   ...	 filename]  -delete  [-Odirname]  [-Nbasename]
       [-Rbasename]

DESCRIPTION
       A  program that can automatically generate documentation	and cross ref-
       erences for a C program.

       The input is any	C program with appropriate comments and	the output  is
       LaTeX, HTML, RTF	or SGML	files.

OPTIONS
       filename
	      The  name	 of  the  file to document, any	number of files	may be
	      documented at a time.

       -delete
	      The files	named are to be	deleted	from the output	directory  and
	      their  entries  in  the cross reference database and main	output
	      files are	to be removed.

       -Odirname
	      The name of a directory to use for the output  latex  files  and
	      the location of the cross	reference files	that are created.

       -Nbasename
	      The  name	to use for the first part of the output	and cross ref-
	      erence files instead of cxref, the file  extensions  remain  the
	      same.

       -Rdirname
	      When  the	 source	 files	are  in	 more  than one	directory, set
	      dirname to the name of the root directory	 of  the  source  tree
	      (use  relative  path  if easier e.g. `-R../..').	This will then
	      run cxref	from that root directory and the `-Odirname'  must  be
	      relative to that directory.

       -all-comments
	      In  case	you  think that	the existing comments might work, (see
	      above for	description of special comments).  [Danger!  This  op-
	      tion can produce weird results.]

       -no-comments
	      Ignores  all  comments, useful if	you just want the cross	refer-
	      ences and	not the	documentation.

       -verbatim-comments
	      When the comments	that you have in the code are formatted	 in  a
	      predetermined  style  that  you  want to preserve	on the output,
	      this option will force them not to be reformatted.  [Note,  this
	      is for file and function comments	only.]

       -block-comments
	      When  the	 comments  in the program are formatted	in the `block'
	      style (with a leading '*'	character on every line), this	option
	      will remove that character from the output.  [Works for a	single
	      `*', `+',	`|' or `:' on each line.]

       -xref  Produce cross referencing	information (see below).
	       -all    All cross references.
	       -file   Cross references	for files.
	       -func   Cross references	for functions.
	       -var    Cross references	for variables.
	       -type   Cross references	for types.

       -warn  Produce warnings,	the options must be concatenated together:
	       -all	  All warnings.
	       -comment	  Warn of missing comments.
	       -xref	  Warn of missing cross	references.

       -index Produce a	cross reference	index, the options  must  be  concate-
	      nated together:
	       -all    All indexes.
	       -file   Index of	files.
	       -func   Index of	functions.
	       -var    Index of	variables.
	       -type   Index of	types.

       -raw   Produce a	raw form of output, not	really of much use except with
	      -warn.

       -latex Produce a	LaTeX file to document each of the  source  files  and
	      also an extra file that includes each of these files.

       -html  Produce  an  HTML	4.01 file to document each of the source files
	      and a main file to reference each	of these files.

       -html-src
	      Produce the HTML output and an HTML version of the  source  file
	      with links into it.

       -rtf   Produce  a  Rich	Text  Format (RTF) file	to document the	source
	      file.

       -sgml  Produce an SGML file to document the source  file.   (Using  the
	      LinuxDoc DTD).

       -Idirname
	      GCC option to specify the	path for include files.

       -Ddefine
	      GCC option to define a pre-processor symbol.

       -Udefine
	      GCC option to undefine a pre-processor symbol.

       -CPP program
	      The  name	 of the	program	to use instead of the compile time de-
	      fault. The program must be able to perform all  of  the  actions
	      that  `gcc  -E -C	-dD' does to work.  If the program takes argu-
	      ments then the whole thing needs to be in	quotes so that	it  is
	      interpreted as a single argument to cxref.

       --arg ... arg
	      Extra  arguments to be passed to the pre-processor can be	placed
	      after the	`--' separator.

   C Compiler Replacement cxref-cc
       To simplify using cxref on existing source code,	there is now  a	 shell
       script that will	call the C compiler and	then call cxref	to process the
       source file.  This means	that it	can be used as a drop  in  replacement
       for CC in Makefiles and the like.

       Usage: cxref-cc [usual cc options]

       The  name  of  the source file is extracted from	the list of options as
       well as the `-D*', `-I*', `-U*' flags and when  the  C  compiler	 exits
       succesfully cxref will be called.  The name of the C compiler to	use is
       controlled by the CXREFCC environment variable, or if this is  not  set
       then the	CC environment variable, or failing this just gcc.

       Using  this script requires the use of a	`.cxref' configuration file to
       contain the options since there is nowhere to put the  options  on  the
       command line for	the C compiler.

       This  will  only	 cross-reference and document the C source files since
       they are	the only ones that are compiled, but it	will  make  sure  that
       they are	cross-referenced with the correct options etc.

   Cxref Configuration File
       These command line arguments can	also be	put into a file	named `.cxref'
       instead of on the command line.	When cxref is run the arguments	to the
       program are interpreted in the following	order.

       (1)  Those  on the command line.	 (2) Those in the `.cxref' file	in the
       current directory.  (3) Those in	the `.cxref' file in the  source  tree
       root specified by `-R'.

       This  means  that  in a multi-directory source tree, each sub-directory
       can have	a `.cxref' file	containing just	the line `-R..'	 or  appropri-
       ate.   The  main	 directory can have a `.cxref' file containing the re-
       mainder of the options.	This removes completely	the need to  have  any
       options on the command line apart from the source file names.

       The  format  of the `.cxref' file is any	number of lines, each one con-
       taining a single	command	line argument (equivalent to one of the	argv).
       The  only  options  that	 cannot	 be used are the names of source files
       themselves and the `-delete' option.  Blank lines are ignored and lines
       starting	with a '#' are comments.

   Program Documentation Comments
       The documentation for the program is produced from comments in the code
       that are	appropriately formatted.  The cross referencing	comes from the
       code itself and requires	no extra work.

       The special comments are	`/**** ****/' (for a file) and `/*++++ ++++*/'
       (for a data object) any number of `*' or	`+' can	be used	inside of  the
       standard	`/*' and `*/' comment delimiters in the	comments, they are ig-
       nored.

       If a comment line starts	with whitespace	and is	followed  by  `+html+'
       then  the  rest of the line is included only in the HTML	output,	and is
       not processed so	it can include HTML markup, `-html-'  means  that  the
       rest  of	 the line is included in all except the	HTML output.  The same
       also applies to the other output	formats,  `+none+'  can	 be  used  for
       lines  not  to appear in	any output.  The exception to this is that the
       raw output does not do any checking and will output all lines.

       In any situation	where a	comment	follows	a `,', `;'  or	`)'  separated
       only  by	 spaces	and tabs, the comment is pushed	to before the punctua-
       tion to apply to	object there.

       The program is implemented using	a full ANSI C grammar parser with some
       GCC  extensions,	 this means that the style of the code is unimportant,
       only the	content	and comments.

   Cross Referencing
       The cross referencing is	performed for the following items

       Files
	The files that the current file	is included in
	(even when included via	other files).

       #includes
	Files included in the current file.
	Files included by these	files etc.

       Variables
	The location of	the definition of external variables.
	The files that have visibility of global variables.
	The files / functions that use the variable.

       Functions
	The file that the function is prototyped in.
	The functions that the function	calls.
	The functions that call	the function.
	The files and functions	that reference the function.
	The variables that are used in the function.

       Each of these items is cross referenced in the output.

       The cross referencing uses  files  `cxref.variable',  `cxref.function',
       `cxref.include' and `cxref.typedef' in the output directory.  These are
       a complete list of the function and variable usage in the  program  and
       could  be  used to generate a function call hierarchy or	variable usage
       diagram for example.  Two cxref passes of  each	file  is  needed,  the
       first  to  build	 up  the cross referencing files and the second	to use
       them.

       (The file names are different if	the `-N' option	is used.)

   LaTeX Output
       The default LaTeX output	is a file for each of the  source  files  with
       one extra file `cxref.tex' that includes	each of	the other files.  This
       is to allow a makefile to only update the changed files	(although  the
       references may require all of the files to be checked again).  When the
       cxref.tex file has been written it can be modified by the user, any new
       files  that  are	added are added	at the end of the source code section,
       the rest	of the file being unchanged.

       The index is written to a file called `cxref.apdx.tex' and cxref.tex is
       updated to refer	to it.

       Also  written  out  are three LaTeX style files `page.sty', `fonts.sty'
       and `cxref.sty'.	 These set up the page to use  a  smaller  margin  and
       smaller fonts to	allow more to appear on	a page and also	define the new
       commands	for typesetting	the cxref output.

       (The file names `cxref.tex' and `cxref.apdx.tex'	are different  if  the
       `-N' option is used.)

   HTML	Output
       The default HTML	output is a file for each of the source	files with one
       extra file `cxref.html' that includes each of the other files.  This is
       to allow	a makefile to only update the changed files (although the ref-
       erences may require all of the files to be checked  again).   When  the
       cxref.html  file	 has  been written it can be modified by the user, any
       new files that are added	are added at the end before the	table of  con-
       tents, the rest of the file being unchanged.

       The  index is written to	a file called `cxref.apdx.html'	and cxref.html
       is updated to refer to it.

       (The file names `cxref.html' and	`cxref.apdx.html' are different	if the
       `-N' option is used.)

       The HTML	output uses the	HTML 4.01 standard and all pages validate cor-
       rectly.

   RTF Output
       Rich Text Format	is a fairly low	level page description format  devised
       by Microsoft.  It is not	a well defined and easy	to understand standard
       as are the other	formats, but it	is popular for document	exchange.

       There is	a single output	file for each of the source files and an index
       file.

   SGML	Output
       Since SGML is a meta-language it	is necessary to	define the layout ele-
       ments as	well as	provide	the information.  The cxref  output  uses  the
       LinuxDoc	 document  format  and	is designed for	use with the SGMLtools
       programs	(http://www.sgmltools.org/).

       There is	a single output	file for each of the source files and an index
       file.

SEE ALSO
       The  files  that	come with the cxref source code	distribution give more
       information.  The README	file gives examples of how to use the comments
       in  source  code.   There  is  a	list of	frequently asked questions and
       their answers for the cxref program in the FAQ file.   A	 list  of  im-
       provements planned for future versions of the program are listed	in the
       file TODO.

       More  up-to-date	 information  can  be  found  on  the  cxref  homepage
       http://www.gedanken.org.uk/software/cxref/.

AUTHOR
       The cxref program was written by	Andrew M. Bishop in 1995-2004.

       The cxref program is copyright Andrew M.	Bishop 1995-2004.

       The cxref-cpp program is	copyright Free Software	Foundation, Inc.

       The cxref and cxref-cpp programs	can be freely distributed according to
       the terms of the	GNU General Public License (see	the file `COPYING').

				 June 15 2004			      cxref(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SEE ALSO | AUTHOR

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

home | help