[doconce] push by h...@simula.no - Better link colors for latex - works better in BW. Changed to lighter ... on 2013-06-24 18:00 GMT
5 views
Skip to first unread message
doc...@googlecode.com
Jun 24, 2013, 2:01:09 PM6/24/13
to docon...@googlegroups.com
Revision: 3e5e789d7a90
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Mon Jun 24 11:00:38 2013
Log: Better link colors for latex - works better in BW. Changed to
lighter gray in gray latex admons. Changed HTML gray admons to match the
gray background in pygments code.
http://code.google.com/p/doconce/source/detail?r=3e5e789d7a90
Modified:
/doc/manual/manual.do.txt
/lib/doconce/common.py
/lib/doconce/doconce.py
/lib/doconce/html.py
/lib/doconce/latex.py
/lib/doconce/misc.py
/test/admon.do.txt
=======================================
--- /doc/manual/manual.do.txt Sun Jun 9 04:52:30 2013
+++ /doc/manual/manual.do.txt Mon Jun 24 11:00:38 2013
@@ -1937,6 +1937,15 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+!bwarning
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like `${var}` to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., `${\cal O}(\Delta x^2)$` which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+!ewarning
+
===== The Basics of Mako =====
Just a preliminary sketch of some Mako code (next example is better!):
@@ -2145,6 +2154,26 @@
* Strings with `'T<%.1f'` look as openings of Mako blocks (`<%`); change
to `'T < %.1f'` to avoid this confusion.
+=== The Mako preprocessor claims a variable is undefined ===
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use `${` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is `${}^+$` type of indication of superscripts.
+A suggested rewrite is `$\,{}^+$`.
+
+The error message will ask you to rerun `doconce` with
+`--mako_strict_undefined`, which will display the variable that
+is confusing Mako. However, do not continue to use
+`--mako_strict_undefined` while you are debugging because this
+variable will then always be undefined in that mode.
+Use `# #ifdef` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without `--mako_strict_undefined`).
+
=== Something goes wrong in the preprocessing step ===
You can examine `tmp_preprocess__filename` and `tmp_mako__filename`,
@@ -2530,6 +2559,14 @@
===== Problems with HTML Output =====
+=== MathJax formulas are not properly rendered ===
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+ * `[` and `]` brackets must sometimes be replaced by `\lbrack` and
`\rbrack`
+
=== How can I change the layout of the HTML page? ===
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /lib/doconce/common.py Sun Jun 16 22:16:28 2013
+++ /lib/doconce/common.py Mon Jun 24 11:00:38 2013
@@ -43,6 +43,31 @@
print e
sys.exit(1)
+def fix_backslashes(text):
+ """
+ If some Doconce text is read from a doc string
+ or from a GUI, backslashes are normally interpreted,
+ and the Doconce text is then malformed. This function
+ restores backslashes. For double backslash in LaTeX
+ one needs to have the double backslash at the end of
+ the line, otherwise they are not preserved.
+ """
+ # Preserve backslashes as in a raw string
+ escape = {
+ '\\'+ '\n':'\\\\' + '\n',
+ '\a':r'\a',
+ '\b':r'\b',
+ '\c':r'\c',
+ '\f':r'\f',
+ '\r':r'\r',
+ '\t':r'\t',
+ '\v':r'\v',
+ }
+ for char in escape:
+ text = text.replace(char, escape[char])
+ return text
+
+
def where():
"""
Return the location where the doconce package is installed.
=======================================
--- /lib/doconce/doconce.py Fri Jun 14 04:02:09 2013
+++ /lib/doconce/doconce.py Mon Jun 24 11:00:38 2013
@@ -1698,7 +1698,7 @@
# version < 2.7 warning
print '*** warning: citations may appear in random order unless
you upgrade to Python version 2.7 or 3.1'
if len(citations) > 0 and 'BIBFILE:' not in filestr:
- print '*** error: you have citations but no biblioraphy
(BIBFILE: ...)'
+ print '*** error: you have citations but no bibliography
(BIBFILE: ...)'
_abort()
if 'BIBFILE:' in filestr and len(citations) > 0 and \
which('publish') is None:
@@ -2437,6 +2437,18 @@
_abort()
return filename if preprocessor is None else resultfile
+ # Check if LaTeX math has ${...} problems
+ inline_math = re.findall(INLINE_TAGS['math'], filestr_without_code)
+ for groups in inline_math:
+ formula = groups[2]
+ suggestion = ''
+ if formula[0] == '{':
+ if formula[1] == '}':
+ suggestion = 'as $\,{}...$'
+ print '*** error: potential problem with formula $%s$' %
formula
+ print ' since ${ can confuse Mako - rewrite', suggestion
+ _abort()
+
if preprocessor is not None: # already found preprocess commands?
# The output is in resultfile, mako is run on that
filename = resultfile
=======================================
--- /lib/doconce/html.py Sat Jun 8 16:09:14 2013
+++ /lib/doconce/html.py Mon Jun 24 11:00:38 2013
@@ -1267,10 +1267,14 @@
if body_font_family is not None:
if body_font_family in google_fonts:
import_body_font = link % body_font_family
+ else:
+ print '*** warning: --html_body_font=%s is not valid' %
body_font_family
import_heading_font = ''
if heading_font_family is not None:
if heading_font_family in google_fonts:
import_heading_font = link % heading_font_family
+ else:
+ print '*** warning: --html_heading_font=%s is not valid' %
heading_font_family
if import_body_font or import_heading_font:
css = ' ' + '\n '.join([import_body_font,
import_heading_font]) \
+ '\n' + css
@@ -1286,7 +1290,8 @@
admon_css_vars = {style: {} for style in admon_styles}
admon_css_vars['yellow'] = dict(boundary='#fbeed5',
background='#fcf8e3')
admon_css_vars['apricot'] = dict(boundary='#FFBF00',
background='#fbeed5')
- admon_css_vars['gray'] = dict(boundary='#bababa',
background='whiteSmoke')
+ #admon_css_vars['gray'] = dict(boundary='#bababa',
background='whiteSmoke')
+ admon_css_vars['gray'] = dict(boundary='#bababa',
background='#f8f8f8') # same color as in pygments light gray background
for a in admons:
if a != 'block':
admon_css_vars['yellow']['icon_' + a]
= 'small_yellow_%s.png' % a
=======================================
--- /lib/doconce/latex.py Sat Jun 8 16:09:14 2013
+++ /lib/doconce/latex.py Mon Jun 24 11:00:38 2013
@@ -875,6 +875,7 @@
\begin{graybox2admon}[%%s]
%%s
\end{graybox2admon}
+
''' %% (title_graybox1, block_graybox2)
if latex_admon in ('colors1', 'colors2', 'graybox3', 'yellowbox'):
@@ -882,22 +883,28 @@
\begin{%(_admon)s_%%(latex_admon)sadmon}[%%(title)s]
%%(block)s
\end{%(_admon)s_%%(latex_admon)sadmon}
+
''' %% vars()
+
elif latex_admon == 'paragraph':
text = r'''
\begin{paragraphadmon}[%%(title_para)s]
%%(block)s
\end{paragraphadmon}
+
''' %% vars()
+
elif latex_admon == 'graybox2':
text = r'''
%%(envir_graybox2)s
''' %% vars()
+
else:
text = r'''
\begin{graybox1admon}[%%(title_graybox1)s]
%%(block)s
\end{graybox1admon}
+
''' %% vars()
return text
""" % vars()
@@ -1280,10 +1287,11 @@
% #endif
% Hyperlinks in PDF:
+\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage[%
colorlinks=true,
- linkcolor=blue,
- urlcolor=blue,
+ linkcolor=linkcolor,
+ urlcolor=linkcolor,
citecolor=black,
filecolor=black,
%filecolor=blue,
@@ -1418,7 +1426,7 @@
INTRO['latex'] += r"""
% Admonition is an oval gray box
\newmdenv[
- backgroundcolor=gray!10, %% white with 10%% gray
+ backgroundcolor=gray!5, %% white with 5%% gray
skipabove=\topsep,
skipbelow=\topsep,
outerlinewidth=0.5,
=======================================
--- /lib/doconce/misc.py Sun Jun 9 05:29:27 2013
+++ /lib/doconce/misc.py Mon Jun 24 11:00:38 2013
@@ -4058,6 +4058,7 @@
(r'^\s*file=[A-Za-z_0-9.]+\s*$', '', re.MULTILINE),
(r"^@@@CODE.*$", "", re.MULTILINE),
(r"^\s*(FIGURE|MOVIE):\s*\[.+?\]", "", re.MULTILINE),
+ (r"^\s*BIBFILE:.+$", "", re.MULTILINE),
(r"^\s*TOC:\s+(on|off)", "", re.MULTILINE),
(r"\$.+?\$", ""), # inline math (before mako variables)
(r"\$\{.*?\}", ""), # mako variables (clashes with math: ${\cal
O}(dx)$)
=======================================
--- /test/admon.do.txt Tue Jun 11 01:50:39 2013
+++ /test/admon.do.txt Mon Jun 24 11:00:38 2013
@@ -84,9 +84,13 @@
!bnotice (illegal-size) Note, eventually!
Ah, we are soon close to the end (with illegal font size specification!).
-But first a bit of math:
+But first a bit of math where we define $\theta$ and $\bm{r}$:
+
!bt
-\[ p=q\]
+\begin{align*}
+\theta &= q^2,\\
+\bm{r} &= \varrho\bm{i}
+\end{align*}
!et
!enotice
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Mon Jun 24 11:00:38 2013
Log: Better link colors for latex - works better in BW. Changed to
lighter gray in gray latex admons. Changed HTML gray admons to match the
gray background in pygments code.
http://code.google.com/p/doconce/source/detail?r=3e5e789d7a90
Modified:
/doc/manual/manual.do.txt
/lib/doconce/common.py
/lib/doconce/doconce.py
/lib/doconce/html.py
/lib/doconce/latex.py
/lib/doconce/misc.py
/test/admon.do.txt
=======================================
--- /doc/manual/manual.do.txt Sun Jun 9 04:52:30 2013
+++ /doc/manual/manual.do.txt Mon Jun 24 11:00:38 2013
@@ -1937,6 +1937,15 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+!bwarning
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like `${var}` to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., `${\cal O}(\Delta x^2)$` which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+!ewarning
+
===== The Basics of Mako =====
Just a preliminary sketch of some Mako code (next example is better!):
@@ -2145,6 +2154,26 @@
* Strings with `'T<%.1f'` look as openings of Mako blocks (`<%`); change
to `'T < %.1f'` to avoid this confusion.
+=== The Mako preprocessor claims a variable is undefined ===
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use `${` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is `${}^+$` type of indication of superscripts.
+A suggested rewrite is `$\,{}^+$`.
+
+The error message will ask you to rerun `doconce` with
+`--mako_strict_undefined`, which will display the variable that
+is confusing Mako. However, do not continue to use
+`--mako_strict_undefined` while you are debugging because this
+variable will then always be undefined in that mode.
+Use `# #ifdef` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without `--mako_strict_undefined`).
+
=== Something goes wrong in the preprocessing step ===
You can examine `tmp_preprocess__filename` and `tmp_mako__filename`,
@@ -2530,6 +2559,14 @@
===== Problems with HTML Output =====
+=== MathJax formulas are not properly rendered ===
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+ * `[` and `]` brackets must sometimes be replaced by `\lbrack` and
`\rbrack`
+
=== How can I change the layout of the HTML page? ===
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /lib/doconce/common.py Sun Jun 16 22:16:28 2013
+++ /lib/doconce/common.py Mon Jun 24 11:00:38 2013
@@ -43,6 +43,31 @@
print e
sys.exit(1)
+def fix_backslashes(text):
+ """
+ If some Doconce text is read from a doc string
+ or from a GUI, backslashes are normally interpreted,
+ and the Doconce text is then malformed. This function
+ restores backslashes. For double backslash in LaTeX
+ one needs to have the double backslash at the end of
+ the line, otherwise they are not preserved.
+ """
+ # Preserve backslashes as in a raw string
+ escape = {
+ '\\'+ '\n':'\\\\' + '\n',
+ '\a':r'\a',
+ '\b':r'\b',
+ '\c':r'\c',
+ '\f':r'\f',
+ '\r':r'\r',
+ '\t':r'\t',
+ '\v':r'\v',
+ }
+ for char in escape:
+ text = text.replace(char, escape[char])
+ return text
+
+
def where():
"""
Return the location where the doconce package is installed.
=======================================
--- /lib/doconce/doconce.py Fri Jun 14 04:02:09 2013
+++ /lib/doconce/doconce.py Mon Jun 24 11:00:38 2013
@@ -1698,7 +1698,7 @@
# version < 2.7 warning
print '*** warning: citations may appear in random order unless
you upgrade to Python version 2.7 or 3.1'
if len(citations) > 0 and 'BIBFILE:' not in filestr:
- print '*** error: you have citations but no biblioraphy
(BIBFILE: ...)'
+ print '*** error: you have citations but no bibliography
(BIBFILE: ...)'
_abort()
if 'BIBFILE:' in filestr and len(citations) > 0 and \
which('publish') is None:
@@ -2437,6 +2437,18 @@
_abort()
return filename if preprocessor is None else resultfile
+ # Check if LaTeX math has ${...} problems
+ inline_math = re.findall(INLINE_TAGS['math'], filestr_without_code)
+ for groups in inline_math:
+ formula = groups[2]
+ suggestion = ''
+ if formula[0] == '{':
+ if formula[1] == '}':
+ suggestion = 'as $\,{}...$'
+ print '*** error: potential problem with formula $%s$' %
formula
+ print ' since ${ can confuse Mako - rewrite', suggestion
+ _abort()
+
if preprocessor is not None: # already found preprocess commands?
# The output is in resultfile, mako is run on that
filename = resultfile
=======================================
--- /lib/doconce/html.py Sat Jun 8 16:09:14 2013
+++ /lib/doconce/html.py Mon Jun 24 11:00:38 2013
@@ -1267,10 +1267,14 @@
if body_font_family is not None:
if body_font_family in google_fonts:
import_body_font = link % body_font_family
+ else:
+ print '*** warning: --html_body_font=%s is not valid' %
body_font_family
import_heading_font = ''
if heading_font_family is not None:
if heading_font_family in google_fonts:
import_heading_font = link % heading_font_family
+ else:
+ print '*** warning: --html_heading_font=%s is not valid' %
heading_font_family
if import_body_font or import_heading_font:
css = ' ' + '\n '.join([import_body_font,
import_heading_font]) \
+ '\n' + css
@@ -1286,7 +1290,8 @@
admon_css_vars = {style: {} for style in admon_styles}
admon_css_vars['yellow'] = dict(boundary='#fbeed5',
background='#fcf8e3')
admon_css_vars['apricot'] = dict(boundary='#FFBF00',
background='#fbeed5')
- admon_css_vars['gray'] = dict(boundary='#bababa',
background='whiteSmoke')
+ #admon_css_vars['gray'] = dict(boundary='#bababa',
background='whiteSmoke')
+ admon_css_vars['gray'] = dict(boundary='#bababa',
background='#f8f8f8') # same color as in pygments light gray background
for a in admons:
if a != 'block':
admon_css_vars['yellow']['icon_' + a]
= 'small_yellow_%s.png' % a
=======================================
--- /lib/doconce/latex.py Sat Jun 8 16:09:14 2013
+++ /lib/doconce/latex.py Mon Jun 24 11:00:38 2013
@@ -875,6 +875,7 @@
\begin{graybox2admon}[%%s]
%%s
\end{graybox2admon}
+
''' %% (title_graybox1, block_graybox2)
if latex_admon in ('colors1', 'colors2', 'graybox3', 'yellowbox'):
@@ -882,22 +883,28 @@
\begin{%(_admon)s_%%(latex_admon)sadmon}[%%(title)s]
%%(block)s
\end{%(_admon)s_%%(latex_admon)sadmon}
+
''' %% vars()
+
elif latex_admon == 'paragraph':
text = r'''
\begin{paragraphadmon}[%%(title_para)s]
%%(block)s
\end{paragraphadmon}
+
''' %% vars()
+
elif latex_admon == 'graybox2':
text = r'''
%%(envir_graybox2)s
''' %% vars()
+
else:
text = r'''
\begin{graybox1admon}[%%(title_graybox1)s]
%%(block)s
\end{graybox1admon}
+
''' %% vars()
return text
""" % vars()
@@ -1280,10 +1287,11 @@
% #endif
% Hyperlinks in PDF:
+\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage[%
colorlinks=true,
- linkcolor=blue,
- urlcolor=blue,
+ linkcolor=linkcolor,
+ urlcolor=linkcolor,
citecolor=black,
filecolor=black,
%filecolor=blue,
@@ -1418,7 +1426,7 @@
INTRO['latex'] += r"""
% Admonition is an oval gray box
\newmdenv[
- backgroundcolor=gray!10, %% white with 10%% gray
+ backgroundcolor=gray!5, %% white with 5%% gray
skipabove=\topsep,
skipbelow=\topsep,
outerlinewidth=0.5,
=======================================
--- /lib/doconce/misc.py Sun Jun 9 05:29:27 2013
+++ /lib/doconce/misc.py Mon Jun 24 11:00:38 2013
@@ -4058,6 +4058,7 @@
(r'^\s*file=[A-Za-z_0-9.]+\s*$', '', re.MULTILINE),
(r"^@@@CODE.*$", "", re.MULTILINE),
(r"^\s*(FIGURE|MOVIE):\s*\[.+?\]", "", re.MULTILINE),
+ (r"^\s*BIBFILE:.+$", "", re.MULTILINE),
(r"^\s*TOC:\s+(on|off)", "", re.MULTILINE),
(r"\$.+?\$", ""), # inline math (before mako variables)
(r"\$\{.*?\}", ""), # mako variables (clashes with math: ${\cal
O}(dx)$)
=======================================
--- /test/admon.do.txt Tue Jun 11 01:50:39 2013
+++ /test/admon.do.txt Mon Jun 24 11:00:38 2013
@@ -84,9 +84,13 @@
!bnotice (illegal-size) Note, eventually!
Ah, we are soon close to the end (with illegal font size specification!).
-But first a bit of math:
+But first a bit of math where we define $\theta$ and $\bm{r}$:
+
!bt
-\[ p=q\]
+\begin{align*}
+\theta &= q^2,\\
+\bm{r} &= \varrho\bm{i}
+\end{align*}
!et
!enotice
Reply all
Reply to author
Forward
0 new messages