cxref(1)

💖 cxref — C Cross Referencing & Documenting tool 💖

okay bestie, sit down, hydrate, because this is the tool for making your C code look like it actually has its life together. it's cxref, from section 1 of the General Commands Manual. she's giving documentation generator, she's giving cross-referencer, she's giving main character. let's go 🫶

---

✨ 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]

and also, the delete-y mode:

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

---

🦋 DESCRIPTION 🦋

It's a program that just... automatically generates documentation and cross references for a C program. no cap. you feed her a C program that has appropriate comments, and she hands you back LaTeX, HTML, RTF or SGML files. it's giving glow-up but for source code 💅

---

🎀 OPTIONS 🎀

• filename — the name of the file to document. you can pass literally any number of files and she'll document them all at once. iconic, no notes.
• -delete — the files you named get yeeted from the output directory, and their entries in the cross reference database and the main output files get removed too. 🗑️
• -Odirname — the name of a directory to use for the output latex files, and also the location of the cross reference files that get created. one directory, two jobs, she's versatile.
• -Nbasename — the name to use for the first part of the output and cross reference files, instead of cxref. the file extensions stay exactly the same, don't worry.
• -Rdirname — for when your source files are spread across more than one directory: set dirname to the name of the root directory of the source tree (use a relative path if that's easier, e.g. -R../..). this then runs cxref from that root directory, and the -Odirname must be relative to that directory. 🧭
• -all-comments — for when you think the existing comments might work, (see above for description of special comments). [Danger! This option can produce weird results.] 💀
• -no-comments — ignores all comments. useful if you just want the cross references and not the documentation. minimalism era.
• -verbatim-comments — when the comments in your code are formatted in a predetermined style that you want to preserve on the output, this option forces 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 removes 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. heads up bestie, 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. again, these must be concatenated 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. ngl it's 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 default. the program must be able to perform all of the actions that gcc -E -C -dD does, otherwise it won't work. if the program takes arguments, then the whole thing needs to be in quotes so that it's 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 🧚

so to make using cxref on existing source code not be a whole ordeal, there's now a shell script that calls the C compiler and then calls cxref to process the source file. which means yes, it can be used as a drop in replacement for CC in Makefiles and the like. slay.

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 appropriate. The main directory can have a .cxref file containing the remainder of the options. This removes completely the need to have any options on the command line apart from the source file names. obsessed.

The format of the .cxref file is any number of lines, each one containing 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. zero effort, maximum output, that's the vibe.

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 ignored.

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, and +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 punctuation 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 matter. we love a judgement-free parser.

---

⭐ 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 references 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 contents, the rest of the file being unchanged.

okay so the index gets written out to a file literally called cxref.apdx.html, and then cxref.html gets updated so it refers to that index. slay. 💅

(and heads up bestie — if you used the -N option, those file names cxref.html and cxref.apdx.html are gonna be different. just saying. 🙈)

the HTML output is on the HTML 4.01 standard, and every single page validates correctly. no cap, all of them. ✨

---

🍓 RTF Output 🍓

okay so Rich Text Format is a fairly low level page description format that Microsoft came up with. ngl it is not a well defined and easy to understand standard the way the other formats are, but it's popular for document exchange so here we are. 💀

there's a single output file for each of the source files, plus an index file. periodt.

---

🌈 SGML Output 🌈

so since SGML is a meta-language, you literally have to define the layout elements as well as provide the information. that's just the deal. 🦋

the cxref output uses the LinuxDoc document format, and it's designed for use with the SGMLtools programs (http://www.sgmltools.org/).

and yep — a single output file for each of the source files, plus an index file. 💖

---

👑 SEE ALSO 👑

the files that come with the cxref source code distribution have so much more for you, bestie. like:

• README — gives examples of how to use the comments in source code. 🎀
• FAQ — a list of frequently asked questions and their answers for the cxref program.
• TODO — a list of improvements planned for future versions of the program.

and if you want more up-to-date information, the cxref homepage is at http://www.gedanken.org.uk/software/cxref/. go look, iykyk. 🫶

---

💜 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.

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

---

and that's the whole page, bestie!! this one's dated June 15 2004 and it's the cxref(1) manual page — go forth and cross-reference your little heart out. 🌸🦋💖