[doconce.wiki] push by h...@simula.no - updates on 2013-07-13 07:15 GMT
1 view
Skip to first unread message
doc...@googlecode.com
Jul 13, 2013, 3:16:10 AM7/13/13
to docon...@googlegroups.com
Revision: 22f948fb09bf
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Sat Jul 13 00:17:11 2013
Log: updates
http://code.google.com/p/doconce/source/detail?r=22f948fb09bf&repo=wiki
Modified:
/Description.wiki
/Quickref.wiki
/Tutorial.wiki
=======================================
--- /Description.wiki Fri Jun 28 09:25:55 2013
+++ /Description.wiki Sat Jul 13 00:17:11 2013
@@ -1,7 +1,7 @@
#summary Doconce Description
By *Hans Petter Langtangen*
-==== Jun 28, 2013 ====
+==== Jul 13, 2013 ====
<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
@@ -604,6 +604,8 @@
==== HTML ====
+==== Basics ====
+
Making an HTML version of a Doconce file `mydoc.do.txt`
is performed by
{{{
@@ -611,6 +613,21 @@
}}}
The resulting file `mydoc.html` can be loaded into any web browser for
viewing.
+==== Typesetting of Code ====
+
+If the Pygments package (including the `pygmentize` program)
+is installed, code blocks are typeset with
+aid of this package. The command-line argument `--no_pygments_html`
+turns off the use of Pygments and makes code blocks appear with
+plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
+on line numbers in Pygments-formatted code blocks. A specific
+Pygments style is set by `--pygments_html_style=style`, where `style`
+can be `default`, `emacs`, `perldoc`, and other valid names for
+Pygments styles.
+
+
+==== HTML Styles ====
+
The HTML style can be defined either in the header of the HTML file,
using a named built-in style;
in an external CSS file; or in a template file.
@@ -630,22 +647,14 @@
links to the CSS stylesheet in `filename`. Several stylesheets can
be specified: `--ccs=file1.css,file2.css,file3.css`.
+==== HTML templates ====
+
Templates are HTML files with "slots" `%(main)s` for the main body
of text, `%(title)s` for the title, and `%(date)s` for the date.
Doconce comes with a few templates. The usage of templates is
described in a
[https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html separate
document]. That document describes how you your Doconce-generated
HTML file can have any specified layout.
-If the Pygments package (including the `pygmentize` program)
-is installed, code blocks are typeset with
-aid of this package. The command-line argument `--no_pygments_html`
-turns off the use of Pygments and makes code blocks appear with
-plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
-on line numbers in Pygments-formatted code blocks. A specific
-Pygments style is set by `--pygments_html_style=style`, where `style`
-can be `default`, `emacs`, `perldoc`, and other valid names for
-Pygments styles.
-
The HTML file can be embedded in a template with your own tailored
design, see a [
https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html tutorial] on
this topic. The template file must contain
valid HTML code and can have three "slots": `%(title)s` for a title,
@@ -669,6 +678,36 @@
that are used if the document contains `!split` commands for splitting
it into many pages.
+==== The HTML File Collection ====
+
+There are usually a range of files needed for an HTML document arising
+from a Doconce source. The needed files are listed in
+`.basename_html_file_collection`, where `basename` is the filestem of
+the Doconce file (i.e., the Doconce source is in `basename.do.txt`).
+
+==== Filenames ====
+
+An HTML version of a Doconce document is often made in different styles,
+calling for a need to rename the HTML output file. This is conveniently
+done by the `--html_output=basename` option, where `basename` is the
+filestem of the associated HTML files. The
+`.basename_html_file_collection` file lists all the needed files
+for the HTML document. Here is an example on making three versions of
+the HTML document: `mydoc_bloodish.html`, `mydoc_solarized`, and
+`mydoc_vagrant`.
+
+{{{
+Terminal> doconce format html mydoc --html_style=bloodish \
+ --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
+Terminal> doconce format html mydoc --html_style=vagrant \
+ --html_output=mydoc_vagrant --pygments_html_style=default \
+ --html_template=templates/my_adapted_vagrant_template.html
+Terminal> doconce split_html mydoc_vagrant.html
+}}}
==== Blog Posts ====
@@ -802,9 +841,11 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.
-An option `--latex_printed` makes some adjustments for documents
+An option `-DDEVICE=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.
*Step 2.* Run `ptex2tex` (if you have it) to make a standard LaTeX file,
{{{
@@ -839,11 +880,11 @@
* `A4PAPER` for A4 paper size
* `A6PAPER` for A6 paper size (suitable for reading PDFs on phones)
* `MOVIE` for specifying how movies are handled: the value `media9`
implies the `media9` package and the `\includemedia` command (default),
while other values are `movie15` (`\includemovie` command), `multimedia`
(for Beamer-style `\movie` command), or `href-run` (for the plain
`\hrun:file` command)
+ * `MOVIE_CONTROLS` adds buttons for starting/stopping movies if the
`media9` package is used.
* `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere - and note that the
preamble is only included if the document has a title, author, and date)
* `MINTED` for inclusion of the minted package for typesetting of code
with the Pygments tool (which requires `latex` or `pdflatex` to be run
with the `-shell-escape` option)
* `TODONOTES` for using the fancy `todonotes` package for typesetting
inline comments (looks much like track changes in MS Word). This macro
has only effect if inline comments are used (name, colon, and comment
inside brackets).
* `LINENUMBERS` for inclusion of line numbers in the text.
- * `AMON` for setting the type of admonitions: `"colors"` for colored
boxes with icons, `"graybox1"` for gray frame boxes with rounded corners
(default), `"graybox2"` for narrower square gray frame boxes (except for
summary, which for A4 format is small and with wrapped text around if it
does not contain verbatim code), or `"paragraph"` for simple, plain
paragraph headings and ordinary text
* `COLORED_TABLE_ROWS` for coloring every other table rows (set this
variable to `gray` or `blue`)
* `BLUE_SECTION_HEADINGS` for blue section and subsection headings
* `LATEX_HEADING` for the typesetting of the title, author, parts of
preamble (values: `traditional` for traditional LaTeX heading,
`titlepage` for a separate titlepage, `Springer_collection` for edited
volumes on Springer, `beamer` for Beamer slides, `doconce_heading`
(default) for listing institutions after names)
@@ -880,10 +921,18 @@
begin and end for blocks inside `!bc fpro` and `!ec`). Specifying
`envir=ans:nt` means that all other environments are typeset with the
`anslistings.sty` package, e.g., `!bc cppcod` will then result in
-`\begin{c++}`. If no environments like `sys`, `fpro`, or the common
-`envir` are defined on the command line, the plain `\begin{verbatim}`
-and `\end{verbatim}` used.
+`\begin{c++}`. A predefined shortcut as in `shcod=Verbatim-0.85`
+results in denser
+vertical spacing (baselinestretch 0.85 in LaTeX terminology), and
+`shcod=Verbatim-indent` implies indentation of the verbatim text.
+Alternatively, one can provide all desired parameters
+`\begin{Verbatim}` instruction using the syntax illustrated for
+the `sys` environments above.
+If no environments like `sys`, `fpro`, or the common
+`envir` are defined on the command line, the plain `\begin{Verbatim}`
+and `\end{Verbatim}` instructions are used.
+
*Step 2b (optional).* Edit the `mydoc.tex` file to your needs.
For example, you may want to substitute `section` by `section*` to
@@ -1493,6 +1542,7 @@
Here are some examples:
+
{{{
__Abstract.__ The following text just attempts to exemplify
various section headings.
@@ -1501,11 +1551,6 @@
(this affects only `latex` output, where the appendix formatting
is used - all other formats just leave the heading as it is written).
-========= Example on a Chapter Heading =========
-
-Some text.
-
-
======= Example on a Section Heading =======
The running text goes here.
@@ -1532,7 +1577,7 @@
Figures are recognized by the special line syntax
{{{
-FIGURE:[filename, height=xxx width=yyy scale=zzz] possible caption
+FIGURE:[filename, height=400 width=600 frac=0.8] caption
}}}
The filename can be without extension, and Doconce will search for an
@@ -1541,10 +1586,21 @@
file, and if not, the given file is converted to a proper format
(using ImageMagick's `convert` utility).
-The height, width, and scale keywords (and others) can be included
-if desired and may have effect for some formats. Note the comma
-between the sespecifications and that there should be no space
-around the = sign.
+The height, width, and frac keywords can be included
+if desired and may have effect for some formats: the height and width
+are used for output in the formats `html`, `rst`, `sphinx`, while
+the frac specification is used for `latex` and `pdflatex` to specify
+the width of the image as a fraction of the text width.
+
+The figure caption is optional. If omitted, the figure appears "inline"
+in the text without any figure environment in LaTeX formats or HTML.
+The caption may contain a label for referencing the figure.
+
+*Warning.*
+Note the comma
+between the filename and the figure size specifications and
+that there should be no space around the = sign. This syntax must
+be strictly followed.
Note also that, like for `TITLE:` and `AUTHOR:` lines, all information
related to a figure line *must be written on the same line*. Introducing
@@ -1552,8 +1608,6 @@
part of the caption appearing on the same line as `FIGURE:` will be
included in the formatted caption).
-
-
---------------------------------------------------------------
Figure: Streamtube visualization of a fluid flow. (fig:viz)
@@ -1637,12 +1691,16 @@
{{{
MOVIE: [http://www.youtube.com/watch?v=sI2uCHH3qIM, width=420 height=315]
-MOVIE: [http://vimeo.com/55562330, width=500 height=278] Computational
fluid dynamics movie.
+MOVIE: [http://vimeo.com/55562330, width=500 height=278] CFD.
}}}
Note that there must be a blank line after every `MOVIE:` command.
The width and height parameters are not required, but leaving them out
may lead to movie sizes you do not want.
+ http://www.youtube.com/watch?v=sI2uCHH3qIM
+
+ CFD. http://vimeo.com/55562330
+
==== Copying Computer Code from Source Files ====
Another type of special lines starts with `@@@CODE` and enables copying
=======================================
--- /Quickref.wiki Fri Jun 28 09:25:55 2013
+++ /Quickref.wiki Sat Jul 13 00:17:11 2013
@@ -1,7 +1,7 @@
#summary Doconce Quick Reference
By *Hans Petter Langtangen*
-==== Jun 8, 2013 ====
+==== Jul 13, 2013 ====
<wiki: toc max_depth="2" />
@@ -430,7 +430,7 @@
Figures and movies have almost equal syntax:
{{{
-FIGURE: [relative/path/to/figurefile, width=500] Here goes the caption
which must be on a single line. label{some:fig:label}
+FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the
caption which must be on a single line. label{some:fig:label}
MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which
must be on a single line. label{some:fig:label}
@@ -439,6 +439,7 @@
# A mandatory comma after the figure/movie filename,
+ # no comments between `width`, `height`, and `frac` and no spaces
around the `=` characters,
# all of the command must appear on a single line,
# there must be a blank line after the command.
@@ -447,6 +448,12 @@
output format. If not suitable version is found, Doconce will convert
another format to the needed one.
+The caption is optional. If omitted, the figure will be inlined (meaning
+no use of any figure environment in HTML or LaTeX formats). The `width`
+and `height` parameters affect HTML formats (`html`, `rst`, `sphinx`),
+while `frac` is the width of the image as a fraction of the total text
+width in the `latex` and `pdflatex` formats.
+
Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.
=======================================
--- /Tutorial.wiki Fri Jun 28 09:25:55 2013
+++ /Tutorial.wiki Sat Jul 13 00:17:11 2013
@@ -2,7 +2,7 @@
#summary Doconce: Document Once, Include Anywhere
By *Hans Petter Langtangen*
-==== May 29, 2013 ====
+==== Jul 13, 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?
@@ -322,7 +322,7 @@
As see in Figure ref{mysec:fig:myfig}, the key equation
features large, smooth regions *and* abrupt changes.
-FIGURE: [fig/myfile, width=600] My figure. label{mysec:fig:myfig}
+FIGURE: [fig/myfile, width=600 frac=0.9] My figure. label{mysec:fig:myfig}
===== References =====
@@ -341,7 +341,7 @@
Transformation of a Doconce document `mydoc.do.txt` to various other
-formats applies the script `doconce format`:
+formats apply the script `doconce format`:
{{{
Terminal> doconce format format mydoc.do.txt
}}}
@@ -427,6 +427,8 @@
==== HTML ====
+==== Basics ====
+
Making an HTML version of a Doconce file `mydoc.do.txt`
is performed by
{{{
@@ -434,6 +436,21 @@
}}}
The resulting file `mydoc.html` can be loaded into any web browser for
viewing.
+==== Typesetting of Code ====
+
+If the Pygments package (including the `pygmentize` program)
+is installed, code blocks are typeset with
+aid of this package. The command-line argument `--no_pygments_html`
+turns off the use of Pygments and makes code blocks appear with
+plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
+on line numbers in Pygments-formatted code blocks. A specific
+Pygments style is set by `--pygments_html_style=style`, where `style`
+can be `default`, `emacs`, `perldoc`, and other valid names for
+Pygments styles.
+
+
+==== HTML Styles ====
+
The HTML style can be defined either in the header of the HTML file,
using a named built-in style;
in an external CSS file; or in a template file.
@@ -453,22 +470,14 @@
links to the CSS stylesheet in `filename`. Several stylesheets can
be specified: `--ccs=file1.css,file2.css,file3.css`.
+==== HTML templates ====
+
Templates are HTML files with "slots" `%(main)s` for the main body
of text, `%(title)s` for the title, and `%(date)s` for the date.
Doconce comes with a few templates. The usage of templates is
described in a
[https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html separate
document]. That document describes how you your Doconce-generated
HTML file can have any specified layout.
-If the Pygments package (including the `pygmentize` program)
-is installed, code blocks are typeset with
-aid of this package. The command-line argument `--no_pygments_html`
-turns off the use of Pygments and makes code blocks appear with
-plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
-on line numbers in Pygments-formatted code blocks. A specific
-Pygments style is set by `--pygments_html_style=style`, where `style`
-can be `default`, `emacs`, `perldoc`, and other valid names for
-Pygments styles.
-
The HTML file can be embedded in a template with your own tailored
design, see a [
https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html tutorial] on
this topic. The template file must contain
valid HTML code and can have three "slots": `%(title)s` for a title,
@@ -492,6 +501,36 @@
that are used if the document contains `!split` commands for splitting
it into many pages.
+==== The HTML File Collection ====
+
+There are usually a range of files needed for an HTML document arising
+from a Doconce source. The needed files are listed in
+`.basename_html_file_collection`, where `basename` is the filestem of
+the Doconce file (i.e., the Doconce source is in `basename.do.txt`).
+
+==== Filenames ====
+
+An HTML version of a Doconce document is often made in different styles,
+calling for a need to rename the HTML output file. This is conveniently
+done by the `--html_output=basename` option, where `basename` is the
+filestem of the associated HTML files. The
+`.basename_html_file_collection` file lists all the needed files
+for the HTML document. Here is an example on making three versions of
+the HTML document: `mydoc_bloodish.html`, `mydoc_solarized`, and
+`mydoc_vagrant`.
+
+{{{
+Terminal> doconce format html mydoc --html_style=bloodish \
+ --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
+Terminal> doconce format html mydoc --html_style=vagrant \
+ --html_output=mydoc_vagrant --pygments_html_style=default \
+ --html_template=templates/my_adapted_vagrant_template.html
+Terminal> doconce split_html mydoc_vagrant.html
+}}}
==== Blog Posts ====
@@ -625,9 +664,11 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.
-An option `--latex_printed` makes some adjustments for documents
+An option `-DDEVICE=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.
*Step 2.* Run `ptex2tex` (if you have it) to make a standard LaTeX file,
{{{
@@ -662,11 +703,11 @@
* `A4PAPER` for A4 paper size
* `A6PAPER` for A6 paper size (suitable for reading PDFs on phones)
* `MOVIE` for specifying how movies are handled: the value `media9`
implies the `media9` package and the `\includemedia` command (default),
while other values are `movie15` (`\includemovie` command), `multimedia`
(for Beamer-style `\movie` command), or `href-run` (for the plain
`\hrun:file` command)
+ * `MOVIE_CONTROLS` adds buttons for starting/stopping movies if the
`media9` package is used.
* `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere - and note that the
preamble is only included if the document has a title, author, and date)
* `MINTED` for inclusion of the minted package for typesetting of code
with the Pygments tool (which requires `latex` or `pdflatex` to be run
with the `-shell-escape` option)
* `TODONOTES` for using the fancy `todonotes` package for typesetting
inline comments (looks much like track changes in MS Word). This macro
has only effect if inline comments are used (name, colon, and comment
inside brackets).
* `LINENUMBERS` for inclusion of line numbers in the text.
- * `AMON` for setting the type of admonitions: `"colors"` for colored
boxes with icons, `"graybox1"` for gray frame boxes with rounded corners
(default), `"graybox2"` for narrower square gray frame boxes (except for
summary, which for A4 format is small and with wrapped text around if it
does not contain verbatim code), or `"paragraph"` for simple, plain
paragraph headings and ordinary text
* `COLORED_TABLE_ROWS` for coloring every other table rows (set this
variable to `gray` or `blue`)
* `BLUE_SECTION_HEADINGS` for blue section and subsection headings
* `LATEX_HEADING` for the typesetting of the title, author, parts of
preamble (values: `traditional` for traditional LaTeX heading,
`titlepage` for a separate titlepage, `Springer_collection` for edited
volumes on Springer, `beamer` for Beamer slides, `doconce_heading`
(default) for listing institutions after names)
@@ -703,9 +744,17 @@
begin and end for blocks inside `!bc fpro` and `!ec`). Specifying
`envir=ans:nt` means that all other environments are typeset with the
`anslistings.sty` package, e.g., `!bc cppcod` will then result in
-`\begin{c++}`. If no environments like `sys`, `fpro`, or the common
-`envir` are defined on the command line, the plain `\begin{verbatim}`
-and `\end{verbatim}` used.
+`\begin{c++}`. A predefined shortcut as in `shcod=Verbatim-0.85`
+results in denser
+vertical spacing (baselinestretch 0.85 in LaTeX terminology), and
+`shcod=Verbatim-indent` implies indentation of the verbatim text.
+Alternatively, one can provide all desired parameters
+`\begin{Verbatim}` instruction using the syntax illustrated for
+the `sys` environments above.
+
+If no environments like `sys`, `fpro`, or the common
+`envir` are defined on the command line, the plain `\begin{Verbatim}`
+and `\end{Verbatim}` instructions are used.
*Step 2b (optional).* Edit the `mydoc.tex` file to your needs.
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Sat Jul 13 00:17:11 2013
Log: updates
http://code.google.com/p/doconce/source/detail?r=22f948fb09bf&repo=wiki
Modified:
/Description.wiki
/Quickref.wiki
/Tutorial.wiki
=======================================
--- /Description.wiki Fri Jun 28 09:25:55 2013
+++ /Description.wiki Sat Jul 13 00:17:11 2013
@@ -1,7 +1,7 @@
#summary Doconce Description
By *Hans Petter Langtangen*
-==== Jun 28, 2013 ====
+==== Jul 13, 2013 ====
<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
@@ -604,6 +604,8 @@
==== HTML ====
+==== Basics ====
+
Making an HTML version of a Doconce file `mydoc.do.txt`
is performed by
{{{
@@ -611,6 +613,21 @@
}}}
The resulting file `mydoc.html` can be loaded into any web browser for
viewing.
+==== Typesetting of Code ====
+
+If the Pygments package (including the `pygmentize` program)
+is installed, code blocks are typeset with
+aid of this package. The command-line argument `--no_pygments_html`
+turns off the use of Pygments and makes code blocks appear with
+plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
+on line numbers in Pygments-formatted code blocks. A specific
+Pygments style is set by `--pygments_html_style=style`, where `style`
+can be `default`, `emacs`, `perldoc`, and other valid names for
+Pygments styles.
+
+
+==== HTML Styles ====
+
The HTML style can be defined either in the header of the HTML file,
using a named built-in style;
in an external CSS file; or in a template file.
@@ -630,22 +647,14 @@
links to the CSS stylesheet in `filename`. Several stylesheets can
be specified: `--ccs=file1.css,file2.css,file3.css`.
+==== HTML templates ====
+
Templates are HTML files with "slots" `%(main)s` for the main body
of text, `%(title)s` for the title, and `%(date)s` for the date.
Doconce comes with a few templates. The usage of templates is
described in a
[https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html separate
document]. That document describes how you your Doconce-generated
HTML file can have any specified layout.
-If the Pygments package (including the `pygmentize` program)
-is installed, code blocks are typeset with
-aid of this package. The command-line argument `--no_pygments_html`
-turns off the use of Pygments and makes code blocks appear with
-plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
-on line numbers in Pygments-formatted code blocks. A specific
-Pygments style is set by `--pygments_html_style=style`, where `style`
-can be `default`, `emacs`, `perldoc`, and other valid names for
-Pygments styles.
-
The HTML file can be embedded in a template with your own tailored
design, see a [
https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html tutorial] on
this topic. The template file must contain
valid HTML code and can have three "slots": `%(title)s` for a title,
@@ -669,6 +678,36 @@
that are used if the document contains `!split` commands for splitting
it into many pages.
+==== The HTML File Collection ====
+
+There are usually a range of files needed for an HTML document arising
+from a Doconce source. The needed files are listed in
+`.basename_html_file_collection`, where `basename` is the filestem of
+the Doconce file (i.e., the Doconce source is in `basename.do.txt`).
+
+==== Filenames ====
+
+An HTML version of a Doconce document is often made in different styles,
+calling for a need to rename the HTML output file. This is conveniently
+done by the `--html_output=basename` option, where `basename` is the
+filestem of the associated HTML files. The
+`.basename_html_file_collection` file lists all the needed files
+for the HTML document. Here is an example on making three versions of
+the HTML document: `mydoc_bloodish.html`, `mydoc_solarized`, and
+`mydoc_vagrant`.
+
+{{{
+Terminal> doconce format html mydoc --html_style=bloodish \
+ --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
+Terminal> doconce format html mydoc --html_style=vagrant \
+ --html_output=mydoc_vagrant --pygments_html_style=default \
+ --html_template=templates/my_adapted_vagrant_template.html
+Terminal> doconce split_html mydoc_vagrant.html
+}}}
==== Blog Posts ====
@@ -802,9 +841,11 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.
-An option `--latex_printed` makes some adjustments for documents
+An option `-DDEVICE=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.
*Step 2.* Run `ptex2tex` (if you have it) to make a standard LaTeX file,
{{{
@@ -839,11 +880,11 @@
* `A4PAPER` for A4 paper size
* `A6PAPER` for A6 paper size (suitable for reading PDFs on phones)
* `MOVIE` for specifying how movies are handled: the value `media9`
implies the `media9` package and the `\includemedia` command (default),
while other values are `movie15` (`\includemovie` command), `multimedia`
(for Beamer-style `\movie` command), or `href-run` (for the plain
`\hrun:file` command)
+ * `MOVIE_CONTROLS` adds buttons for starting/stopping movies if the
`media9` package is used.
* `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere - and note that the
preamble is only included if the document has a title, author, and date)
* `MINTED` for inclusion of the minted package for typesetting of code
with the Pygments tool (which requires `latex` or `pdflatex` to be run
with the `-shell-escape` option)
* `TODONOTES` for using the fancy `todonotes` package for typesetting
inline comments (looks much like track changes in MS Word). This macro
has only effect if inline comments are used (name, colon, and comment
inside brackets).
* `LINENUMBERS` for inclusion of line numbers in the text.
- * `AMON` for setting the type of admonitions: `"colors"` for colored
boxes with icons, `"graybox1"` for gray frame boxes with rounded corners
(default), `"graybox2"` for narrower square gray frame boxes (except for
summary, which for A4 format is small and with wrapped text around if it
does not contain verbatim code), or `"paragraph"` for simple, plain
paragraph headings and ordinary text
* `COLORED_TABLE_ROWS` for coloring every other table rows (set this
variable to `gray` or `blue`)
* `BLUE_SECTION_HEADINGS` for blue section and subsection headings
* `LATEX_HEADING` for the typesetting of the title, author, parts of
preamble (values: `traditional` for traditional LaTeX heading,
`titlepage` for a separate titlepage, `Springer_collection` for edited
volumes on Springer, `beamer` for Beamer slides, `doconce_heading`
(default) for listing institutions after names)
@@ -880,10 +921,18 @@
begin and end for blocks inside `!bc fpro` and `!ec`). Specifying
`envir=ans:nt` means that all other environments are typeset with the
`anslistings.sty` package, e.g., `!bc cppcod` will then result in
-`\begin{c++}`. If no environments like `sys`, `fpro`, or the common
-`envir` are defined on the command line, the plain `\begin{verbatim}`
-and `\end{verbatim}` used.
+`\begin{c++}`. A predefined shortcut as in `shcod=Verbatim-0.85`
+results in denser
+vertical spacing (baselinestretch 0.85 in LaTeX terminology), and
+`shcod=Verbatim-indent` implies indentation of the verbatim text.
+Alternatively, one can provide all desired parameters
+`\begin{Verbatim}` instruction using the syntax illustrated for
+the `sys` environments above.
+If no environments like `sys`, `fpro`, or the common
+`envir` are defined on the command line, the plain `\begin{Verbatim}`
+and `\end{Verbatim}` instructions are used.
+
*Step 2b (optional).* Edit the `mydoc.tex` file to your needs.
For example, you may want to substitute `section` by `section*` to
@@ -1493,6 +1542,7 @@
Here are some examples:
+
{{{
__Abstract.__ The following text just attempts to exemplify
various section headings.
@@ -1501,11 +1551,6 @@
(this affects only `latex` output, where the appendix formatting
is used - all other formats just leave the heading as it is written).
-========= Example on a Chapter Heading =========
-
-Some text.
-
-
======= Example on a Section Heading =======
The running text goes here.
@@ -1532,7 +1577,7 @@
Figures are recognized by the special line syntax
{{{
-FIGURE:[filename, height=xxx width=yyy scale=zzz] possible caption
+FIGURE:[filename, height=400 width=600 frac=0.8] caption
}}}
The filename can be without extension, and Doconce will search for an
@@ -1541,10 +1586,21 @@
file, and if not, the given file is converted to a proper format
(using ImageMagick's `convert` utility).
-The height, width, and scale keywords (and others) can be included
-if desired and may have effect for some formats. Note the comma
-between the sespecifications and that there should be no space
-around the = sign.
+The height, width, and frac keywords can be included
+if desired and may have effect for some formats: the height and width
+are used for output in the formats `html`, `rst`, `sphinx`, while
+the frac specification is used for `latex` and `pdflatex` to specify
+the width of the image as a fraction of the text width.
+
+The figure caption is optional. If omitted, the figure appears "inline"
+in the text without any figure environment in LaTeX formats or HTML.
+The caption may contain a label for referencing the figure.
+
+*Warning.*
+Note the comma
+between the filename and the figure size specifications and
+that there should be no space around the = sign. This syntax must
+be strictly followed.
Note also that, like for `TITLE:` and `AUTHOR:` lines, all information
related to a figure line *must be written on the same line*. Introducing
@@ -1552,8 +1608,6 @@
part of the caption appearing on the same line as `FIGURE:` will be
included in the formatted caption).
-
-
---------------------------------------------------------------
Figure: Streamtube visualization of a fluid flow. (fig:viz)
@@ -1637,12 +1691,16 @@
{{{
MOVIE: [http://www.youtube.com/watch?v=sI2uCHH3qIM, width=420 height=315]
-MOVIE: [http://vimeo.com/55562330, width=500 height=278] Computational
fluid dynamics movie.
+MOVIE: [http://vimeo.com/55562330, width=500 height=278] CFD.
}}}
Note that there must be a blank line after every `MOVIE:` command.
The width and height parameters are not required, but leaving them out
may lead to movie sizes you do not want.
+ http://www.youtube.com/watch?v=sI2uCHH3qIM
+
+ CFD. http://vimeo.com/55562330
+
==== Copying Computer Code from Source Files ====
Another type of special lines starts with `@@@CODE` and enables copying
=======================================
--- /Quickref.wiki Fri Jun 28 09:25:55 2013
+++ /Quickref.wiki Sat Jul 13 00:17:11 2013
@@ -1,7 +1,7 @@
#summary Doconce Quick Reference
By *Hans Petter Langtangen*
-==== Jun 8, 2013 ====
+==== Jul 13, 2013 ====
<wiki: toc max_depth="2" />
@@ -430,7 +430,7 @@
Figures and movies have almost equal syntax:
{{{
-FIGURE: [relative/path/to/figurefile, width=500] Here goes the caption
which must be on a single line. label{some:fig:label}
+FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the
caption which must be on a single line. label{some:fig:label}
MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which
must be on a single line. label{some:fig:label}
@@ -439,6 +439,7 @@
# A mandatory comma after the figure/movie filename,
+ # no comments between `width`, `height`, and `frac` and no spaces
around the `=` characters,
# all of the command must appear on a single line,
# there must be a blank line after the command.
@@ -447,6 +448,12 @@
output format. If not suitable version is found, Doconce will convert
another format to the needed one.
+The caption is optional. If omitted, the figure will be inlined (meaning
+no use of any figure environment in HTML or LaTeX formats). The `width`
+and `height` parameters affect HTML formats (`html`, `rst`, `sphinx`),
+while `frac` is the width of the image as a fraction of the total text
+width in the `latex` and `pdflatex` formats.
+
Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.
=======================================
--- /Tutorial.wiki Fri Jun 28 09:25:55 2013
+++ /Tutorial.wiki Sat Jul 13 00:17:11 2013
@@ -2,7 +2,7 @@
#summary Doconce: Document Once, Include Anywhere
By *Hans Petter Langtangen*
-==== May 29, 2013 ====
+==== Jul 13, 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?
@@ -322,7 +322,7 @@
As see in Figure ref{mysec:fig:myfig}, the key equation
features large, smooth regions *and* abrupt changes.
-FIGURE: [fig/myfile, width=600] My figure. label{mysec:fig:myfig}
+FIGURE: [fig/myfile, width=600 frac=0.9] My figure. label{mysec:fig:myfig}
===== References =====
@@ -341,7 +341,7 @@
Transformation of a Doconce document `mydoc.do.txt` to various other
-formats applies the script `doconce format`:
+formats apply the script `doconce format`:
{{{
Terminal> doconce format format mydoc.do.txt
}}}
@@ -427,6 +427,8 @@
==== HTML ====
+==== Basics ====
+
Making an HTML version of a Doconce file `mydoc.do.txt`
is performed by
{{{
@@ -434,6 +436,21 @@
}}}
The resulting file `mydoc.html` can be loaded into any web browser for
viewing.
+==== Typesetting of Code ====
+
+If the Pygments package (including the `pygmentize` program)
+is installed, code blocks are typeset with
+aid of this package. The command-line argument `--no_pygments_html`
+turns off the use of Pygments and makes code blocks appear with
+plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
+on line numbers in Pygments-formatted code blocks. A specific
+Pygments style is set by `--pygments_html_style=style`, where `style`
+can be `default`, `emacs`, `perldoc`, and other valid names for
+Pygments styles.
+
+
+==== HTML Styles ====
+
The HTML style can be defined either in the header of the HTML file,
using a named built-in style;
in an external CSS file; or in a template file.
@@ -453,22 +470,14 @@
links to the CSS stylesheet in `filename`. Several stylesheets can
be specified: `--ccs=file1.css,file2.css,file3.css`.
+==== HTML templates ====
+
Templates are HTML files with "slots" `%(main)s` for the main body
of text, `%(title)s` for the title, and `%(date)s` for the date.
Doconce comes with a few templates. The usage of templates is
described in a
[https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html separate
document]. That document describes how you your Doconce-generated
HTML file can have any specified layout.
-If the Pygments package (including the `pygmentize` program)
-is installed, code blocks are typeset with
-aid of this package. The command-line argument `--no_pygments_html`
-turns off the use of Pygments and makes code blocks appear with
-plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
-on line numbers in Pygments-formatted code blocks. A specific
-Pygments style is set by `--pygments_html_style=style`, where `style`
-can be `default`, `emacs`, `perldoc`, and other valid names for
-Pygments styles.
-
The HTML file can be embedded in a template with your own tailored
design, see a [
https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html tutorial] on
this topic. The template file must contain
valid HTML code and can have three "slots": `%(title)s` for a title,
@@ -492,6 +501,36 @@
that are used if the document contains `!split` commands for splitting
it into many pages.
+==== The HTML File Collection ====
+
+There are usually a range of files needed for an HTML document arising
+from a Doconce source. The needed files are listed in
+`.basename_html_file_collection`, where `basename` is the filestem of
+the Doconce file (i.e., the Doconce source is in `basename.do.txt`).
+
+==== Filenames ====
+
+An HTML version of a Doconce document is often made in different styles,
+calling for a need to rename the HTML output file. This is conveniently
+done by the `--html_output=basename` option, where `basename` is the
+filestem of the associated HTML files. The
+`.basename_html_file_collection` file lists all the needed files
+for the HTML document. Here is an example on making three versions of
+the HTML document: `mydoc_bloodish.html`, `mydoc_solarized`, and
+`mydoc_vagrant`.
+
+{{{
+Terminal> doconce format html mydoc --html_style=bloodish \
+ --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
+Terminal> doconce format html mydoc --html_style=vagrant \
+ --html_output=mydoc_vagrant --pygments_html_style=default \
+ --html_template=templates/my_adapted_vagrant_template.html
+Terminal> doconce split_html mydoc_vagrant.html
+}}}
==== Blog Posts ====
@@ -625,9 +664,11 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.
-An option `--latex_printed` makes some adjustments for documents
+An option `-DDEVICE=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.
*Step 2.* Run `ptex2tex` (if you have it) to make a standard LaTeX file,
{{{
@@ -662,11 +703,11 @@
* `A4PAPER` for A4 paper size
* `A6PAPER` for A6 paper size (suitable for reading PDFs on phones)
* `MOVIE` for specifying how movies are handled: the value `media9`
implies the `media9` package and the `\includemedia` command (default),
while other values are `movie15` (`\includemovie` command), `multimedia`
(for Beamer-style `\movie` command), or `href-run` (for the plain
`\hrun:file` command)
+ * `MOVIE_CONTROLS` adds buttons for starting/stopping movies if the
`media9` package is used.
* `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere - and note that the
preamble is only included if the document has a title, author, and date)
* `MINTED` for inclusion of the minted package for typesetting of code
with the Pygments tool (which requires `latex` or `pdflatex` to be run
with the `-shell-escape` option)
* `TODONOTES` for using the fancy `todonotes` package for typesetting
inline comments (looks much like track changes in MS Word). This macro
has only effect if inline comments are used (name, colon, and comment
inside brackets).
* `LINENUMBERS` for inclusion of line numbers in the text.
- * `AMON` for setting the type of admonitions: `"colors"` for colored
boxes with icons, `"graybox1"` for gray frame boxes with rounded corners
(default), `"graybox2"` for narrower square gray frame boxes (except for
summary, which for A4 format is small and with wrapped text around if it
does not contain verbatim code), or `"paragraph"` for simple, plain
paragraph headings and ordinary text
* `COLORED_TABLE_ROWS` for coloring every other table rows (set this
variable to `gray` or `blue`)
* `BLUE_SECTION_HEADINGS` for blue section and subsection headings
* `LATEX_HEADING` for the typesetting of the title, author, parts of
preamble (values: `traditional` for traditional LaTeX heading,
`titlepage` for a separate titlepage, `Springer_collection` for edited
volumes on Springer, `beamer` for Beamer slides, `doconce_heading`
(default) for listing institutions after names)
@@ -703,9 +744,17 @@
begin and end for blocks inside `!bc fpro` and `!ec`). Specifying
`envir=ans:nt` means that all other environments are typeset with the
`anslistings.sty` package, e.g., `!bc cppcod` will then result in
-`\begin{c++}`. If no environments like `sys`, `fpro`, or the common
-`envir` are defined on the command line, the plain `\begin{verbatim}`
-and `\end{verbatim}` used.
+`\begin{c++}`. A predefined shortcut as in `shcod=Verbatim-0.85`
+results in denser
+vertical spacing (baselinestretch 0.85 in LaTeX terminology), and
+`shcod=Verbatim-indent` implies indentation of the verbatim text.
+Alternatively, one can provide all desired parameters
+`\begin{Verbatim}` instruction using the syntax illustrated for
+the `sys` environments above.
+
+If no environments like `sys`, `fpro`, or the common
+`envir` are defined on the command line, the plain `\begin{Verbatim}`
+and `\end{Verbatim}` instructions are used.
*Step 2b (optional).* Edit the `mydoc.tex` file to your needs.
Reply all
Reply to author
Forward
0 new messages