Skip to content

Latest commit

 

History

History
118 lines (95 loc) · 3.92 KB

README.md

File metadata and controls

118 lines (95 loc) · 3.92 KB
Raw

The Haxe Manual

Build Status

Contributions / Information for authors

For contributions please edit the .tex files in in HaxeManual/. The .md files are generated from it.

The manual is structured using these commands:
\chapter{name}, \section{name}, \subsection{name}, \paragraph{name}

Chapter, section and subsection require a \label{id} so a URL can be determined. It should not contain any spaces.

Formatting:

  • Bold text: \emph{Emphasized text}
  • Code: \expr{haxe code}, \type{MyClass}, \ic{other code}
  • Since: \since{3.1.0}
  • Definition blockquote: \define{Definition name}{define-definition}{Definition description}
  • Trivia blockquote: \trivia{About Trivia}{This is trivia}
  • Internal Links: \tref{Link name}{chapter-section-id} or \Fullref{chapter-section-id}
  • External Links: \href{https://haxe.org}{Haxe Website}

Block of external code (preferred since those are tested):

\haxe{assets/Color.hx}

Block of code, if haxe code:

\begin{lstlisting}
trace("Haxe is great!");
\end{lstlisting}

Block of code, if not haxe code:

\lang{xml}\begin{lstlisting}
<do>
	<until x="4" />
</do>
\end{lstlisting}

Do not put a new line between \lang{} and \begin{lstlisting}, use \lang{none} if the block shouldn't be highlighted. Unordered list:

\begin{itemize}
	\item What is your name?
	\item How old are you?
\end{itemize}

Definition list:

\begin{description}
	\item[Coffee] Black hot drink
	\item[Milk] White cold drink
\end{description}

Finally, if you want to contribute to the Haxe Manual but cannot be arsed to use .tex, just write it in any other format and we'll port it.

Generating Markdown

Go to convert/ and run convert.hxml to generate the markdown which will be exported to the output-folder. For quick testing disable the .mobi generation.

You can use the following defines when using convert for additional features.

  • -D compileEnv Generates images from custom LaTeX environments too complex for Markdown (specifically the flowchart environment at the time of writing). Skips already existing images.
  • -D recompileEnv Generates images even if they already exist at their destination (most useful for convert development).
  • -D keepEnvPDF Keeps the LaTeX generated PDF files. They're placed next to generated images with the same name.
  • -D keepEnvTemp Keeps the generated temporary directory for LaTeX compilation. Useful for debugging / development purposes.

PDF generation

To rebuild the .pdf from the command line, go to HaxeManual/ and run latexmk -xelatex HaxeManual.tex. A recent version of TeX Live should provide latexmk and all needed packages and their dependencies:

  • xelatex
  • cleveref
  • courier
  • framed
  • fullpage
  • geometry
  • graphicx
  • hyperref
  • listings
  • palatino
  • tikz, tkz-euclide, tkz-qtree
  • todonotes
  • underscore
  • xcolor

Requirements for compileEnv

At the time of writing, compileEnv depends on the following.

  • xelatex being in path. TeX Live 2013 version should be sufficient. Used to compile custom LaTeX environment snippets to PDF.
  • mudraw being in path. This is a part of MuPDF. Used for rendering PDF to a PNG image.
  • pandoc being in path. Used for generating .epub file.
  • ebook-convert being in path. This is a part of calibre. Used for converting .epub to .mobi.
  • Source Sans Pro and Source Code Pro fonts being installed.