[doconce.wiki] push by h...@simula.no - updates on 2013-08-11 06:22 GMT

[doc...@googlecode.com]

Revision: 42144bd68a11
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Sat Aug 10 23:22:55 2013
Log: updates
http://code.google.com/p/doconce/source/detail?r=42144bd68a11&repo=wiki

Modified:
/Description.wiki
/Tutorial.wiki

=======================================
--- /Description.wiki Sat Jul 13 00:17:11 2013
+++ /Description.wiki Sat Aug 10 23:22:55 2013
@@ -1,7 +1,7 @@
#summary Doconce Description

By *Hans Petter Langtangen*
-==== Jul 13, 2013 ====
+==== Aug 11, 2013 ====

<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
@@ -39,11 +39,11 @@

*History.* Doconce was developed in 2006 at a time when most popular
markup languages used quite some tagging. Later, almost untagged
-markup languages like Markdown and Pandoc became popular. Doconce is
-not a replacement of Pandoc, which is a considerably more
-sophisticated project. Moreover, Doconce was developed mainly to
-fulfill the needs for a flexible source code base for books with much
-mathematics and computer code.
+markup languages like Markdown and the Pandoc translator became
+popular. Doconce is not a replacement of Pandoc, which is a
+considerably more sophisticated project. Moreover, Doconce was
+developed mainly to fulfill the needs for a flexible source code base
+for books with much mathematics and computer code.

*Disclaimer.* Doconce is a simple tool, largely based on interpreting
and handling text through regular expressions. The possibility for
@@ -701,8 +701,8 @@
--html_output=mydoc_bloodish
Terminal> doconce split_html mydoc_bloodish.html
Terminal> doconce format html mydoc --html_style=solarized \
- --html_output=mydoc_solarized --pygments_html=perldoc \
- --html_admon=apricot
+ --html_output=mydoc_solarized \
+ --pygments_html_style=perldoc --html_admon=apricot
Terminal> doconce format html mydoc --html_style=vagrant \
--html_output=mydoc_vagrant --pygments_html_style=default \
--html_template=templates/my_adapted_vagrant_template.html
@@ -822,6 +822,60 @@
The `-s` option adds a proper header and footer to the `mydoc.html` file.
This recipe is a quick way of makeing HTML notes with (some) mathematics.

