I am producing the documentation with doxygen, and I have a tutorials tab where I have few pages links I produce in doxygen MarkupLanguage.
In my DoxygenLayout.xml I have the following
<tab type="pages" visible="yes" title="Tutorials" intro="Here ..." />
Then I have a directory in my doxygen folder named ../tutorials/
I include that folder on my doxygen.cfg, and include .md files
INPUT = ../../source ../tutorials/
FILE_PATTERNS = *.cxx *.h *.md
The problem is if I specify inside the file tutorial1.md
\page tut_1 A first tutorial
The tutorials TAB will show 2 entries for that page. One with the name of the file (tutorial1) and another with the name of the page (A first tutorial).
What to do so that it only shows the entry "A first tutorial?"
If I do not specify the \page tag then I will have a single entry, but then I cannot reference to this page from other pages.
Is there a simple solution?
Related
I have a rather complex project and I want to document it using doxygen.
I have no problem documenting the code and I also managed to have a nice front-page using a custom README.md file coupled with "USE_MDFILE_AS_MAINPAGE = README.md" directive in Doxyfile.
I defined several groups (#defgroup) which show up as "Modules" in my documentation.
I would like to add a "main page" to each of the group giving general information, beside the customary function/variable/type documentation.
I tried adding custom MODULENAME.md files coupled with matching #includedoc MODULENAME.md entries in group definition, it seem to work (I see several lines like: "Generating docs for page md_mcu_noitr_coro_README..."), but I cannot find if and where the page is linked (I expected to see it in the "Detailed Description" for the module, as it happens if I put some documentation inline where I put the "#includedoc" directive.
a snippet of one of my modules is:
/**
* #file coro.h
* #brief definition of coroutine implementing functions.
*
* #date: Feb 8, 2018
* #author: myself
*
* #defgroup coro "Coroutine implementation in plain 'C'."
*
* #includedoc mcu_noitr/coro/README.md
* #{
*
*/
What am I doing wrong?
Note: it is also a bit surprising I need to put the whole path from where my Doxyfile is, otherwise doxygen won't find it even if it's right beside the file containing the #includedoc command.
I also came across the problem that included files with Markdown formatted text via \includedoc or \include{doc} does not result in correctly interpreted Markdown. Note that I included Markdown files from other Markdown files. My work-around was to use the C pre-processor (cpp) - which is widely available - on Markdown files and use it's #include directive. You could of course use a true general text processor such as M4 as suggested in the cpp man page. Set FILTER_PATTERNS in Doxyfile as:
FILTER_PATTERNS = *.md="cpp -P -traditional-cpp"
You'll need the -P option to avoid it outputting line markers, which confuses Doxygen. -traditional-cpp was needed to avoid cpp eating white space that is important for the correct interpretation of Markdown. Don't use single quotes as this results in an error when Doxygen calls cpp via sh.
Then in my Markdown main page:
Main Page {#mainpage}
==========
Blah blah blah.
#include "other.md"
Using FILTER_PATTERNS instead of INPUT_FILTER avoids the problem about not being allowed to add or remove lines.
I have my markdown files in the same directory, I would guess that if they are located in different places you could tell cpp about it via -I, which would address your expectations about include paths on the issue you filed.
At the moment doxygen does not consider the fact that commands like \includedoc can contain markdown code. At the moment the only possibility would be to write a filter, see configuration parateter INPUT_FILTER in the doxygen configuration file, (not tested!) to replace the \includedoc` with the code of that file.
Is it posible to import a BibTex library in Libre Office Writer?
I have a BibTex file that was generated with BibDesk and which I woul like to import in Libre Office.
Yes BibDesk can export to .doc (libre can import .doc) and many other formats. You can aslo modify the formats
Ref sourceforge SEC117
Export Templates
Templates allow you to export your database to a large variety of formats. It also allows you to customize to a great extent how the data is exported.
To export using templates, choose the "Export..." menu item, which can be found under the "File" menu. You can choose the template from the "File Format" popup button. You can either export the whole database, or just the references which you have selected.
BibDesk provides several default templates, for export to HTML, RSS, Rich Text (RTF, RTFD) and to windows Doc format.
You can also modify a template
Bibdesk Templates
You can find a set of default template files in the folder ~/Library/Application Support/Bibdesk/Templates. For HTML export, there are 3 template files: htmlExportTemplate.html, htmlItemExportTemplate.html and htmlExportStyleSheet.css. Generally, only the first of these template files is required
Looking at the htmlExportTemplate.html file first, this is a relatively simple html document, with a standard header, a link to the external CSS file, and a single "content" div in the body. The formatting of the individual entries into the html file is done using the htmlItemExportTemplate.html file. Opening this file, you will see that the template files comprise a series of items enclosed in < and > signs, the same as those used in HTML to enclose formatting tags, but starting with an extra $. These entities are known as Template Tags.
They are parsed by BibDesk to include the relevant parts of the BibDesk database in the html file. E.G. will be replaced by the contents of the "Title" field in the BibDesk database. A list of the different kinds of Tag is given in the Export Template Keys page. It is also possible to apply modifiers to the field Tags in order to format the contents. One example is the Tag where the full name or an abbreviated name can be chosen, and the "and"s between authors can be replaced by commas. These modifier keys are also explained at the Export Template Keys page.
I hope this helps
I am trying to run doxygen on some source files for a project that I downloaded source files for. The files are located in the following directories:
doc/ - Documentation files, such as .dox files.
src/ - Source files
My settings in my doxygen.config file are:
INPUT = ../ .
FILE_PATTERNS = *.h *.dox *.dxx
When I run doxygen (doxygen doxygen.config), it generates all of the documentation from the .h files correctly, but it does not generate the mainpage correctly. I have a file titled intro.dox in the doc folder, with a command \mainpage Documentation Index, and a bunch of text, but doxygen is not using this to generate the main page.
What am I doing wrong?
There are (at least) two possible reasons for this:
You are not including the /doc directory in you INPUT list. Try modifying this to
INPUT = ../ . ../doc
Did you mean to write ../doc instead of ../? I am guessing that your doxygen.config file is in your src directory. If this is not the case can you make this clear in the question.
Doxygen requires that your documentation files (your .dox files) are plain text with your text wrapped with Doxygen C++ comments (i.e. /** ... */).
Without knowing where doxygen.config is located, and since you are using relative paths in INPUT, it is difficult to determine what might cause this, however since the files you are looking for are in parallel directories, it is possible that doxygen is not search recursively for your files. You may want to confirm that RECURSIVE is set to YES in doxygen.config.
I'm trying to use \cite in Doxygen to produce a bibliography page and also a reference within my text. I have bibtex in my search path and a proper .bib file. I have added the .bib file to CITE_BIB_FILES and am using a proper BibTex label found in the .bib file. Doxygen is creating a bibliography page, but it is empty. It is also creating a citation link in the documentation text, but the link is also empty. Any idea how I can get the citation info displayed?
I was facing the same problem. There is an perl dependency to generate citation. So you must have both perl and bibtex in the system path.
Ignore the example above, that only applies to Latex, for doxygen use (Note: no braces):
\cite Hale
The .bib file has to be located in doxygen working directory.
Bibliographic References HTML page will be then produced by doxygen with:
[1]J. K. Hale. Theory of functional–differential equations. Springer–Verlag, Berlin–Heidelberg–New York, 1977.
for the following bib entry:
#BOOK{Hale,
author = "J. K. Hale",
title = "Theory of functional--differential equations",
publisher = "Springer--Verlag, Berlin--Heidelberg--New York",
year = 1977
}
In order for \cite to work properly you need:
be sure to put your file.bib in the working directory where you call doxygen Doxyfile
bibtex executable must be in the search path
perl executable must be in the search path
the RefName used in \cite RefName must have a corresponding entry in file.bib
Maybe a little late, but I had the same problem. Doxygen generated a bibliography for LaTeX output, but not for HTML output and none of the proposed answers worked for me.
As suggested by #Raffi, this seems to be a bug in Doxygen < 1.8.3. I used Doxygen 1.8.1.1 and it did not work. Then I installed Doxygen 1.8.3.1 without changing anything else and it worked fine.
When you set CITE_BIB_FILES in DoxyFile did you include the .bib extension on the filename?
Doxygen claims it will automatically add the .bib extension, but if you omit it doxygen seems to gets confused and doesn't generate the citelist.doc file properly.
Include .bib in the filename and it should work fine, at least that is the case for me.
In order to create a bibliography you need to instal Perl, and add it to the search path, along with bibtex. In the documentation
for CITE_BIB_FILES it says:
"The CITE_BIB_FILES ... To use this feature you need bibtex and perl available in the search path ... "
In org-mode, when you export HTML projects you can use templates to give all exported pages the same options, this is described here http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html. What I would like to do, is give all exported pages an HTML snippet, for analytics, which is not an option. Is this possible with org-templates?
Now, I tried to add literal HTML code to the base template level-0-template.org with
#begin_html
...
#end_html
but it didn't work out. Does anyone know how to add html code to each HTML file that is exported in the project?
My project is organized as follows:
|- org
|- index.org
|- html
|- index.html (this is exported)
|- templates
|- level-0.org (I'd like to include default html here)
|- org_publish.el (this is the publishing config file)
To expand on my comment in the question, here is the difference between #+setupfile: and #+include:.
Details about both are available in the Org-Mode manual. See Setup File and Include Files.
The setupfile is essentially a list of all org configurations that are included in the linked file. It will pass things such as #+options. It will not however include any other content that the original file might include.
On the other hand, #+include: inserts the content of the linked file wherever the line is inserted. It acts similarly to \input in LaTex. I'm not certain to what degree it will bring along any org-configuration settings from the linked file, you may need to both #+include and #+setupfile the file to ensure everything is present. However since you do want the body content of the file to be included in each, you have to use #+include to insert it.
Glad you found a solution to your problem by sourcing your snippet as a separate html file.
If you wanted to make it work by having the snippet directly included in your template file, you should use:
#+BEGIN_export html
...
#+END_export
instead of:
#+BEGIN_html
...
#+END_html
(The latter will embed the html chunk as a block in the rendered html page-not what you want; the former will export the html chunk as is in the html file so that that code will be rendered when the page is displayed-what you want).