I have a "project book" which uses LaTeX's \documentclass{report} ("report" is like a more compact version of \documentclass{book}). I would like to include into this book an appendix with the Doxygen-generated API documentation for the software in the project.
I have achieved this by setting Doxygen's config options LATEX_HEADER and LATEX_FOOTER to an empty file. This makes the resulting latex/refman.tex have top level commands like: \section{\-Namespace \-Index}, at which point I can wrap this with a top level document like:
\documentclass{report}
\usepackage{doxygen.sty}
% the "import" package helps to find Doxygen files in the latex/ subdirectory
\usepackage{import}
% [...] title page and the rest of the book
\appendix
\chapter{API reference (generated by Doxygen)
subimport{latex/}{refman.tex}
% [...] final stuff
\end{document}
This works reasonably well and I get doxygen.sty with this special doxygen invocation:
doxygen -w latex /dev/null /dev/null doxygen.sty
One problem is that this puts an "autogenerated" header on the entire document (not just on the doxygen appendix). I can get rid of this by editing doxygen.sty (I also rename it for my inclusion, actually) and commenting out the block that starts with % Setup fancy headings.
At this point I have something I can live with, but I would like to go one step further: the "doxygen" style modifies a lot of other aspects of the LaTeX document style, and I like it less.
So my question is (in two levels of excellence):
What would be a minimal set of LaTeX commands to put in a doxygen.sty file that would nicely render the doxygen appendix but not interfere with the rest of the LaTeX document?
Even better, has someone come up with a way of doing
\usepackage{doxygen_standalone}
% [... until you need doxygen]
\begin{doxygen}
% the stuff you need to insert your auto-generated doxygen API docs,
% for example the \subimport{latex/}{refman.tex} that I showed above
\end{doxygen}
This last approach is one I would consider very clean.
I'm hoping there is a really simple answer, such as "this already exists in doxygen.sty as an option, and you missed it!"
rename doxygen.sty to mydoxygen.sty, then modify it by inserting
\newenvironment{doxygen}{... most of doxygen.sty goes here ...}{}
Related
I am using a single unified LaTeX doc to create problem sets and solutions:
\item What is one plus one?
\begin{soln}
The answer is "two".
\end{soln}
In LaTeX, I define this environment with (simplified):
\NewEnviron{soln}
{
\ifsolutions\expandafter
\BODY
\fi
}
That is, if \solutionsfalse has been defined in LaTeX, it prints:
1. What is one plus one?
and if \solutionstrue has been defined, it prints:
1. What is one plus one?
** The answer is two **
I'm trying to replicate this in pandoc to generate HTML or MD files from the latex input, but I've run against the wall. Pandoc doesn't honor any kind of /if /else /fi statement in LaTeX, I think. Pandoc doesn't honor the comment environment, which would also work with \excludecomment{soln}. So, I can't come up with a shim.tex file that would replicate the 'ignore stuff in the soln environment'.
The next way to go would, I guess, be to do something in luatex that pandoc can talk to, or to define the custom environment to pandoc with a filter? But the documentation for those systems is extremely heavyweight - there's no easy way in.
Can anyone suggest a solution to this?
Ideally, I want to run two different shell commands. Command A should omit all content in the soln environment. Command B, ideally, should turn all regular text blue, and show all content in the soln environment in black color.
(P.S. The xcolor package also seems unsupported in native pandoc, although there is a filter that doesn't work for me.)
Edit
Following comments by #tarleb and #mb21, I guess I have to try to work out how filters work. Again, the documentation here is terrible - it wants you to know everything before you can do anything.
I tried this:
return {
{
RawBlock = function(elem)
print(elem.text)
if starts_with('\\begin{soln}', elem.text) then
return pandoc.RawBlock(elem.format,"SOLN")
else
return elem
end
end,
}
}
and ran it with
pandoc --lua-filter ifdef.lua --mathjax -s hw01.tex -s -o hw01.html
But there is nothing on stdout from the print statement, and my document is unchanged, so the RawBlocks are apparently not processed by the lua filter unless the -f latex+raw_tex flag is passed. But passing those flags means that pandoc doesn't actually process the \include commands in the latex, so my filter wont' see the subdocuments.
Apparently, the answer is "No, pandoc cannot support new latex environment", because it would require modifying the parser. Although the -f latex+raw_tex can disable big parts of the parser, that just means the document is largely unparsed, which isn't what I want.
Please tell me if I'm wrong.
What is the best way to take care of citations in Ipython Notebook? Ideally, I would like to have a bibtex file, and then, as in latex, have a list of shorthands in Ipython markdown cells, with the full references at the end of the notebook.
The relevant material I found is this: http://nbviewer.ipython.org/github/ipython/nbconvert-examples/blob/master/citations/Tutorial.ipynb
But I couldn't follow the documentation very well. Can anyone explain it? Thanks so much!!
Summary
This solution is largely based on Sylvain Deville's excellent blog post. It allows you to simply write [#citation_key] in markdown cells. The references will be formatted after document conversion. The only requirements are LaTeX and pandoc, which are both widely supported. While there is never a guarantee, this approach should therefore still work in many years time.
Step-by-Step Guide
In addition to a working installation of jupyter you need:
LaTeX (installation guide).
Pandoc (installation guide).
A citation style language. Download a citation style, e.g., APA. Save the .csl file (e.g., apa.csl) into the same folder as your jupyter notebook (or specify the path to the .csl file later).
A .bib file with your references. I am using a sample bib file list.bib. Save to the same folder as your jupyter notebook (or specify the path to the .bib file later).
Once you completed these steps, the rest is easy:
Use markdown syntax for references in markdown cells in your jupyter notebook. E.g., [#Sh:1] where the syntax works like this: ([#citationkey_in_bib_file]). I much prefer this syntax over other solutions because it is so fast to type [#something].
At the end of your ipython notebook, create a code cell with the following syntax to automatically convert your document (note that this is R code, use an equivalent command to system() for python):
#automatic document conversion to markdown and then to word
#first convert the ipython notebook paper.ipynb to markdown
system("jupyter nbconvert --to markdown paper.ipynb")
#next convert markdown to ms word
conversion <- paste0("pandoc -s paper.md -t docx -o paper.docx",
" --filter pandoc-citeproc",
" --bibliography="listb.bib",
" --csl="apa.csl")
system(conversion)
Run this cell (or simply run all cells). Note that the 2nd system call is simply pandoc -s paper.md -t docx -o paper.docx --filter pandoc-citeproc --bibliography=listb.bib --csl=apa.csl. I merely used paste0() to be able to spread this over multiple lines and make it nicer to read.
The output is a word document. If you prefer another document, check out this guide for alternative syntax.
#Extras
If you do not like that your converted document includes the syntax for the document conversion, insert a markdown cell above and below the code cell with the syntax for the conversion. In the cell above, enter <!-- and in the cell below enter -->. This is a regular HTML command for a comment, so the syntax will in between these two cells will be evaluated but not printed.
You can also include a yaml header in your first cell. E.g.,
---
title: This is a great title.
author: Author Name
abstract: This is a great abstract
---
You can use the Document Tools of the Calico suite, which can be installed separately with:
sudo ipython install-nbextension https://bitbucket.org/ipre/calico/downloads/calico-document-tools-1.0.zip
Read the tutorial and watch the YouTube video for more details.
Warning: only the cited references are processed. Therefore, if you fail to cite an article, it won't appear in the References section. As a little working example, copy the following in a Markdown cell and press the "book" icon.
<!--bibtex
#Article{PER-GRA:2007,
Author = {P\'erez, Fernando and Granger, Brian E.},
Title = {{IP}ython: a System for Interactive Scientific Computing},
Journal = {Computing in Science and Engineering},
Volume = {9},
Number = {3},
Pages = {21--29},
month = may,
year = 2007,
url = "http://ipython.org",
ISSN = "1521-9615",
doi = {10.1109/MCSE.2007.53},
publisher = {IEEE Computer Society},
}
#article{Papa2007,
author = {Papa, David A. and Markov, Igor L.},
journal = {Approximation algorithms and metaheuristics},
pages = {1--38},
title = {{Hypergraph partitioning and clustering}},
url = {http://www.podload.org/pubs/book/part\_survey.pdf},
year = {2007}
}
-->
Examples of citations: [CITE](#cite-PER-GRA:2007) or [CITE](#cite-Papa2007).
This should result in the following added Markdown cell:
References
^ Pérez, Fernando and Granger, Brian E.. 2007. IPython: a System for Interactive Scientific Computing. URL
^ Papa, David A. and Markov, Igor L.. 2007. Hypergraph partitioning and clustering. URL
I was able to run it with the following approach:
Insert the html citation as in the tutorial you mentioned.
Create ipython.bib in the "standard" bibtex format. It goes into the same file as your *.ipynb notebook file.
Create the template file as in the tutorial, also in the same directory or else in the (distribution dependent) directory with the other templates. On my system, that's /usr/local/lib/python2.7/dist-packages/IPython/nbconvert/templates/latex.
The tutorial has the template extend latex_article.tplx. On my distribution, it's article.tplx (without latex_).
Run nbconvert with --to latex; that generates an .aux file among other things. Latex will complain about missing references.
Run bibtex yournotebook.aux; this generates yournotebook.bbl. You only need to re-run this if you change references.
Re-run nbconvert either with --to latex or with --to pdf. This generates a .tex file, or else runs all the way to a .pdf.
If you want html output, you can use pandoc to assemble the references into a tidy citation page. This may require some hand-editing to make an html page you can reference from your main document.
If you know that you will be converting your notebook to latex anyway, consider simply adding a "Raw" cell (Ctrl+M R) to the end of the document, containing the bibliography just as you would put it in pure LaTeX.
For example, when I need to reference a couple of external links, I would not even care to do a proper BibTeX thing and simply have a "Raw" cell at the end of the notebook like that:
\begin{thebibliography}{1}
\bibitem{post1}
Holography in Simple Terms. K.Tretyakov (blog post), 2015.\\
\url{http://fouryears.eu/2015/07/24/holography-in-simple-terms/}
\bibtem{book1}
The Importance of Citations. J. Smith. 2010.
\end{thebibliography}
The items can be cited in other Markdown cells using the usual <cite data-cite="post1">(KT, 2015)</cite>
Of course, you can also use proper BibTeX as well. Just add the corresponding Raw cell, e.g:
\bibliographystyle{unsrt}
\bibliography{papers}
This way you do not have to bother editing a separate template file (at the price of cluttering the notebook's HTML export with raw Latex, though).
You should have a look at the latex_envs extension in https://github.com/ipython-contrib/IPython-notebook-extensions (install from this repo, it is the most recent version). This extension contains a way to integrate bibliography using bibtex files and standard latex notation, and generates a bibliography section at the end of the notebook. Style of citations can be (to some extent) customized. Some documentation here https://rawgit.com/jfbercher/latex_envs/master/doc/latex_env_doc.html
I'm going to be taking a ton of lecture notes, and then compiling them into LaTeX so that I can have excellent documents for future me to look over. I'm trying to organize things so that I can have a bunch of little documents containing the notes from a lecture, and then compile them at the end of the semester into one large document containing all of them. I have used import/include etc. successfully in the past, but I've had to remove the content at the head and foot of the sub-documents before compiling the main document. For example, I would have to remove:
\begin{document}
and
\end{document}
from every sub-document before compiling the main document. This is fine for a report with 5 or so sections, but a pain in the ass for something with 100+. Any recommendations for ignoring the contents of a LaTeX file programmatically when using the import command?
I see two approaches here. Either carefully structure your documents, or use some hacky TeX magic:
The smart way
Break your smaller documents into a header part, a footer part and a content part.
header.tex:
\documentclass{article}
...
\begin{document}
footer.tex:
\end{document}
foo-content.tex:
In this paper, we discuss an new approach to metasyntactic variables...
foo.tex (the small paper version):
\include{header}
\include{foo-content}
\include{footer}
In your .tex for the collected articles document:
\include{foo-content}
The hacky TeX way
Put this in some common include file, used by your individual files:
\ifx\ismaindoc\undefined
\newcommand{\inbpdocument}{\begin{document}}
\newcommand{\outbpdocument}{\end{document}}
\else
\newcommand{\inbpdocument}{}
\newcommand{\outbpdocument}{}
\fi
Use \inbpdocument and \outbpdocument in your individual files, in place of \begin{document} and \end{document}. In your main file, put in a \def \ismaindoc {} before including or importing anything.
Here's another possible approach: if you put magic strings (i.e., "% % BEGIN LECTURE % %" ... "% % END LECTURE % %") in the individual files, you could awk out the guts of the individual files, assemble them using make/sh, and then \include them.
There's another hack you could use, which wouldn't require modifying the individual files... just temporarily redefine the {document} environment (to something benign, i.e. a no-op), \include the individual files, and then restore the {document} environment definition.
If I recall correctly, the commands to do this are \let and \renewenvironment.
Hm. You might also have to temporarily redefine \documentclass and \usepackage, too. It's a hack, yes, but I think it should work.
I haven't used it, but it looks like the "subfiles" package does exactly what you want:
http://en.wikibooks.org/wiki/LaTeX/Modular_Documents#Subfiles_package
I have fairly large Latex document with a lot of TikZ figures inside. I have a habit of frequent recompilation and it takes forever to compile it using pdflatex. Figures in TikZ take most of the time.
My question is what is the best way to split the document into separate tex files (figures/chapters) to achieve separate compilation of figures and chapters, separate chapter pdfs, and a whole document pdf file ?
Have you tried compiling each picture on its own and then including them in your tex file as pdf rather than the tikz code? You can use the package standalone so that the picture will be the exact size you need. So :
\documentclass{standalone}
\usepackage{tikz,pgf} %and any other packages or tikzlibraries your picture needs
\begin{document}
\begin{tikzpicture}
%your tikz code here
\end{tikzpicture}
\end{document}
The good thing about this is that you can either include the compile this document directly to get a pdf figure to include in your document, or you can use the command \input to include it in your main document as a tikz code by adding
\usepackage{standalone}
in your main document (together with the tikz packages and libraries), and then
\begin{figure}
\input{tikzfile.tex}
\end{figure}
There is a possibly better way (imho) to cache tikz-pictures. Add the following lines in your
preamble:
\usetikzlibrary{external}
\tikzexternalize[prefix=i/]
After a pdflatex-run you'll see all pictures in the subdirectory ./i .
If you update the code of a tikz-picture simply throw away its corresponding pdf-file and it will be regenerated. For more info see the manual of PFG/TikZ section 32.4 Externalizing Graphics
and possibly 32.5 Using External Graphics Without pgf Installed.
How about putting each chapter in a separate file and then using \include to put them into some master file? Then you can use \includeonly to only compile the chapter you're currently working on. That should save some time at least.
I expect some sort of makefile based solution would be even better than this, but I don't know anything about makefiles...
The way I generally do this is to apply Latex to just part of the file: Emacs and several other Latex editors allow you to compiler regions: with Auctex, you can run TeX-pin-region to specify the current chapter, and then TeX-command-region to run Latex on the selected region.
The traditional way to do this is cut parts of the big file into smaller parts that are \included, and then either comment out parts you don't want to work on, or put some macrology at the beginning and end of each file that allows them to be compiled separately.
I'm trying to include a simple glossary to my LaTeX document,
I already searched for something like that on google, but never got it running.
I would like to use glossary or glossaries.
how to write it in the text?
how to print it?
what to execute on which position?
Well, there is a glossaries package on CTAN. Read the pdf documentation.
Check if you already have it in your installation, if not install it, and put \usepackage{glossaries} in the preamble of you document and it will be available to you.
It looks like you need \usepackage{glossaries} and \makeglossaries in the preamble, and some number of \newglossaryentry and \newacronym calls (it is not immediately clear to me if these only go in the premble or can go in the document text). Finally, you will need one or more \printglossary calls in the text. Use \gsl to connect glossary entries on the argument with the pages they occur on.
Processing the file will have to include a call to makeglossaries followed by at least one more invokation of latex.
In addition to the samples mentioned in the documentation there is a Stack Overflow question which includes a minimal file making use of glossaries. You may be particularly interested in the acronym glossary.
There is a nice blog for beginners: LaTeX glossary and list of acronyms
Here is an example:
\documentclass{article}
% Load the package
\usepackage{glossaries}
% Generate the glossary
**\makeglossaries**
\begin{document}
%Term definitions
\newglossaryentry{utc}{name=UTC, description={Coordinated Universal Time}}
\newglossaryentry{adt}{name=ADT, description={Atlantic Daylight Time}}
\newglossaryentry{est}{name=EST, description={Eastern Standard Time}}
% Use the terms
\gls{utc} is 3 hours behind \gls{adt} and 10 hours ahead of \gls{est}.
%Print the glossary
\printglossaries
\end{document}