Early feedback on revised GLM manual

[JesseTG]

@Groovounet I'm in the process of converting the documentation to LaTeX, instead of the DOCX file that exists now. I proposed this in the gli repo, but I'm doing the GLM manual first, so let's bring the discussion here.

I've attached the LaTeX for the first section and its PDF output, for your perusal.

Overleaf Link

glm-manual.pdf I've only converted the first section thus far. I haven't managed to put images inside it yet, but it's on the to-do list.

\documentclass{scrartcl}

% Packages
% ---
\usepackage[utf8]{inputenc} % Unicode support (Umlauts etc.)
\usepackage{hyperref} % Add a link to your document
\usepackage{graphicx} % Add pictures to your document
\usepackage{xcolor} % Allow verbatim text in macro arguments
\usepackage{cprotect}
\usepackage{minted} % Source code formatting and highlighting

\setlength{\parindent}{0em}
\setlength{\parskip}{1em}

\definecolor{beige}{rgb}{0.95,0.95,0.92}
\hypersetup{
    colorlinks=false,
    linkbordercolor=red,
    pdfborderstyle={/S/U/W 1},
    pdfauthor=Christophe Riccio,
    pdftitle=GLM Manual
}

\usemintedstyle{borland}
\newminted{cpp}{linenos, bgcolor=beige}
\newminted{glsl}{linenos, bgcolor=beige}

\begin{document}
% Set up the maketitle command
\author{Christophe Riccio}
\subtitle{Version 0.9.7}

\title{GLM Manual}
\date{\today{}} % You can remove \today{} and type a date manually

\maketitle{} % Generates title

\pagebreak{}

\section*{Licensing}

\subsection*{\hypertarget{happybunny}{The Happy Bunny License (Modified MIT License)}}

\copyright{} 2008 - 2015 G-Truc Creation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Restrictions: By making use of the Software for military purposes, you choose to make a Bunny unhappy.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

\pagebreak{}

\subsection*{\hypertarget{mit}{The MIT License}}
\copyright{} 2008 - 2015 G-Truc Creation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

\pagebreak{}

\addcontentsline{toc}{section}{Introduction}
\tableofcontents{}

\pagebreak{}

\section*{Introduction}