+==== GitHub-flavored Markdown ====
+
+Adding the command-line option `github-md` turns on the GutHub-flavored
+Markdown dialect, which is used for the issue tracker on
[http://github.com GitHub]. A special feature is the support of task lists:
+unnumbered lists with `[x]` (task done) or `[ ]` (task not done).
+(Tables get typeset directly as HTML and the syntax for code highlighting
+is different from Pandoc extended Markdown.) Here is an example:
+
+{{{
+!bquote
+===== Problems with a function =====
+
+There is a problem with the `f(x)` function
+
+!bc pycod
+def f(x):
+ return 1 + x
+!ec
+This function should be quadratic.
+!equote
+
+OK, this is fixed:
+
+!bc pycod
+def f(x, a=1, b=1, c=1):
+ return a*x**2 + b*x + c
+!ec
+
+===== Updated task list =====
+
+ * [x] Offer an `f(x)` function
+ * [ ] Extension to cubic functions
+ * [x] Allowing general coefficient in the quadratic function
+
+=== Remaining functionality ===
+
+|---------------------------------------------------------------|
+| function | purpose | state |
+|----l-----------l------------------------------l---------------|
+| `g(x)` | Compute the Gaussian function. | Formula ready. |
+| `h(x)` | Heaviside function. | Formula ready. |
+| `I(x)` | Indicator function. | Nothing done yet. |
+|---------------------------------------------------------------|
+}}}
+Say this text is stored in a file `mycomments.do.txt`. Running
+
+{{{
+Terminal> doconce format pandoc mycomments --github_md
+}}}
+produces `mycomments.md` which can be pasted into the Write field of
+the GitHub issue tracker. Turning on Preview shows the typesetting of
+the quote, compute code, inline verbatim, headings, the task list, and
+the table.
+

==== LaTeX ====

@@ -841,11 +895,11 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.

-An option `-DDEVICE=paper` makes some adjustments for documents
+An option `--device=paper` makes some adjustments for documents
aimed at being printed. For example, links to web resources are
associated with a footnote listing the complete web address (URL).
-The default, `-DDEVICE=screen`, creates a PDF file for reading
-on a screen where links are clickable.
+The default, `--device=screen`, creates a PDF file for reading
+on a screen where links are just clickable.

*Step 2.* Run `ptex2tex` (if you have it) to make a standard LaTeX file,
{{{
@@ -1776,6 +1830,19 @@
with a leading space and a trailing space, comma, semi-colon, or question
mark (but not period!) becomes a link with the web address as link text.)

+==== Mail Addresses ====
+
+Links that launches a mail to a specified address is written as
+ordinary URLs, typically as
+
+{{{
+Send "mail": "mailto:h...@simula.no"
+# Alternative:
+to "`h...@simula.no`": "mailto:h...@simula.no".
+}}}
+which appears as Send [mailto:h...@simula.no mail] to
+[mailto:h...@simula.no `h...@simula.no`].
+
==== Links to Local Files ====

Links to files ending in `.txt`, `.html`, `.pdf`, `.py`, `.f`,
@@ -2840,11 +2907,11 @@
Some recommended combinations for admonitions in HTML are


- * `--html_admon=apricot`, `--html_style=solarized`
- * `--html_admon=yellow`, `--html_style=bluish2`, `--no_pygments_html`
- * `--html_admon=yellow`, `--html_style=blueish2`,
`--pygments_html_style=default`
- * `--html_admon=gray`, `--html_style=bloodish`, `--no_pygments_html`
- * `--html_admon=gray`, `--html_style=bloodish`,
`--pygments_html_style=default`
+ * `--html_style=solarized`, `--html_admon=apricot`,
`--pygments_html_style=perldoc`
+ * `--html_style=blueish2`, `--html_admon=yellow`, `--no_pygments_html`
+ * `--html_style=blueish2`, `--html_admon=yellow`,
`--pygments_html_style=default`
+ * `--html_style=bloodish`, `--html_admon=gray`, `--no_pygments_html`
+ * `--html_style=bloodish`, `--html_admon=gray`,
`--pygments_html_style=default`
* `--html_style=vagrant`, `--pygments_html_style=default`,
`--html_template=...`

The `vagrant` HTML style has CSS files that override the definition
=======================================
--- /Tutorial.wiki Sat Jul 13 00:17:11 2013
+++ /Tutorial.wiki Sat Aug 10 23:22:55 2013
@@ -2,7 +2,7 @@
#summary Doconce: Document Once, Include Anywhere

By *Hans Petter Langtangen*
-==== Jul 13, 2013 ====
+==== Aug 11, 2013 ====

* When writing a note, report, manual, etc., do you find it difficult
to choose the typesetting format? That is, to choose between plain
(email-like) text, wiki, Word/OpenOffice, LaTeX, HTML, reStructuredText,
Sphinx, XML, etc. Would it be convenient to start with some very simple
text-like format that easily converts to the formats listed above, and
then at some later stage eventually go with a particular format?
* Do you need to write documents in varying formats but find it
difficult to remember all the typesetting details of various formats like
[http://refcards.com/docs/silvermanj/amslatex/LaTeXRefCard.v2.0.pdf LaTeX],
[http://www.htmlcodetutorial.com/ HTML],
[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
reStructuredText], [http://sphinx.pocoo.org/contents.html Sphinx], and
[http://code.google.com/p/support/wiki/WikiSyntax wiki]? Would it be
convenient to generate the typesetting details of a particular format
from a very simple text-like format with minimal tagging?
@@ -524,8 +524,8 @@
--html_output=mydoc_bloodish
Terminal> doconce split_html mydoc_bloodish.html
Terminal> doconce format html mydoc --html_style=solarized \
- --html_output=mydoc_solarized --pygments_html=perldoc \
- --html_admon=apricot
+ --html_output=mydoc_solarized \
+ --pygments_html_style=perldoc --html_admon=apricot
Terminal> doconce format html mydoc --html_style=vagrant \
--html_output=mydoc_vagrant --pygments_html_style=default \
--html_template=templates/my_adapted_vagrant_template.html
@@ -645,6 +645,60 @@
The `-s` option adds a proper header and footer to the `mydoc.html` file.
This recipe is a quick way of makeing HTML notes with (some) mathematics.

+==== GitHub-flavored Markdown ====
+
+Adding the command-line option `github-md` turns on the GutHub-flavored
+Markdown dialect, which is used for the issue tracker on
[http://github.com GitHub]. A special feature is the support of task lists:
+unnumbered lists with `[x]` (task done) or `[ ]` (task not done).
+(Tables get typeset directly as HTML and the syntax for code highlighting
+is different from Pandoc extended Markdown.) Here is an example:
+
+{{{
+!bquote
+===== Problems with a function =====
+
+There is a problem with the `f(x)` function
+
+!bc pycod
+def f(x):
+ return 1 + x
+!ec
+This function should be quadratic.
+!equote
+
+OK, this is fixed:
+
+!bc pycod
+def f(x, a=1, b=1, c=1):
+ return a*x**2 + b*x + c
+!ec
+
+===== Updated task list =====
+
+ * [x] Offer an `f(x)` function
+ * [ ] Extension to cubic functions
+ * [x] Allowing general coefficient in the quadratic function
+
+=== Remaining functionality ===
+
+|---------------------------------------------------------------|
+| function | purpose | state |
+|----l-----------l------------------------------l---------------|
+| `g(x)` | Compute the Gaussian function. | Formula ready. |
+| `h(x)` | Heaviside function. | Formula ready. |
+| `I(x)` | Indicator function. | Nothing done yet. |
+|---------------------------------------------------------------|
+}}}
+Say this text is stored in a file `mycomments.do.txt`. Running
+
+{{{
+Terminal> doconce format pandoc mycomments --github_md
+}}}
+produces `mycomments.md` which can be pasted into the Write field of
+the GitHub issue tracker. Turning on Preview shows the typesetting of
+the quote, compute code, inline verbatim, headings, the task list, and
+the table.
+

==== LaTeX ====

@@ -664,11 +718,11 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.

-An option `-DDEVICE=paper` makes some adjustments for documents
+An option `--device=paper` makes some adjustments for documents
aimed at being printed. For example, links to web resources are
associated with a footnote listing the complete web address (URL).
-The default, `-DDEVICE=screen`, creates a PDF file for reading
-on a screen where links are clickable.
+The default, `--device=screen`, creates a PDF file for reading
+on a screen where links are just clickable.

*Step 2.* Run `ptex2tex` (if you have it) to make a standard LaTeX file,
{{{