I'm preparing the code documentation for C code with doxygen.
I would like to create an Errors section under the Parameters and Returns sections for each function in the output rtf document.
/**
* Some description
*
* #param[in] i4InputParam
*
* #error IOError
* #error RangeError
*/
In the online doxygen manual, I found \xrefitem command for this purpose.
In my doxygen configuration file I have the below aliases definition for #error tags:
ALIASES += error="\xrefitem #error \"Errors\" \"Errors\""
This alias creates the Errors section in function documentation as I want. However, it also creates an errors list section after TOC and before the file Index sections. I don't want this top level error list section.
The problem is that the "list title" parameter seems to be mandatory.
When I remove the third parameter it does not create neither of those Errors sections. When I set to empty \"\"" it still creates the top level error list.
Do you have any suggestions to force \xrefitem to ignore the "list title" parameter? or Do you suggest any other alternative to perform this operation?
Related
I'm trying to find a way to add a clickable link in org-mode that opens another local file and scrolls to a specific property id.
It's easier to explain with an example:
$ cat file1.org
* org links that I've tried and they don't work properly
[[file:path/to/another-file.org::#d89ba6bd-7c9a-4559-9965-7a6541f1a7c5][ref]]
[[file:path/to/another-file.org:id:d89ba6bd-7c9a-4559-9965-7a6541f1a7c5][ref]]
[[file:path/to/another-file.org::d89ba6bd-7c9a-4559-9965-7a6541f1a7c5][ref]]
[[file:path/to/another-file.org::id:d89ba6bd-7c9a-4559-9965-7a6541f1a7c5][ref]]
$ cat another-file.org
* Top category
** Category X
*** Question :drill:
:PROPERTIES:
:ID: d89ba6bd-7c9a-4559-9965-7a6541f1a7c5
:END:
Content of d89ba6bd-7c9a-4559-9965-7a6541f1a7c5 entry
*** Question :drill:
:PROPERTIES:
:ID: some-other-property-uuid
:END:
Content of some-other-property-uuid entry
Unfortunately, I can't change the structure of another-file.org. I can only reference using a property id.
Just renaming "Question :drill:" would have been much easier but it is duplicated many times and as I said it is not available for updates.
Update:
With "CUSTOM_ID" property it seems to be working
*** Question :drill:
:PROPERTIES:
:CUSTOM_ID: d89ba6bd-7c9a-4559-9965-7a6541f1a7c5
:END:
Content of d89ba6bd-7c9a-4559-9965-7a6541f1a7c5 entry
[[file:path/to/another-file.org::#d89ba6bd-7c9a-4559-9965-7a6541f1a7c5][ref]]
But is there any way to make it with with default :ID: property?
Try setting org-link-search-must-match-exact-headline to nil. That makes the third type of link above [[file:path/to/another-file.org::d89ba6bd-7c9a-4559-9965-7a6541f1a7c5][ref]] do a fuzzy text search, whereas the other values (t and the default query-to-create) are biased towards headlines when the target file is an Org mode file.
Here's the doc string of org-link-search-must-match-exact-headline:
org-link-search-must-match-exact-headline is a variable defined in ‘ol.el’.
Its value is nil
Original value was ‘query-to-create’
This variable is safe as a file local variable if its value
satisfies the predicate ‘symbolp’.
You can customize this variable.
This variable was introduced, or its default value was changed, in
version 24.1 of Emacs.
Documentation:
Non-nil means internal fuzzy links can only match headlines.
When nil, the a fuzzy link may point to a target or a named
construct in the document. When set to the special value
‘query-to-create’, offer to create a new headline when none
matched.
Spaces and statistics cookies are ignored during heading searches.
BTW, I found it by reading the External Links section of the manual: look for text search and the accompanying footnote.
I try to use a proper macro like .Bl with its .It to render list in mandoc (or per say man page) with the following syntax (as seen in mdoc.7)
The arguments are as follows:
.Bl -tag -width Ds
.It Fl v
Print verbose information.
.El
Tried both on macOS and Ubuntu 16.04 by putting into .SH DESCRIPTION, and it doesn't render expected output. All I see is
The arguments are as follows: Print verbose information.
The steps I do this is
Edit mandoc file
Symlink it to target file at /usr/local/share/man/man3/
See result by man <filename>
PS. I didn't go any gzip.
What did I miss? How can I properly render list in mandoc?
Instead, I look at mandoc's code of /usr/share/man/man1/bash.1 in which I view such man page via man /usr/share/man/man1/bash.1 for safety to ensure I view the right file.
It uses the following syntax
.TP 10
.BI Item Name
Item description
.TP
.BI Item Name 2
Item 2 description
This will properly renders those two items in which the first column has 10 character in width. The second item will use the same column width as defined before. Much cleaner and simpler than what I tried but with not success in the question.
You will see the following output using above syntax
I'm writing a README.md for one of my repositories on github.com.
As part of this README.md I'd like to include a quote of another README.md (from another repository), which implies using advanced markdown inside the quote.
Eventually I'd like to see something like this:
Item 1
Use the following:
First level of quoted list
Second level of quoted list
Nested quote
Item 2
For now I'm trying to achieve this with the following markdown:
* Item 1
* Use the following
> * First level of quoted list
> * Second level of quoted ***list***
> * > Nested *quote*
* Item 2
There are several online markdown editors out there that intend to simulate github markdown behavior: ones that work much better than github itself, others that are a bit more realistic, but in github it looks like this:
Item 1
Use the following
> * First level of quoted list > * Second level of quoted list > * > Nested quote
Item 2
So it appears that github supports some simple markdown inside the block quote (like bold, italic etc.), but it won't support the advanced markdown (like lists, quotes etc.)
Is there any way to quote a complex markdown on github?
GitHub is picky about requiring blank lines (to create a new pagragraph) before starting a blockquote. This seems to do what you want:
* Item 1
* Use the following
> * First level of quoted list
> * Second level of quoted ***list***
>
> * > Nested *quote*
* Item 2
* Parent
Some text under this level
** Headline below parent
** Another Headline at the same level
I don't want this text to be a headline but be indented same as the text under the parent level without being a headline. Cannot do this.
I just cannot re-indent this text just below the parent level here
* Another top-level headline
Is there any way in org-mode to re-indent plain text back to the same indent level as the plain text just under the parent level but below several headlines under the parent?
I am trying to do something like this:
* A Section
Introductory text.....
** Subsection 1
** Subsection 2
Further Reading
Now, that "Further Reading" is not a headline, I don't want it to be one. However, I cannot "get out of" Subsection 2: Anything I type below it is a part of it. Perhaps I need to structure this some other way such as using lists instead of headlines.
There is no way to do this in org, currently - there is no syntax that ends a subheader to return you to the previous level. But you could add a subsection at the same level - e.g. in your example,
* A Section
Introductory text.....
** Subsection 1
Subsection 1 text
** Subsection 2
Subsection 2 text
** Further Reading
Some further reading
It might be nice if org had some syntax, like **-, that would end a subsection, but I'm not sure how involved a change that would be - probably pretty extensive.
I am trying to use the doxygen to generate a user help, when I use the command \tableofcontents in the mainpage, nothing shows in the html output.I just don't know why, does anyone know how to use the command of tableofcontents? Some examples will be better, thanks!
Note that the browser is OK.
The solution key is to add a label to your headlines:
This is a level 1 header {#labelid_H1}
========================
This is a level 2 header {#labelid_H2}
------------------------
# This is a level 1 header # {#labelidH1}
## This is level 2 header ## {#labelidH2}
Then table of contents [TOC]
[TOC]
as well as headline links
[Link to first headline](#ref labelid_H1)
[Link to second headline](#labelid_H2)
are working.
Another point to mention is that Doxygen eats up the first line in the file that's used as mainpage (look for "Eat my shorts, Doxygen!" in: Use the README.md file as main page in Doxygen)