OpenGL Mathematics (GLM) is a C++ mathematics library for graphics C++ programs based on the \href{http://www.opengl.org/registry/}{OpenGL Shading Language} (GLSL) specifications.

GLM provides classes and functions designed and implemented with the same naming conventions and functionalities than GLSL so that when a programmer knows GLSL, he knows GLM as well which makes it really easy to use.

This project isn't limited to GLSL features. An extension system, based on the GLSL extension conventions, provides extended capabilities: matrix transformations, quaternions, data packing, random numbers, noise, etc...

This library works perfectly with \href{http://www.opengl.org}{OpenGL} but it also ensures interoperability with other third party libraries and SDK. It is a good candidate for software rendering (ray-tracing/rasterisation), image processing, physic simulations and any other development context that requires a simple and convenient mathematics library.

GLM is written in C++98, but can take advantage of C++11 when supported by the compiler. It is a platform independent library with no dependencies and it officially supports the following compilers:

\begin{itemize}
  \item \href{https://developer.apple.com/Library/mac/documentation/CompilerTools/Conceptual/LLVMCompilerOverview/index.html}{Apple Clang} 4.0 and higher
  \item \href{http://gcc.gnu.org/}{GCC} 4.2 and higher
  \item \href{https://software.intel.com/en-us/intel-compilers}{Intel C++ Composer} XE 2013 and higher
  \item \href{http://llvm.org/}{LLVM} 3.0 and higher
  \item \href{http://www.visualstudio.com/}{Visual C++} 2010 and higher
  \item \href{https://developer.nvidia.com/about-cuda}{CUDA} 4.0 and higher (experimental)
  \item Any conforming C++98 or C++11 compiler
\end{itemize}

The source code and the documentation, including this manual, are licensed under the \hyperlink{happybunny}{Happy Bunny License (Modified MIT)} and the \hyperlink{mit}{MIT License}.
Thanks for contributing to the project by submitting reports for bugs and feature requests. Any feedback is welcome at glm@g-truc.net.

\section{Getting started}
\subsection{Setup}
GLM is a header-only library. Hence, there is nothing to build to use it. To use GLM, a programmer only has to include \verb|<glm/glm.hpp>| in his program. This include provides all the GLSL features implemented by GLM.

Core GLM features can be included individually to reduce compilation times.

\begin{itemize}
\item \verb|<glm/vec2.hpp>|: \verb|vec2|, \verb|bvec2|, \verb|dvec2|, \verb|ivec2| and \verb|uvec2|
\item \verb|<glm/vec3.hpp>|: \verb|vec3|, \verb|bvec3|, \verb|dvec3|, \verb|ivec3| and \verb|uvec3|
\item \verb|<glm/vec4.hpp>|: \verb|vec4|, \verb|bvec4|, \verb|dvec4|, \verb|ivec4| and \verb|uvec4|
\item \verb|<glm/mat2x2.hpp>|: \verb|mat2|, \verb|dmat2|
\item \verb|<glm/mat2x3.hpp>|: \verb|mat2x3|, \verb|dmat2x3|
\item \verb|<glm/mat2x4.hpp>|: \verb|mat2x4|, \verb|dmat2x4|
\item \verb|<glm/mat3x2.hpp>|: \verb|mat3x2|, \verb|dmat3x2|
\item \verb|<glm/mat3x3.hpp>|: \verb|mat3|, \verb|dmat3|
\item \verb|<glm/mat3x4.hpp>|: \verb|mat3x4|, \verb|dmat3x4|
\item \verb|<glm/mat4x2.hpp>|: \verb|mat4x2|, \verb|dmat4x2|
\item \verb|<glm/mat4x3.hpp>|: \verb|mat4x3|, \verb|dmat4x3|
\item \verb|<glm/mat4x4.hpp>|: \verb|mat4|, \verb|dmat4|
\item \verb|<glm/common.hpp>|: all the GLSL common functions
\item \verb|<glm/exponential.hpp>|: all the GLSL exponential functions
\item \verb|<glm/geometry.hpp>|: all the GLSL geometry functions
\item \verb|<glm/integer.hpp>|: all the GLSL integer functions
\item \verb|<glm/matrix.hpp>|: all the GLSL matrix functions
\item \verb|<glm/packing.hpp>|: all the GLSL packing functions
\item \verb|<glm/trigonometric.hpp>|: all the GLSL trigonometric functions
\item \verb|<glm/vector_relational.hpp>|: all the GLSL vector relational functions
\end{itemize}

\subsection{Faster program compilation}
GLM is a header-only library that heavily uses C++ templates, which may significantly increase the compile time for files that use GLM. Hence, GLM functionality should be included only by files that actually use it.

To further reduce compilation time, GLM 0.9.5 introduced forward declarations of all types through the header \verb|<glm/fwd.hpp>|.

\begin{cppcode}
// Header file
#include <glm/fwd.hpp>
\end{cppcode}

\begin{cppcode}
// Source file
#include <glm/glm.hpp>
\end{cppcode}

\subsection{Example usage of core GLM}

\begin{cppcode}
// Include GLM core features
#include <glm/vec3.hpp>
#include <glm/vec4.hpp>
#include <glm/mat4x4.hpp>

// Include GLM extensions
#include <glm/gtc/matrix_transform.hpp>

using glm::vec2;
using glm::vec3;
using glm::mat4;

mat4 transform(
  vec2 const & Orientation, 
  vec3 const & Translate,
  vec2 const & Up)
{
  mat4 Projection = glm::perspective(45.0f, 4.0f/3.0f, 0.1f, 100.0f);
  mat4 ViewTranslate = glm::translate(mat4(1.0f), Translate);
  mat4 ViewRotateX = glm::rotate(ViewTranslate, Orientation.y, Up);
  mat4 View = glm::rotate(ViewRotateX, Orientation.x, Up);
  mat4 Model = mat4(1.0f);

  return Projection * View * Model;
}
\end{cppcode}

\subsection{Dependencies}

When \verb|<glm/glm.hpp>| is included, GLM will provide all standard GLSL features.

GLM does not depend on external libraries or external headers such as \verb|gl.h|, \cprotect{\href{http://www.opengl.org/registry/api/GL/glcorearb.h}}{\verb|glcorearb.h|}, \verb|gl3.h|, \verb|glu.h| or \verb|windows.h|. However, if \verb|<boost/static_assert.hpp>| is included, then  \href{http://www.boost.org/doc/libs/release/libs/static_assert/}{Boost.StaticAssert}  will be used to provide compile-time errors.  Otherwise, if using a C++11 compiler, the standard \verb|static_assert| will be used instead. If neither is available, GLM will use its own implementation of \verb|static_assert|.

\end{document}

Is this something you'd want me to move forward with?

[JesseTG]

Looks like by "not famous to be easy", you were talking about actually compiling it. Writing is isn't too difficult, but compiling it is a pain. I'll make sure to set that up okay, too. Do you use Linux, per chance?

[Groovounet]

I barely use Linux. Only once in a while. Even if I was using Linux, the solution needs to be cross platform or potentially cross platform so that I could make it works on Windows, MacOSX and Linux.

[JesseTG]

Gotcha. Looks like it's just a matter of installing some LaTeX packages, then. I've got the PDF itself mostly done, my next step will be adding that build step.

[JesseTG]

Question. How do you want me to implement building? To build the manual will require various LaTeX packages to be installed; should the CMake file presume that they already are, or should I try to fetch them remotely as well?

[Groovounet]

Well first, I think simplicity is really important so I would say the goal would be to build in a single step. Having a dedicated custom target, build it and it's done.

This said, platforms / ecosystems have different cultures and this needs to be considered. I think for MacOSX and Windows, anything should be in the repository. It would be nice to have a submodule for that but once again... Github has a serious limitation. :(

On Linux, well, I am pretty much unfit for this culture. Each time, I have to install packages and spent forever to deal with the dependant packages to the package I actually want.

So can building be simple for the users? It sounds like your experience shows that it's not a piece of cake. Can CMake make it a piece of cake?

[JesseTG]

Yes, there are CMake scripts for automating LaTeX builds, and I'm experimenting with one. And it is easy to make the manual a custom target.

As for installing LaTeX itself, I'm pretty sure there are convenient installers for it on non-Linux platforms (on Linux, apt-get, yum, etc. are the convenient installers). I'll look into it.

[Groovounet]

Thinking about it, I think it's good enough to let install LaTeX. What I am not sure is, is it the only tool to install? If yes, I think just a "clean" error message (LaTeX missing, needs to be install, see there for more information about building GLM manual).

If it's actually a pill of mess tools, then I don't know, it depends.

[JesseTG]

Yeah, CMake actually has a built-in FindLatex.cmake for just such a scenario. And I'm including another UseLatex.cmake to make it easier (you'll see it when I send my PR).

As for installation, this website lists the exact distributions the user can download. I just need to see which packages (features, macros, etc.) said LaTeX bundles include.

[JesseTG]

Now that I've actually made the PR and pushed my work, let's move discussion to #458