## Package: cxref / 1.6e-1

 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615 Description: Upstream changes introduced in version 1.6c-1 This patch has been created by dpkg-source during the package build. Here's the last changelog entry, hopefully it gives details on why those changes were made: . cxref (1.6c-1) unstable; urgency=low . * New upstream release . The person named in the Author field signed this changelog entry. Author: Camm Maguire --- The information above should follow the Patch Tagging Guidelines, please checkout http://dep.debian.net/deps/dep3/ to learn about the format. Here are templates for supplementary fields that you might want to add: Origin: , Bug: Bug-Debian: http://bugs.debian.org/ Bug-Ubuntu: https://launchpad.net/bugs/ Forwarded: Reviewed-By: Last-Update: Index: cxref-1.6e/README-1.html =================================================================== --- /dev/null +++ cxref-1.6e/README-1.html @@ -0,0 +1,376 @@ + + + + + C Cross Referencing & Documenting tool. Version 1.5.: C Cross Referencing & Documenting tool. Version 1.5 - cxref + + + + +Next +Previous +Contents +
+

1. C Cross Referencing & Documenting tool. Version 1.5 - cxref

+ +

A program that can automatically generate documentation and cross references for +a C program.
+The input is any C program with appropriate comments and the output is LaTeX, +HTML, RTF or SGML files.

+ +

1.1 Program Options +

+ +

The name of the program is cxref.

+

+

+
+Usage: cxref filename [ ... filename] +             [-Odirname] [-Nbasename] [-Rdirname] +             [-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] +             [-latex209|-latex2e] +             [-html20|-html32][-src] +             [-rtf] +             [-sgml] +             [-Idirname] [-Ddefine] [-Udefine] +             [-CPP cpp_program] [-- cpp_arg [ ... cpp_arg]] + +Usage: cxref filename [ ... filename] -delete +             [-Odirname] [-Nbasename] [-Rdirname] +
+
+

+

+

+
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 +reference 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.

+

In case you think that the existing comments might work, +(see below for description of special comments).
+[Danger! This option can produce weird results.]

+

Ignores all comments, useful if you just want the cross +references and not the documentation.

+

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

+

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

+
-xref

Warn of missing cross references.

+
+

+
-index

Produce a cross reference index, the options 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, not really of much use except +with -warn.

+
-latex209

Produce a LaTeX file to document each of the source files and +also an extra file that includes each of these files. (Using +the LaTeX version 2.09 format.)

+
-latex2e

Produce the LaTeX file described above for use with the +LaTeX2e version of LaTeX.

+
-html20

Produce an HTML file to document each of the source files and +a main file to reference each of these files. (using the HTML +2.0 standard, no tables).

+
-html32

Produce the HTML file described above but using HTML 3.2.

+
-rtf

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

+
-html20-src

Produce the HTML v2.0 output and a HTML version of the source +file with links into it.

+
-html32-src

Produce the HTML v3.2 output and a HTML version of the source +file with links into it.

+
-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 to work. If the program takes +arguments 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.

+
+

+ +

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

+ +

1.3 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. +
3. Those in the .cxref' file in the current directory.
4. +
5. Those in the .cxref' file in the source tree root specified by -R'.
6. +
+

+

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.

+

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.

+ +

+ +

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 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, ++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.

+ +

1.5 Automated Comment Insertion +

+ +

To simplify the insertion of comments that will be parsed by cxref, the file +cxref.el provides a number of Emacs lisp functions. To use them add the line +(load "cxref") to your .emacs' file or type M-x load-file cxref.el from +within Emacs.

+

The functions and key bindings are: +

+
Control-C Control-X Control-F

Adds file comments, a /** **/ header at the top of the +file and if it is a .h file then it also adds a #ifndef, +#define at the beginning and #endif at the end to stop +multiple inclusions.

+
Control-C Control-X f

Adds comments to a function, the cursor must be on the +line containing the start of the function definition when +this function is called. The /*+ ... +*/ comment that is +added is of the header type (see the examples) not inline.

+
Control-C Control-X v

Adds a leading comment to the variable or other definition +on the current line.

+
Control-C Control-X e

Adds a trailing comment at the end of the line.

+
Control-C Control-X i

Adds an inline comment that is ignored by cxref.

+
+

+ +

1.6 C Preprocessor +

+ +

To improve the output that is available a modified version of the GNU CPP V2.7.2 +is supplied (named cxref-cpp).
+This modified C preprocessor allows for a finer control over some features of +the preprocessing that are not important for a compiler. In a standard +preprocessor, the preprocessor directives are intended for use only by the +preprocessor, so passing the information through is not important.
+With cxref-cpp, there are two features that are different to the standard GNU +CPP: +

+
1. The #include directives from the file are output in the same way as the +#defines are output. An extra flag has been added to cpp to do this, '-dI', +it works in the same way as the existing '-dD' flag for #defines.
2. +
3. Comments trailing a #include or a #define are dropped with GNU CPP even if -C +is used. This is not important while compiling but is useful for documenting.
4. +
+

+ +

1.7 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.)

+ +

1.8 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.)
+The two different forms of LaTeX output are selected by using the -latex209 or +the -latex2e options. These select between two sets of output that can be used +with those two different versions of LaTeX.

+ +

1.9 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.
+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 two different forms of HTML output are selected by using the -html20 or the +-html32 options. These select between two sets of output that comply with the +HTML 2.0 and 3.2 definitions, they differ in their use of tables.

