I am using doxygen to create documentation (a PDF) for a C project. I would like the index to show up in the TOC. This is simple enough with [pdf]latex.
Problem #1: I cannot use the tocbibind or idxlayout packages (see link above). If I attempt to use these with doxygen
EXTRA_PACKAGES = [nottoc]tocbibind
then doxygen writes to the TeX source file
\usepackage{[nottoc]{tocbibind}}
and the extra {} causes a LaTeX error. This seems to be a bug in doxygen?
Problem #2: This leaves me with the imakeidx package (again, see link above). In the doxygen config file
EXTRA_PACKAGES = imakeidx
But now I need to change from \makeindex to \makeindex[intoc].
Back to the Doxyfile:
MAKEINDEX_CMD_NAME = makeindex[intoc]
But this has no discernible effect. Any suggestions for actually getting the index to show up in the TOC?
The issue as described occurred in Doxygen 1.6.1. Problem #1 above has been fixed (see here). In Doxygen 1.8.7 (which I am now using) the index is included in the TOC without issue.
UPDATE: Problem #2 was based upon my own misunderstanding of a configuration option. See the comment from albert, who has proposed a patch that provides the functionality I wanted.
EDIT: The mentioned pull request 715 has been integrated in master on github.
Related
We want to keep track of changes in a LaTeX document in such a way that people who can't read LaTeX can also see the changes at once. The .tex files are stored in a git repository. So detailed information about the changes is available.
For this purpose I think it might be possible to use the git diff output between two revisions to generate the PDF and somehow mark the changes since the selected other revision of the document.
Do you know of an (easy) way to achieve this?
Do you know of other ways to visualize differences between PDF files?
[Expanding on my comment, since it apparently helped :-) ]
latexdiff is a Perl script that can diff two LaTeX documents and mark up changes without the distractions of the LaTeX markup itself. The README says:
latexdiff is a Perl script, which compares two latex files and marks
up significant differences between them (i.e. a diff for latex files).
Various options are available for visual markup using standard latex
packages such as "color.sty". Changes not directly affecting visible
text, for example in formatting commands, are still marked in
the latex source. Note that only files conforming to latex syntax will
be processed correctly, not generic TeX files. Some further
minor restrictions apply, see documentation.
A rudimentary revision facilility is provided by another Perl script,
latexrevise, which accepts or rejects all changes. Manual
editing of the difference file can be used to override this default
behaviour and accept or reject selected changes only.
The author is F Tilmann.
The project is developed on Github, but you can get the script in a tarball from CTAN if you prefer. The link in the comment is a useful overview of how to use it.
I'm trying to use doxyqml to produce QML documentation through doxygen, but the documentation pages are not being created.
As per the doxyqml documentation I've added a *.qml entry to FILE_PATTERNS, and added *.qml=doxyqml to FILTER_PATTERNS (doxyqml is available from /usr/bin so just calling doxyqml on the command line is sufficient to launch it).
From the doxygen output I can see that the *.qml file pattern is working as the files appear in the 'Reading' stage of the output - but not the parsing stage. If I add a #define or some other non-QML statement to the files then a doxyqml error appears in the doxygen output, so I know that doxyqml is being called correctly.
I also know that the doxyqml output is correct because if I copy the output from calling doxyqml directly with one of the qml files, and paste it into a *.h file, doxygen builds the documentation for it.
It's almost as if doxygen is just not reading the output from doxyqml. Has anyone else had this experience? I'm using doxygen 1.8.8 and the latest doxyqml codebase (7th July 2014).
It seems to be because Doxygen uses the file extension to work out what parser to use to analyse the text, and because *.qml is new to it, it was guessing wrong (though I don't know which it was attempting to use).
The solution was to tell Doxygen which parser to use for QML files, so I just needed to add qml=c++ to EXTENSION_MAPPING, and then everything worked as expected.
There are several doxygen commands whose purpose is to create links in the documentation (#link, #ref).
I am currently using the #ref command to create a link to a custom file, written in a language not supported by doxygen (xml).
I would like to alter this link so that it points to a precise line in the file.
Is there a doxygen command that allows to do that ?
I'm not sure that \ref or \link can do this. However, if they could, one problem of adopting this approach is that the links will become invalid if you change the contents of the file you are linking to without changing the link. This is one of the problems of separating source code and documentation.
Rather than linking to a particular line in another file why don't you include the particular part of the file you are interested in in the documentation? You could either:
include the whole file with \include (there is also \includelineno) and just reference relevant parts of it in the text (e.g. "function xxx in the code below"), or
include snippets of the file where you need to refer to them in the documentation using \snippet.
Edit: Alternatively, you could use the \dontinclude command which, together with the \line, \skip, \skipline, and \until commands allows you to include specific lines/blocks of a particular file. See the example in the \dontinclude documentation.
Im using doxygen outside of its design, but well within its capability. I have a bunch of essentially text files, appended with some doxygen tags. I am successfully generating doxygen output. However, somehow doxygen occasionally discovers what it assumes to be a variable, and proceeds to document it using surrounding text, causing a lot of confusing documentation. I cant see any direct relationship between these anomalies, only that they're reproducing the same output on each run, and what I can see is at least some are next to a ';' or a '='.
I only want doxygen to document what I've manually tagged. I am hoping to remove any occurrence of these anomalies, however I cannot alter existing text. I can only add doxygen tags, or alter the configuration file. Any ideas?
Many thanks.
Because in my particular case, I do not need any automatically generated documentation, only that which I have tagged with doxygen tags, setting
EXCLUDE_SYMBOLS = *
removes any instance of doxygen "finding" and documenting variables. This however may remove any ability to find any class declarations, namespaces or functions, however this is acceptable for me.
I'd love to ask you how do the guys developing dojo create the documentation?
From nightly builds you can get the uncompressed js files with all the comments, and I'm sure there is some kind documenting script that will generate some html or xml out of it.
I guess they use jsdoc as this can be found in their utils folder, but I have no idea on how to use it. jsDoc toolkit uses different /**commenting**/ notations than the original dojo files.
Thanks for all your help
It's all done with a custom PHP parser and Drupal. If you look in util/docscripts/README and util/jsdoc/INSTALL you can get all the gory details about how to generate the docs.
It's different than jsdoc-toolkit or JSDoc (as youv'e discovered).
FWIW, I'm using jsdoc-toolkit as it's much easier to generate static HTML and there's lots of documentation about the tags on the google code page.
Also, just to be clear, I don't develop dojo itself. I just use it a lot at work.
There are two parts to the "dojo jsdoc" process. There is a parser, written in PHP, which generates xml and/or json of the entirety of listed namespaces (defined in util/docscripts/modules, so you can add your own namespaces. There are basic usage instructions atop the file "generate.php") and a Drupal part called "jsdoc" which installs as a drupal module/plugin/whatever.
The Drupal aspect of it is just Dojo's basic view of this data. A well-crafted XSLT or something to iterate over the json and produce html would work just the same, though neither of these are provided by default (would love a contribution!). I shy away from the Drupal bit myself, though it has been running on api.dojotoolkit.org for some time now.
The doc parser is exposed so that you may use its inspection capabilities to write your own custom output as well. I use it to generate the Komodo .cix code completion in a [rather sloppy] PHP file util/docscripts/makeCix.php, which dumps information as found into an XML doc crafted to match the spec there. This could be modified to generate any kind of output you chose with a little finagling.
The doc syntax is all defined on the style guideline page:
http://dojotoolkit.org/reference-guide/developer/styleguide.html