It seems that Github does not support the sphinx.ext.doctest syntax in their reStructuredText renderer, which is causing some problems when trying to include a doctest-style code block (.. doctest) in a README.rst which is transcluded into the documentation index (which is rendered by sphinx). If I replace the .. doctest directive with something else, it doesn't render properly as a doctest on Sphinx, but if I don't remove the directive, the code block doesn't render at all (see this gist).
Ideally I'd like to find a solution which just does the right thing in both environments, but failing that, is there a way to fall back to a .. code block or some other supported format (e.g. the rST equivalent of a <NoScript> tag)?
Related
I am using Scribble to write assignments and would like to have the ability to include common text snippets somewhere in the document. For example:
#lang scribble/manual
#section{Some section}
#include-file["common-pretext.scrbl"] #; my imaginary command
Some additional text after the pretext
#section{Next section}
More text...
I would like #include-file to include the contents of common-pretext.scrbl just as if I had copy/pasted its contents at the specified position. That is, I would like its contents to be part of Some section and also properly handle Scribble commands occurring in common-pretext.scrbl.
I know that Scribble has #include-section, which is similar to what I want. However, #include-section always starts a new section and text following it until the next section is silently dropped (I am not sure why this happens, but presumably because of how the document is constructed). I also tried Racket's #include, but then the contents are not shown at all. Lastly, I tried building a macro that does what I want, but failed to make it work (if a macro is the way to go, then I am happy to share my attempts so far).
Is there such a command already and if not how can I build one?
This question is pretty old, but if you are still looking, this package does what you want:
https://docs.racket-lang.org/scribble-include-text/index.html
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)
I'm trying to figure out how to modify an XML file with NSIS. So I'm trying to learn how to use the XML plugin. The examples on the forum page often use the format ${plugin::command} like:
${xml::LoadFile}
The documentation gives no indication that you need the dollar sign and curly braces. As I understand it, just plugin::command will do. So I've been trying to figure out what that syntax means.
The documentation says a $ is for variables and the {} are for code blocks, but I can't find anything about what it means when they're used together. My Internet searches have revealed that it's used for something called template literals in JavaScript. But what does it mean in NSIS?
EDIT: I should mention that the NSIS documentation does show examples of this syntax, especially in the Predefines section, but it still doesn't explain what the syntax means in general.
EDIT: Okay, now I see that the syntax is for the compiler to replace things using !define and !macro. But... what about this specific case? Is it valid to use colons in such a symbol? Why are some people writing ${xml::LoadFile}and some people just writing xml::LoadFile?
It's a !define. There is a header file for this plugin that defines it. The plugin probably needs to do more than one thing, so they wrapped a few lines together with a define that inserts a macro. Either that or it has some default parameters for the plugin call. Either way, it's trying to save you some typing with this syntax.
We are trying to implement an automatic markdown generator for an easily maintainable documentation.
When mentioning a variable's type, we would like to prefix it with ? when it is nullable, use backticks around it and add a link to its description. For example: `?[Article](#article)`.
However, the backticks break the link syntax because of the overlap. We use `?`[`Article`](#article) instead to make the link works but it creates a space between ? and Article as follow: ?Article.
Is it possible to make it look like ?Article with a link on Article only?
I just tested this out and discovered that there is no space between ? and Article. What appears to be a space is simply GitHub's styling of two <code> blocks up against each other.
Wrapping the whole thing in backticks won't work because backticks indicate code, and Markdown treats the contents as if they are a code sample where you want to show the source.
The best workaround I can find is to use <code> tags directly:
<code>?[Article](https://stackoverflow.com/)</code>
On both GitHub and Stack Overflow this renders like so:
?Article
(I have used a link to Stack Overflow as the link target here simply so we get a rendered link as an example. I expect that #article will work equally well in your environment.)
In my opinion this is even a reasonable way of doing what you want. Markdown's backticks compile to <code> tags, and inline HTML code is expressly permitted by Markdown:
For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.
I have a mainpage.dox file which is invoked in the configuration file as:
USE_MDFILE_AS_MAINPAGE = ../mainpage.dox
Inside the document I provide instructions on compiling. I would like to list the compiler option as -L/$(MKLROOT)/lib/intel64 -lmkl_rt, however the $(MKLROOT) part is expanded. Is there a way to prevent this from happening?
When I put the following in mainpage.md
1 Test with backticks `-L$(MKLROOT)/lib/intel64 -lmkl_rt`
2 Test without backticks -L\$(MKLROOT)/lib/intel64 -lmkl_rt
3 Test with code <code>-L\$(MKLROOT)/lib/intel64 -lmkl_rt</code>
#verbatim
4 Test with verbatim -L$(MKLROOT)/lib/intel64 -lmkl_rt
#endverbatim
The $(MKLROOT) in the first example gets (incorrectly) expanded.
The other three examples work as expected (using doxygen 1.8.5)
Note that USE_MDFILE_AS_MAINPAGE expects a pure markdown file, not something with a /*! .. */ comment block.
FWIW the latest version of Doxygen as of this writing (1.8.15) still behave in the same way and escaping the backslash still doesn't work. I'm using the following workaround for now:
`-L$``$(MKLROOT)`
which, while ugly, works and doesn't require adding the <code> tags everywhere.
I've also created an issue in Doxygen asking for this to be changed.