When a .Rmd file is being knit into html, latex commands are completely ignored. Itemize, quotes, even text formatting disappers, along with the text. When knitting to .pdf \chapter is declared to be undefined control sequence and the execution is halted.
---
output:
html_document:
fig_caption: yes
keep_md: yes
theme: cerulean
toc: yes
pdf_document:
fig_caption: yes
keep_tex: yes
toc: yes
---
\chapter{{Efficient R Coding}}
\section{Benchmarking}
Donald Knuth\sidenote{See \url{http://en.wikipedia.org/wiki/Donald_Knuth}} made the following statement on optimization:
\begin{quote}
\textit{"We should forget about small efficiencies, say about 97\% of the time: premature optimization is the root of all evil."}
\end{quote}
\noindent So before we rush headlong into optimising our R code, we will spend some time determining when it is worthwhile optimising. In this chapter, we will look at benchmarking. In computing, a benchmark is obtained by running a set of programs in order to assess their relative performance.
\section{Simple benchmarks}
To construct a benchmark we typically use the following steps
\begin{enumerate}
\item Construct a function (or set of functions) around the feature we want to
benchmark. This function usually has an argument that allows us to vary the
complexity of the object. For example, a parameter \texttt{n} that alters the data
This is renders as...
Enumerate environment is ignored. Section and chapter titles are also ignored. How to make pandoc render the content enclosed in the curly brackets?
Related
I have already seen some other links related to this question, which are mentioned as below:
How to write LaTeX in IPython Notebook?
https://towardsdatascience.com/write-markdown-latex-in-the-jupyter-notebook-10985edb91fd
https://colab.research.google.com/drive/18_2yFdH8G-6NXY_7fTcshMoScgJ-SYac#scrollTo=go3imAWqE9au
However, I am still facing some problems while using the Latex code inside Jupyter notebook.
For example,
\begin{align*}
f(x) &= x^2\\
g(x) &= \frac{1}{x}\\
F(x) &= \int^a_b \frac{1}{3}x^3
\end{align*}
This works fine as Markdown but
\begin{equation*}
f(x) &= x^2\\
g(x) &= \frac{1}{x}\\
F(x) &= \int^a_b \frac{1}{3}x^3
\end{equation*}
does not.
While trying to create an ordered list using the following
\begin{enumerate}
\item The labels consists of sequential numbers.
\item The numbers starts at 1 with every call to the enumerate environment.
\end{enumerate}
However, $\textbf{This is a bold text.}$ works.
It's really confusing what I can use and whatnot. Is there any way so that I can use only Latex code (and no HTML or other code) inside Visual Studio code to format my texts and equations without worrying about which will work and which not?
The short and very pragmatic answer is: you can't.
When you type something like $ a^2 $ in a markdown cell, what Jupyter Notebook actually does is send it to a library called MathJax. Mathjax, in its turn, does not compile the TeX code you typed using a standard LaTeX compiler. It, instead, just looks for mathematics environments and try to process the TeX-like syntax into something MathJax can understand.
Diving in LaTeX-stuff
There are two modes in (La)TeX: the text mode and the math mode, which are treated separately by the TeX compiler. For example, open your TeX editor and try to compile the following code.
\documentclass{article}
\begin{document}
a^2
$ ação $
\end{document}
You'll receive that error:
! Missing $ inserted.
<inserted text>
$
l.4
I've inserted a begin-math/end-math symbol since I think
you left one out. Proceed, with fingers crossed.
Missing character: There is no ç (U+00E7) in font cmmi10!
Missing character: There is no ç (U+00E7) in font cmmi10!
Missing character: There is no ã (U+00E3) in font cmmi10!
Missing character: There is no ã (U+00E3) in font cmmi10!
It's telling you that (1) you can't use ^ in text mode; (2) you can't use unicode characters such as ç and ã in math mode.
At this point, it's important to remember that align environments are courtesy of amsmath or mathtools packages, and doesn't exists in "plain" LaTeX
Back to MathJax
Unlike a real LaTeX compiler, MathJax does not implement the entire TeX macros universe, but only those related to the math mode (as the name suggests). From documentation:
Note that the TeX input processor implements only the math-mode macros of TeX and LaTeX, not the text-mode macros. MathJax expects that you will use standard HTML tags to handle formatting the text of your page; it only handles the mathematics. So, for example, MathJax does not implement \emph or \begin{enumerate}...\end{enumerate} or other text-mode macros or environments. You must use HTML to handle such formatting tasks. If you need a LaTeX-to-HTML converter, you should consider other options.
However, there are some exceptions. The default configuration of TeX input processor allow detecting environments outside math mode, so those environment related to math (equation, align, matrix, etc) can be correctly typeset. Recall that LaTeX does not implements align out-of-the-box, while MathJax does.
And what about the buggy equation environment?
Regarding your buggy equation environment, it's more a LaTeX stuff. equation environments does not support line breaks (\\) neither & (the first one I can't explain exactly why, but certainly someone in TeX SE can), so your input is invalid.
You can now with the latest version of VS Code. The feature is still in preview (as of writing) so you have to enable it in settings.json by adding "notebook.experimental.useMarkdownRenderer": true
Restart VS Code and try $$y=x^2$$ and press ctrl+enter to see it rendered. I think for now the equation needs to be on a separate line by itself.
Here's the announcement: https://code.visualstudio.com/updates/v1_55#_preview-features
I am looking for a term that I heard recently but can't think of at the moment. It's on the tip of my tongue.
What is it called when you are able to execute individual cells / blocks of code, see the output, and the system maintains state between execution of the cells?
For example, this is a feature of Mathematica notebooks, Jupyter notebooks, etc. But the term I'm looking for is more narrow than "notebook interface" or "literate programming", as it doesn't require pretty printing, text cells, etc. The purpose is more for testing syntax or seeing output dynamically than it is for creating a readable document.
I think it was an acronym, possibly four letters...
Read–eval–print loop (REPL) enables interactive mode of development where expressions are evaluated on the fly as opposed to the traditional edit-compile-run-debug cycle. For example, Scala's REPL, or OCaml's REPL:
...permits interactive use of the
OCaml system through a read-eval-print loop (REPL). In this mode, the
system repeatedly reads OCaml phrases from the input, then typechecks,
compile and evaluate them, then prints the inferred type and result
value...
Informally, I have often heard the distinction being referred to as simply interpreter vs. compiler, for example, "Let's quickly try it out in the interpreter".
Github supports syntax highlight as follows:
```javascript
let message = 'hello world!'
```
And it supports diff as follows: (but WITHOUT syntax highlight)
```diff
-let message = 'hello world!'
+let message = 'hello stackoverflow!'
```
How can I get both 'syntax hightlight' AND 'diff' ?
No, this is not a supported feature at this time.
GitHub documents their processing of lightweight markup languages (including Markdown, among others) in github/markup. Note step 3:
Syntax highlighting is performed on code blocks. See github/linguist for more information about syntax highlighting.
If we follow that link, we find a list of grammars that Linguist uses to provide syntax highlighting on GitHub. Linguist can only apply one of the grammars in that list to a block of code at a time. Of course, one of the grammars is Diff. However, that grammar knows nothing about the language of code being diffed, so you don't get syntax highlighting of that.
Of course, there are other languages which are often combined. For example, HTML is often included in a templating language. Therefore, in addition to the HTML grammar, we also find grammars for HTML+Django, HTML+ECR HTML+EEX, HTML+ERB, and HTML+PHP. In each case, the single grammar is aware of two languages. Both the specific templating language and the HTML which is interspersed within the template.
To accomplish the same thing with a diff, you would need a separate "diff" grammar for every single language listed. In other words, the number of grammars would double. Of course, a way to avoid this might be to treat diff differently. When diff is specified, they could run the block through the syntax highlighter twice, once for diff and once for the source language. However, at least when processing code blocks in lightweight markup languages, they have not implemented such a feature.
And if they ever were to implement such a feature in the future, it would likely be more complicated that simply running the code block through twice. After all, every line of the diff has diff specific content which would confuse the other language grammar. Therefore, every grammar would need to be diff aware, or each line would need to be fed to the grammar separately with the diff parts removed. The problem with the later is that the grammar would not have the context of each line and is more likely to get things wrong. Whether such a solution is possible is outside this cope of this answer, but the point is that it is reasonable to expect that such a feature would be much lower priority to support due to the complexity involved.
So why does GitHub do syntax highlighting in other places on its website? Because, in those cases, it has access to the two source files being diffed and it generates the diff itself. Each source is first highlighted (avoiding the complexity mentioned above), then the diff is created from the two highlighted source files. However, a diff included in a Markdown code block is already a diff when GitHub first sees it. There is no way for them to highlight the pre-diff code first. In other words, the process they currently use would not be transferable to supporting the requested feature.
You would need to post-process the output of the git diff in order to add syntax highlighting for the right language of the file being diff'ed.
But since you are asking for GitHub, that post-processing is not in your control, and is not provided by GitHub at the moment in its GFM (GitHub Flavored Markdown Spec).
It is supported for source files, in a regular diff like this one or in a PR: GitHub does the syntax highlighting of the two versions of the file, and then computes the diff.
It is not supported in a regular markdown fenced code block, where the +/- of a diff would throw off the syntax highlighting engine, considering there is no "diff" operation done here (just the writer trying to add diff +/- symbols)
The publish function in MATLAB works for both scripts and functions,
while the one for Octave works only for scripts: if I enter
publish myFunc.m
Octave gave
error: publish: Only Octave script files can be published.
Am I able to publish a function in Octave? If yes, how?
You can use Octave Forge generate_html package which is meant to generate html of individual functions. It is mostly used to generate the documentation of Octave Forge packages, and its defaults reflect that, but you could add any style you want.
This package will use the same help text that the help function in Octave sees which is the first block of comments in the file that does not start by Copyright or Author. You can have it in plain text but for nicer formatting, you can use Texinfo. In that case, the first line of the help text should be -*- texinfo -*-. There is a page on the Octave wiki with tips on how to write nice help text including a short section on Texinfo syntax (the actual Texinfo manual can be a bit overwhelming).
In addition to the help text, the generate_html package also identifies %!demo blocks and generates a section with the demo code and output it generates, including figures.
The best way to see how help text and demo blocks work in Octave is to check the source (as #Andy pointed out in the comments). For example, see the source for inpolygon (scroll to the bottom to find the %!demo blocks, right before %!test and %!error). The generate_html package generates this page (note the Demonstration blocks).
This is a "multiple questions in one" question, making lots of assumptions in between, so let's address those first:
1. I'll start by the question in the comment, since that's the easiest: Matlab's publisher is not a code documentation tool. It's a "make a quick report that includes both text and code to show at your supervisor meeting or write a quick point in a blog" tool. So the link you point to is simply irrelevant in this case, since that talks about documentation for matlab code.
2. The fact that matlab's publisher also "works for functions", particularly given the first point here, should be considered to be more of a bug than a feature, or at most as a trivial undocumented extension. If you look at the matlab documentation for the publish command, you'll see it expects a filename, not a function with arguments, and the documentation only talks about scripts and makes no mention of 'function' compatibility.
3. Furthermore, even if you did want to use publisher as a "documentation tool", this is counterintuitive for functions in this format, since you need to provide arguments in order for publisher to work (which will not be shown in the actual report), you'll need a modified version that displays intermediate calculations (as opposed to your normal version which presumably does not), and the function just spews an ugly ans= blabla at the end of the report. If your end goal is documentation, it might be best to write a bespoke script for this anyway, showing proper usage and examples, like matlab does in its actual documentation.
Having said all that, yes, there is a 'cheat' you can do to include a function's code in your published report, which is that, in octave (also matlab since R2016b), functions can be defined locally. A .m file that only contains function definitions is interpreted as a function file, but if there are other non-function-declaration instructions preceding the function definitions (other than comments), then it is seen as a script. So if you publish this script, you effectively get a published report with function code in it:
%% Adding function
% This function takes an input and adds 5 to it.
%% Example inputs
In = 10;
%% The function itself
% Marvel at its beauty!
function Out = myfun(In)
%% Here is where the addition takes place.
% It is a beautiful addition
Out = In + 5;
end
%% Example use
Out = myfun(In)
(If you're not happy about having to create a 'wrapper script' manually, you can always create your own wrapper function that does this automatically).
However, both the matlab and octave publishers are limited tools by design. Like I said earlier, it's more of a "quick report to show numbers and plots to your supervisor" tool, rather than a "make nice documentation or professional reports" tool. Instead, I would invest in a nice automated latex workflow, and have a look at code formatting tools for displaying code, and simply wrap that code in a script that produces output to a file that you can then import into latex. It may sound like more work, but it's a lot more flexible and robust in the long term, particularly since the formatting commands can be very quirky as well as limited.
Many man pages and --help option use a format for describing the command line options of the documented utilities. For instance, for the cd shell command:
cd [-L | -P] [directory]
cd -
I'd like to parse these descriptions. Is there a model or formal format (even if it is not widely accepted)?
I've seen that at least python's argparse (http://pymotw.com/2/argparse/) can generate something like that.
Some details about the notation used for the SYNOPSIS section can be found in the man manual:
The following conventions apply to the SYNOPSIS section and can be used as a guide in
other sections.
bold text type exactly as shown.
italic text replace with appropriate argument.
[-abc] any or all arguments within [ ] are optional.
-a|-b options delimited by | cannot be used together.
argument ... argument is repeatable.
[expression] ... entire expression within [ ] is repeatable.
Exact rendering may vary depending on the output device. For instance, man will
usually not be able to render italics when running in a terminal, and will typically
use underlined or coloured text instead.
The command or function illustration is a pattern that should match all possible
invocations. In some cases it is advisable to illustrate several exclusive
invocations as is shown in the SYNOPSIS section of this manual page.
There are further details in the the POSIX Utility Syntax Guidelines.
Many libraries to parse the command line options can generate the synopsis section (e.g. take a look at boost::program_options).