diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/generic/markdown/markdown.md |
Initial commit
Diffstat (limited to 'macros/generic/markdown/markdown.md')
-rw-r--r-- | macros/generic/markdown/markdown.md | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/macros/generic/markdown/markdown.md b/macros/generic/markdown/markdown.md new file mode 100644 index 0000000000..ddd8c67dcd --- /dev/null +++ b/macros/generic/markdown/markdown.md @@ -0,0 +1,278 @@ + +--- +title: Markdown Package User Manual +author: Vít Novotný +date: v\markdownVersion{} (\markdownLastModified{}) +--- + + +<link href="https://afeld.github.io/emoji-css/emoji.css" rel="stylesheet" /> + +Introduction +============ +The [Markdown package][pkg] converts [markdown][] markup to \TeX{} commands. The +functionality is provided both as a Lua module and as plain \TeX{}, \LaTeX{}, and +\Hologo{ConTeXt} macro packages that can be used to directly typeset \TeX documents +containing markdown markup. Unlike other convertors, the Markdown package +makes it easy to redefine how each and every markdown element is rendered. +Creative abuse of the markdown syntax is encouraged. ;-) + + [markdown]: https://daringfireball.net/projects/markdown/basics/ + (Daring Fireball: Markdown Basics) + [pkg]: https://ctan.org/pkg/markdown + (CTAN: Package markdown) + + +This document is a user manual for the [Markdown package][pkg]. It provides +tutorials and code examples. For an in-depth description of the package +requirements, interfaces, and implementation, please refer to the [technical +documentation][techdoc]. + + [techdoc]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf + (A Markdown Interpreter for TeX) + + +Requirements +------------ + +The package requires a working \TeX{} distribution. [\TeX{} Live][tl] ≥ 2013 is +known to work and so are recent installation of [Mik\TeX{}][mik]. If you are +using a minimal installation of a \TeX{} distribution, please consult the +[technical documentation][techdoc] for a detailed list of required packages. + + [tl]: https://www.tug.org/texlive/ (TeX Live - TeX Users Group) + [mik]: https://miktex.org/ (Home - MiKTeXorg) + +Installation +------------ + +The package comes pre-installed with [\TeX{} Live][tl] ≥ 2016 and with recent +installations of [MikTeX][mik]. Unless you explicitly wish to use the latest +version of the package, you are encouraged to skip this step. + +To install the package, first download the package from the repository +using Git: +``` sh +git clone https://github.com/witiko/markdown +`````` +Next, enter the directory named `markdown` and interpret the file named +`markdown.ins` file using a Unicode-aware \TeX{} engine, such as XeTeX or +LuaTeX: +``` sh +cd markdown +luatex markdown.ins +`````` +This should produce the following files: + + * `markdown.lua`, the Lua module, + * `markdown-cli.lua`, the Lua command-line interface, + * `markdown.tex`, the plain \TeX{} macro package, + * `markdown.sty`, the \LaTeX{} package, and + * `t-markdown.tex`, the \Hologo{ConTeXt} module. + +### Local Installation + +To perform a local installation, place the above files into your \TeX{} +directory structure. This is generally where the individual files should be +placed: + + * `<TEXMF>/tex/luatex/markdown/markdown.lua` + * `<TEXMF>/scripts/markdown/markdown-cli.lua` + * `<TEXMF>/tex/generic/markdown/markdown.tex` + * `<TEXMF>/tex/latex/markdown/markdown.sty` + * `<TEXMF>/tex/context/third/markdown/t-markdown.tex` + +where `<TEXMF>` corresponds to a root of your \TeX{} distribution, such as +`/usr/share/texmf` and `~/texmf` on UN\*X systems or +`C:\Users\`\meta{Your username}`\texmf` on Windows systems. When in doubt, +consult the manual of your \TeX{} distribution. + +### Portable Installation + +Alternatively, you can also store the above files in the same folder as your +\TeX{} document and distribute them together. This way your document can be +portably typeset on legacy \TeX{} distributions. + + +First Document +-------------- + +In this section, we will take the necessary steps to typeset our first markdown +document in \TeX{}. This will serve as our first hands-on experience with the +package and also as a reassurance that the package has been correctly installed. + +### Using Lua + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input hello +\bye +``````` + +#### Using the Lua Module + +Using a text editor, create a text document named `hello.lua` with the +following content: +``` lua +#!/usr/bin/env texlua +local kpse = require("kpse") +kpse.set_program_name("luatex") +local markdown = require("markdown") +local convert = markdown.new() +print(convert("Hello *world*!")) +``````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua hello.lua > hello.tex +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text +“Hello *world*!” Invoking pdfTeX should have the same effect: +``` sh +texlua hello.lua > hello.tex +pdftex document.tex +`````` + +#### Using the Lua Command-Line Interface + +Using a text editor, create a text document named `hello.md` with the +following content: +``` md +Hello *world*! +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua ⟨CLI pathname⟩ -- hello.md hello.tex +luatex document.tex +`````` +where \meta{CLI pathname} corresponds to the location of the Lua CLI script file, +such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or +`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + + [Kpathsea]: https://tug.org/kpathsea/ (Kpathsea - TeX Users Group) + +A PDF document named `document.pdf` should be produced and contain the text “Hello +*world*!” Invoking pdfTeX should have the same effect: +``` sh +texlua ⟨CLI pathname⟩ -- hello.md hello.tex +pdftex document.tex +`````` + +### Using Plain \TeX{} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\markdownBegin +Hello *world*! +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text +“Hello *world*!” Invoking pdfTeX should have the same effect: +``` sh +pdftex --shell-escape document.tex +``````` + +### Using \LaTeX{} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage{markdown} +\begin{document} +\begin{markdown} +Hello *world*! +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text “Hello +*world*!” Invoking pdfTeX should have the same effect: +``` sh +pdflatex --shell-escape document.tex +`````` + +*** + +As the next step, try typesetting the example documents distributed along with +the Markdown package: +``` sh +git clone https://github.com/witiko/markdown +cd markdown/examples +lualatex latex.tex +`````` +A PDF document named `latex.pdf` should be produced. Open the text documents +`latex.tex` and `example.md` in a text editor to see how the example documents +are structured. Try changing the documents and typesetting them as follows: +``` sh +lualatex latex.tex +`````` +to see the effect of your changes. + +### Using \Hologo{ConTeXt} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext +\startmarkdown +Hello *world*! +\stopmarkdown +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text “Hello +*world*!” Invoking pdfTeX should have the same effect: +``` sh +texexec --passon=--shell-escape document.tex +`````` + +*** + +As the next step, try typesetting the example documents distributed along with +the Markdown package: +``` sh +git clone https://github.com/witiko/markdown +cd markdown/examples +context context.tex +`````` +A PDF document named `context.pdf` should be produced. Open the text documents +`context.tex` and `example.md` in a text editor to see how the example documents +are structured. Try changing the documents and typesetting them as follows: +``` sh +context context.tex +`````` +to see the effect of your changes. + +Examples +======== + +In this section, I will describe the individual parts of the Markdown package. +Each part will be shown by example, leaving the implementation details to the +[technical documentation][techdoc]. + + [techdoc]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf + (A Markdown Interpreter for \TeX{}) + +/markdown-interfaces.md +/markdown-options.md +/markdown-tokens.md + |