+ +

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

+ +

1.11 SGML Output +

+ +

Since SGML is a meta-language it is necessary to define the layout elements 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.

+ +

1.12 Further Information +

+ +

There is a list of frequently asked questions and their answers for the cxref +program in the FAQ file. A list of improvements planned for future versions of +the program are listed in the file TODO.

+

More up-to-date information can be found on the World Wide Web at the cxref +homepage, reached via the author's homepage http://www.gedanken.demon.co.uk/.

+

If you wish to submit bug reports or other comments about the program then email +the author amb@gedanken.demon.co.uk and put cxref in the subject line.

+ +

+ +

The cxref program was written by Andrew M. Bishop in 1995,96,97,98,99.
+The cxref program is copyright Andrew M. Bishop 1995,96,97,98,99.
+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').

+ +

The functions and key bindings are:

-
Control-C Control-F +
Control-C Control-X Control-F
Adds file comments, a /** **/ header at the top of the file and if it is a .h file then it also adds a #ifndef, #define at the beginning and #endif at the end to stop multiple inclusions. -
Control-C f +
Control-C Control-X f
Adds comments to a function, the cursor must be on the line containing the start of the function definition when this function is called. The /*+ ... +*/ comment that is added is of the header type (see the examples) not inline. -
Control-C v +
Control-C Control-X v
Adds a leading comment to the variable or other definition on the current line. -
Control-C e +
Control-C Control-X e
Adds a trailing comment at the end of the line. -
Control-C i +
Control-C Control-X i
Adds an inline comment that is ignored by cxref.
Index: cxref-1.6e/doc/README =================================================================== --- cxref-1.6e.orig/doc/README +++ cxref-1.6e/doc/README @@ -204,22 +204,22 @@ within Emacs. The functions and key bindings are: -Control-C Control-F - Adds file comments, a /** **/ header at the top of the +Control-C Control-X Control-F - Adds file comments, a /** **/ header at the top of the file and if it is a .h file then it also adds a #ifndef, #define at the beginning and #endif at the end to stop multiple inclusions. -Control-C f - Adds comments to a function, the cursor must be on the +Control-C Control-X f - Adds comments to a function, the cursor must be on the line containing the start of the function definition when this function is called. The /*+ ... +*/ comment that is added is of the header type (see the examples) not inline. -Control-C v - Adds a leading comment to the variable or other definition +Control-C Control-X v - Adds a leading comment to the variable or other definition on the current line. -Control-C e - Adds a trailing comment at the end of the line. +Control-C Control-X e - Adds a trailing comment at the end of the line. -Control-C i - Adds an inline comment that is ignored by cxref. +Control-C Control-X i - Adds an inline comment that is ignored by cxref. -------------------------------------------------------------------------------- -------------------------------- C Preprocessor -------------------------------- Index: cxref-1.6e/src/latex.c =================================================================== --- cxref-1.6e.orig/src/latex.c +++ cxref-1.6e/src/latex.c @@ -935,8 +935,8 @@ static void WriteLatexTemplate(char* nam fputs("\n",template); fputs("% Contents (Optional, either here or at end)\n",template); fputs("\n",template); - fputs("%\\markboth{Contents}{Contents}\n",template); - fputs("%\\tableofcontents\n",template); + fputs("\\markboth{Contents}{Contents}\n",template); + fputs("\\tableofcontents\n",template); fputs("\n",template); fputs("\\chapter{Source Files}\n",template); fputs("\n",template); @@ -946,8 +946,8 @@ static void WriteLatexTemplate(char* nam fputs("\n",template); fputs("% Contents (Optional, either here or at beginning)\n",template); fputs("\n",template); - fputs("\\markboth{Contents}{Contents}\n",template); - fputs("\\tableofcontents\n",template); + fputs("%\\markboth{Contents}{Contents}\n",template); + fputs("%\\tableofcontents\n",template); fputs("\n",template); fputs("\\end{document}\n",template); Index: cxref-1.6e/contrib/cxref.el =================================================================== --- cxref-1.6e.orig/contrib/cxref.el +++ cxref-1.6e/contrib/cxref.el @@ -15,11 +15,11 @@ ;;;###autoload (defun cxref-c-mode-common-hook () "Set up the key bindings for cxref in cc-mode" - (define-key c-mode-map "\C-c\C-f" 'cxref-file-comment) ;; Control-C Control-F - (define-key c-mode-map "\C-cf" 'cxref-function-comment) ;; Control-C f - (define-key c-mode-map "\C-cv" 'cxref-variable-comment) ;; Control-C v - (define-key c-mode-map "\C-ce" 'cxref-endline-comment) ;; Control-C e - (define-key c-mode-map "\C-ci" 'cxref-inline-comment) ;; Control-C i + (define-key c-mode-map "\C-c\C-x\C-f" 'cxref-file-comment) ;; Control-C Control-F + (define-key c-mode-map "\C-c\C-xf" 'cxref-function-comment) ;; Control-C f + (define-key c-mode-map "\C-c\C-xv" 'cxref-variable-comment) ;; Control-C v + (define-key c-mode-map "\C-c\C-xe" 'cxref-endline-comment) ;; Control-C e + (define-key c-mode-map "\C-c\C-xi" 'cxref-inline-comment) ;; Control-C i ) ;;;###autoload `