How to embed shell snippets in doxygen documentation

Question

When installing my package, the user should at some point type

./wand-new "`cat wandcfg_install.spell`"

Or whatever the configuration file is called. If I put this line inside \code ... \endcode, doxygen thinks it is C++ or... Anyway, the word "new" is treated as keyword. How do I avoid this is in a semantically correct way?

I think \verbatim is disqualified because it actually is code, right?

(I guess the answer is to poke that Dimitri should add support for more languages inside a code block like LaTeX listings package, or at least add an disableparse option to code in the meantime)

Answer 1

Doxygen, as of July 2017, does not officially support documenting Shell/Bash scripting language, not even as an extension. There is an unofficial filter called bash-doxygen. Simple to setup: only one file download and three flags adjustments:

• Edit the Doxyfile to map shell files to C parser: EXTENSION_MAPPING = sh=C
• Set your shell script file names pattern as Doxygen inputs, like e.g.: FILE_PATTERNS = *.sh
• Mention doxygen-bash.sed in either the INTPUT_FILTER or the FILTER_PATTERN directive of your Doxyfile. If doxygen-bash.sed is in your $PATH, then you can just invoke it as is, else use sed -n -f /path/to/doxygen-bash.sed --.

Please note that since it uses C language parsing, some limitations apply, as stated in the main README page of bash-doxygen, one of them, at least in my tests, that the \code {.sh} recognises shell syntax, but all lines in the code block begin with an asterisk (*), apparently as a side-effect of requiring that all Doxygen doc sections have lines starting with double-hashes (##).