Problems and solutions
======================

[[Parent]]: user_documentation.txt

This section contains some problems that you might run into when using
Remark, and the solutions of those problems.

SVG-images that do not get loaded
---------------------------------

If an SVG-image does not get loaded when you run a Remark-generated
html-file from a server, but it does get loaded when you run it from
the hard-disk, then the probable cause is that the server does not
have the MIME-type correctly assigned for the .svg files. For example, 
for the `lighttpd` web-server, you should modify the configuration file
`/etc/lighttpd/mime-types.conf` to contain the line

	".svg"          =>      "image/svg+xml"

The former string is the file-extension of the SVG-image file format, 
while the latter is its MIME-type.

Files that are not UTF-8 encoded
--------------------------------

If you pass Remark a file that is not a valid UTF-8 encoding, Remark
replaces each erroneous symbol with the U+FFFD REPLACEMENT CHARACTER.

Mathematical expressions not shown in Internet Explorer
-------------------------------------------------------

Internet Explorer does not directly support MathML which is used to 
present mathematics in Remark (by AsciiMathML). In this case, the 
[[FileLink: ASCIIMathMLwFallback.js]] script contains a fallback to 
image-based rendering. To enable this fallback, replace the line
which reads

[[Code]]:
	var AMTcgiloc = "";

with an url to a cgi-server that can render Latex mathematics strings 
into images, e.g.

[[Code]]:
	var AMTcgiloc = "http://www.somesite.com/cgi-bin/mimetex.cgi";

[Mimetex][Mimetex] is one program which can do this. Unfortunately
there seem to be quite few free Mimetex-servers to use for this task,
and I am unable to provide one either.

[Mimetex]: http://www.forkosh.com/mimetex.html

Mathematical expressions in wrong places
----------------------------------------

The AsciiMathML Javascript library affects the whole generated page and 
can't be scoped. This is problematic in some cases. For example, in Python 
code an empty string is denoted by two subsequent '. This will be erased 
from the output because AsciiMathML interprets it as a start of a 
mathematical expression. Remark solves this problem partially by making 
it configurable per document type whether AsciiMath should be interpreted 
or not: currently only documentation files (.txt) are interpreted. This
way, for example, Python files can be shown correctly in the CodeView
document type.

Indentation macro-invocation after a multi-line parameter
---------------------------------------------------------

Indentation has a double role. It is used both to denote the 
[invocation][MacroInvocation] of the indentation macro, and to denote 
the range of a multi-line parameter for a macro. Therefore, if one wants to 
write an indentation macro-invocation directly after a multi-line parameter, 
there must be some way to tell Remark where the multi-line parameter
ends and the indentation macro-invocation starts. 

The immediate solution
to this problem is to use explicit invocation instead. However, if the
used indentation macro is not known to the writer (e.g. it is generated by 
some automated process), this solution is not applicable. A general solution 
is to use the [Comment][CommentMacro] macro without a multi-line parameter 
to divide the parameters. For example:

	[[CppCode]]:
		int square(int x)
		{
			return x * x;
		}
		
		int cube(int x)
		{
			return x * x * x;
		}
	
	[[Comment]]

		Parameters for indentation macro-invocation here.

[CommentMacro]: [[Ref]]: Comment_Macro.txt
[MacroInvocation]: [[Ref]]: macro_invocation.txt

Injecting html to the head section
----------------------------------

Html-code can be injected into the head-section of a html-file
by storing text in the `html_head` tag.


