How to use Doxygen tableofcontents command - doxygen

I am trying to use tableofcontents command from Doxygen Doc.
To me \tableofcontents['{'[option[:level]][,option[:level]]*'}'] seems very cryptic.
Could you give an example of how to pass options and levels?

From the doxygen documentation:
24.111 \tableofcontents['{'[option[:level]][,option[:level]]'}']
Creates a table of contents at the top of a page, listing all sections and subsections in the page. The option can
be HTML or LaTeX or XML or DocBook. When a level is specified this means the maximum nesting level that
is shown. The value of level should be in the range 1..5, values outside this range are considered to be 5. In
case no level is specified level is set to 5 (show all) In case no option. is specified \tableofcontents
acts as if just the option HTML and XML was specified. In case of multiple \tableofcontents commands
in a page the option(s)
See also the beginning of the chapter "Special Commands" where a small description is of some of the used symbols.
So e.g.:
\tableofcontents
\tableofcontents{HTML}
\tableofcontents{HTML:3}
\tableofcontents{HTML:2,LaTex:3}

Related

Hide the documentation source file link in doxygen

Doxygen shows at the end of each html file the text "The document for this ... was generated from the following file..."
Is it possible to remove this text by using an option in the doxyfile?
With the aid of the configuration parameter SHOW_USED_FILES it is possible to disable the sentence ""The documentation for this...".
From the documentation:
SHOW_USED_FILES
Set the SHOW_USED_FILES tag to NO to disable the list
of files generated at the bottom of the documentation of classes and
structs. If set to YES, the list will mention the files that were used
to generate the documentation.
The default value is: YES.

Page numbers in scribble/acmart

I'm creating a pdf with the scribble/acmart language. How can I add page numbers to my document?
Make a LaTeX file with the line \settopmatter{printfolios=true}
If the file is named texstyle.tex, invoke Scribble with the command:
scribble ++style texstyle.tex --pdf FILE.scrbl
The rendered FILE.pdf should have line numbers.
(If you already had a ++style file, just add the \settopmatter line to that.)
The solution Ben gave is one way. But you can actually do this without modifying your texstyle.tex file.
If you add the following lines to your document, the appropriate topmatter will be added to your pdf file:
#para[#:style 'pretitle]{
#elem[#:style "settopmatter"]{
printfolios=true}}
You can see it doing this by running:
> scribble --latex myfile.scrbl
If you do this, you will notice the following line in your pdf file:
\settopmatter{printfolios=true}\titleAndVersionAndAuthors{Hello}{6.9.0.4}{\SNumberOfAuthors{1}\SAuthor{World}}
(Where Hello and World is the name and author of your paper, and the \title... macro runs \maketitle.)
This works because the 'pretitle style (when given to a paragraph), pulls its entire body above the title.
And whenever a string is given as the style for an element, it maps to the a latex command.
That is, this scribble code:
#elem[#:style "mycommand"]{Thebody}
Maps to:
\mycommand{Thebody}
The result of composing these two forms together is to drag this to the top of the file.
And because you've done this in scribble rather than latex, you can use Racket's semantics to add page numbers. For example, if you use your own #lang, you can now have the language decide whether or not you want pages.

asciidoc: is there a way to create an anchor that will be visible in libreoffice writer?

Tl;dr;
What is the correct way to create an anchor in docbook? and is there a way that will make the anchor visible in writer?
Background
I am trying to split up documentation that was previously in single open office documents into smaller asciidoc documents which are both included in the main open office document and also converted to either or both of html & pdf.
I have this mostly working. I use asciidoctor to create html. asciidoctor-pdf to create pdf and a combination of asciidoctor and pandoc to create .odt files. I also tried the python implementation of asciidoc but found the interface less useable.
Round tripping between asciidoc and odt is obviously not possible. This is sort of a fusion where the master document is word processed but pieces of content that can be produced independently (think man pages - in fact that is one of several use cases) are included.
asciidoc to html:
asciidoctor -b html5 foo.adoc -o foo.html
asciidoc to pdf:
asciidoctor-pdf -b pdf foo.adoc -o foo.pdf
asciidoc to odt
asciidoctor -b docbook foo.adoc -o foo.docbook
pandoc --base-header-level=3 -V date:"" -V title:"" -f docbook foo.docbook -o foo.odt
With pandoc I have to nullify the date and title and set the header-level as desired for the section to be inserted as an extra complication.
I insert the resulting .odt into the main document using insert section inside open office.
Note that the main document is not a master document as I could not find a way of creating a master document without also automatically splitting the file on h1 boundaries.
I have two main problems to resolve with this set-up. I would like to add headings in the asciidoc document as cross references and also create entries for them in the alphabetical index (actually the first heading would be suffcient). Is there a way to do this?
Index markers in asciidoc do not result in entries in .odt file being created.
I am able to cross reference content in the inserted section using "insert reference/heading" and referencing the uniquely named header. However, whenever I use "update all" these cross references are invalidated. They are shown as "Error: Reference source not found".
[On a separate note I would also like a way to find broken cross references automatically]
I am currently using libreoffice - Version: 4.3.7.2
I am not adverse to switching version or flavours (i.e. apache) if one behaves better than the other.
I'm not sure if the answer is in the asciidoc or docbook parts of the chain. I would accept an answer which inserts a index entry at the start of the inserted section (top of the .adoc/docbook file) automatically.
I am also open to changing my toolchain to something that will work.
For example I tried the asciidoc-odt backend and fell foul of https://github.com/dagwieers/asciidoc-odf/issues/47 which does not inspire confidence.
Using asciidoc-odt I avoid the need to create an intermediate docbook file. However, I still can't get the anchor to appear.
I can get a macro to create an anchor but at present I haven't figured out how to run the macro from the command line.
To create an anchor in DocBook, make an inline anchor in the .adoc file. For example, giving this to asciidoctor:
[[X1]]Section1
---------------
produced this:
<title>
<anchor xml:id="X1" xreflabel="[X1]"/>
Section1
</title>
Conversely, putting this on separate lines did not create an anchor tag in my test:
[[X1]]
Section 1
Now for some bad news. From the Pandoc User's Guide:
Internal links are currently supported for HTML formats (including HTML slide shows and EPUB), LaTeX, and ConTeXt.
I interpret this to mean that currently, Pandoc does not create internal links in Writer. When I tried it, the link was ignored.
Note: It looks like I did not answer all of your questions. If you want to ask more about LibreOffice cross references and headings (the big bold paragraph towards the end of the question), maybe you could make a separate question just for that part.

Valid Asciidoc to convert to Manpage (with a2x)

I want to write the manpage for my CLI-script with Asciidoc and convert it with
a2x --doctype manpage --format manpage MYMANPAGE.ASCIIDOC
I could not find any Asciidoc example out there which can successfully be converted to a manpage with this command.
Could you point me to an example or provide one?
Found an example - from the Asciidoc sources itself:
http://code.google.com/p/asciidoc/source/browse/doc/asciidoc.1.txt
(Still, more examples for Ascii-doc-formatted manpages very welcome!)
In addition to the link from #ifischer's answer, which provides a very useful example, I would like to direct readers to the following page from the asciidoc documentation: http://www.methods.co.nz/asciidoc/chunked/ch24.html.
In particular, it mentions that:
the title needs to be properly formatted (e.g: PROGRAM(1))
the doctype needs to be "manpage" (e.g: ":doctype: manpage")
the first section needs to be "Name". The contents of this section must also be properly formatted (e.g: "program - ...")
the second section needs to be "Synopsis". It appears the contents of this section can be anything, although standard manpage practice would be to list all of the program invocation options.
The document must of course be a properly formatted asciidoc document.
There are optional pieces of information which can be set for the manpage via ":directives:" in the document header.
When you run a2x, it will automatically name the outputted manpage based on the contents of the name section and title. I believe it's always named "name.x", where name is from the name section and x is the number from the title.

How do I configure BeyondCompare to ignore SCM replaced text in comments?

I do have some text sequences that are replaced by the SCM (Perforce in my case).
I do want to configure BeyondCompare to consider these sequences as unimportant differences in order to be able to ignore them when I compare files.
In my case it's about Python source files and the sequences are looking like
# $Id: //depot/.../filename#7 $
# $DateTime: 2010/09/01 10:45:29 $
# $Author: username $
# $Change: 1234 $
Sometimes these sequences can be outside comments, but even in this cases I would like to be able ignore these lines because they are not really changed.
You need to define a new grammar element (let's call it "SCM") and mark it as unimportant (see the tutorial here; choose "Basic" and make sure to check "Regular Expression").
The grammar element should be (if I interpret your examples correctly):
^.*\$(Id|DateTime|Author|Change):.*$
This will ignore any line that contains $Id:, $DateTime: etc.
If you only want to ignore lines that start with # $..., use
^\s*#s*\$(Id|DateTime|Author|Change):.*$
And if you only want to ignore stuff between $ (and treat everything else as important), use
\$[^$\r\n]*\$
or
\$(Id|DateTime|Author|Change)[^$\r\n]*\$
depending on whether you care about those keywords or not.
Beyond Compare's parser doesn't currently (v3/v4) support nested elements, so file formats grammars can't be used to mark an SCM sequence as unimportant for a specific file type if the text is already classified as a comment, string, etc.
Beyond Compare 4.0 added support for marking arbitrary text as unimportant across an entire comparison, separate from the grammar.
Load the files you're interested in
Click the Session Settings button (aka Rules w/ umpire icon) or use the Session->Session Settings menu item.
Switch to the Importance tab
Click the + button at the bottom of the Unimportant text list.
Add the plain text or regular expression to Text to find edit and check the Regular Expression checkbox if necessary. In this case the regular expression would be:
\$(Id|DateTime|Author|Change):.*\$
Click Ok.
By default these changes will only affect the current comparison. You can change the combobox at the bottom of the Session Settings dialog from Use for this view only to Also update session defaults to make it affect all future comparisons for all file types.