init documentation

documentation/README.md

@@ -0,0 +1,20 @@
+# Documentation de l'application
+
+## Contenu
+
+Le contenu de la documentation vit dans le wiki: https://gitea.champs-libres.be/champs-libres/biommap/wiki/_pages. Éditer ce contenu en ligne ou en utilisant le dépôt du wiki. 
+
+## Build
+
+Pour faire un beau pdf de cette documentation, on utilise pandoc avec un template. Pour lancer la commande:
+
+```bash
+documentation$ sh build.sh
+```
+
+Pour que pandoc trouve les fichiers, il faut leur indiquer un chemin valide. Ici, on présuppose que les dépots de ce projet de du wiki sont tels que:
+
+├── repo
+│   └── biommap-multi
+├── wiki
+│   └── biommap.wiki

documentation/build.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+cd $(dirname "${0}")
+
+pandoc --from markdown \
+     --number-sections \
+     --pdf-engine=xelatex \
+     -o documentation-biommap.pdf \
+     ../../../wiki/biommap.wiki/Gestion-des-utilisateurs.md \
+     ../../../wiki/biommap.wiki/Gestion-des-programmes.md \
+     ../../../wiki/biommap.wiki/Utilisation-API.md \  
+     ../../../wiki/biommap.wiki/Access-a-la-base-de-donnees.md \
+     ../../../wiki/biommap.wiki/Interaction-QGIS-BD.md \
+     ../../../wiki/biommap.wiki/Tableau-de-bord.md \
+     ../../../wiki/biommap.wiki/Editer-le-contenu-statique.md \
+     ../../../wiki/biommap.wiki/Image-programme.md \
+     ../../../wiki/biommap.wiki/Configurer-le-serveur-SMTP.md \
+     ../../../wiki/biommap.wiki/Import-requalification.md \

documentation/image-path.lua

@@ -0,0 +1,10 @@
+
+function fix_path (path)
+  return '../../sncf-qa.wiki/' .. path
+end
+
+function Image (element)
+  element.src = fix_path(element.src)
+  return element
+end
+

documentation/src/001-cover.md

@@ -0,0 +1,6 @@
+
+
+
+\includepdf{./src/cover.pdf}
+
+\newpage

documentation/src/002-toc.md

@@ -0,0 +1,18 @@
+```{=latex}
+
+\begingroup
+
+\hypersetup{linkcolor=linkcolortoc}
+
+\tableofcontents
+
+\listoffigures
+
+\listoftables
+
+\endgroup
+
+```
+
+
+

documentation/template.tex

@@ -0,0 +1,440 @@
+%!TEX TS-program = xelatex
+\documentclass[french, 10pt]{scrartcl}
+
+% The declaration of the document class:
+
+% The second line here, i.e.
+% \documentclass[12pt]{scrartcl}
+% is a standard LaTeX document class declaration:
+% we say what kind of document we are making in curly brackets,
+% and specify any options in square brackets.
+
+% (The previous line is a pseudo-comment, declaring that we will
+% use the special XeTeX machinery for its more extensive font list
+% and its use of unicode;
+% in general, LaTeX 'comments' like this one
+%  begin with % and end with a linebreak.)
+
+% Note that there we have nothing in the nature of a template;
+% it's just a standard bit of LaTeX pandoc will copy unaltered into the
+% LaTeX file it is writing.  But suppose you wrote something
+% more akin to the corresponding line in Pandoc's default
+% latex.template file, say:
+
+% \documentclass$if(fontsize)$[$fontsize$]$endif${scrartcl}
+
+% then you would have invented a 'variable', fontsize,
+% and could write things like
+
+% `markdown2pdf my.txt --xetex --variable=fontsize:12pt -o my.pdf` or
+% `pandoc -r markdown -w html my.txt -s --xetex --variable=fontsize:24pt -o my.tex`.
+
+% If we specified --variable-fontsize:12, then template substitution
+% would yield a LaTeX document beginning
+% \documentclass[12pt]{scrarcl}
+% which is just what we said anyway.
+% But we could also specify a different fontsize.
+
+% I don't use this `--variable=....`functionality myself;
+% I have a couple of basic templates I call with
+% `--template=whatever.template` which I can also
+% easily inspect to adjust things like font size as I please.
+
+% While we are discussing the declaration of the document class...
+% here's an alternative command for two column landscape,
+% not bad for some purposes. (If you strike the word 'landscape'
+% you will have two narrow newspaperlike
+% columns; scientists like that, because irrationality must
+% show itself somewhere):
+%\documentclass[12pt,twocolumn,landscape]{scrartcl}
+% Columns are too close together in LaTeX so we add this
+% `columnsep` command:
+%\setlength{\columnsep}{.5in}
+
+
+% I use the special 'komascript' article class "scrartcl"
+% reasons I can't entirely remember; I'm not sure it's that great.
+% One reason is the unimportant one that, like many classes,
+% it allows very big fonts which are convenient for booklet printing
+% in the idiotic American way by shrinking letterpaper pages.
+
+% the standard minimal LaTeX 'article' class declaration would be something like:
+
+% \documentclass[12pt]{article}
+
+% or for big type:
+
+% \documentclass[24pt]{extarticle}
+
+% but these restrict you to old-fashioned LaTeX materials.
+% Note that Kieran Healy uses the swank 'Memoir' class,
+% \documentclass[11pt,article,oneside]{memoir}
+% which might be worth a look.
+
+% Enough about the document class.
+
+% -- We are in swanky unicode, XeTeX land, and must now import these packages:
+\usepackage{fontspec,xltxtra,xunicode}
+% fontspec means we can specify pretty much any font.
+% Because we are using XeTeX material,
+% this template needs to be called with the `--xetex` flag.
+
+
+% Symbols:
+% Pandoc imports the extensive `amsmath` collection of symbols
+% for typesetting ordinary math.
+\usepackage{amsmath}
+% if you use exotic symbols you need to import specific packages, eg. for
+% electrical engineering diagrams, musical notation, exotic currency symbols,
+% the unspeakable rites of freemasonry etc.
+
+\usepackage{amssymb}
+
+\usepackage{eurosym}
+\usepackage{rotating}
+
+\usepackage[%
+    all,
+    defaultlines=3 % nombre minimum de lignes
+]{nowidow}
+
+% `babel`:
+% The `babel` package, among other things, lets you determine what
+% language you are using in a given stretch of text, so that typesetting
+% will go well. Here we specify that mostly, we are speaking English:
+% \usepackage[francais]{babel}
+%%% \usepackage[francais]{babel}
+\usepackage{babel}
+
+
+
+% Margins, etc:
+% the `geometry` package makes for convenient adjusting of margins, which is what
+% you asked about.  Of course it can do much more, even make coffee for you:
+\usepackage{geometry}
+\geometry{verbose,a4paper,tmargin=3cm,bmargin=5cm,lmargin=3cm,rmargin=5cm}
+% so if you just keep a copy of this template in the directory you are working in, you
+% can adjust the margins by going into this file and messing with the margins.
+% the syntax is very unforgiving, but permits 3cm and 2.5in and some other things.
+
+
+% Font:
+% Here I set my main font, which is an Apple Corporation Exclusive, golly.
+
+% \setmainfont{Hoefler Text}
+% \setromanfont[Mapping=tex-text,Contextuals={NoWordInitial,NoWordFinal,NoLineInitial,NoLineFinal},Ligatures={NoCommon}]{Hoefler Text}
+
+% Hoefler Text is okay, but note the long discussion of 'contextuals' which is necessary to cools off
+% some of its show-offy properties. (You can make your essay look like the
+% Declaration of Independence by specifying e.g. Ligatures={Rare} )
+% If you have a copy you might try it; as it is
+% I will comment it out and supply something more certain to be around:
+
+\setmainfont{Open Sans}
+
+% Properly one should specify a sanserif font and a monospace font
+% see e.g. the example of Kieran Healy:
+% \setromanfont[Mapping=tex-text,Numbers=OldStyle]{Minion Pro}
+% \setsansfont[Mapping=tex-text]{Minion Pro}
+% \setmonofont[Mapping=tex-text,Scale=0.8]{Pragmata}
+
+% But I hate sanserif fonts, and anyway there are defaults.
+
+
+
+% Heading styles:
+% These commands keep the koma system from making stupid sans serif section headings
+\setkomafont{title}{\rmfamily\mdseries\upshape\normalsize\color{clgreencolor}}
+\setkomafont{sectioning}{\rmfamily\mdseries\upshape\normalsize\color{clgreencolor}}
+\setkomafont{descriptionlabel}{\rmfamily\mdseries\upshape\normalsize\color{clgreencolor}}
+
+% Add some numbering to headings and a new line until heading level 6
+\usepackage{titlesec}
+\setcounter{secnumdepth}{6}
+\titleformat{\paragraph}{\normalfont\normalsize\color{clgreencolor}}{\theparagraph}{1em}{}
+\titlespacing*{\paragraph}{0pt}{3.25ex plus 1ex minus .2ex}{1.5ex plus .2ex}
+\titleformat{\subparagraph}{\normalfont\normalsize\color{clgreencolor}}{\thesubparagraph}{1em}{}
+\titlespacing*{\subparagraph}{0pt}{3.25ex plus 1ex minus .2ex}{1.5ex plus .2ex}
+
+% Hyphenation
+% We played with the tolerance to increase the hyphenation
+\tolerance=1000
+% list of words which need hyphenation
+\hyphenation{a-gen-da cha-que u-sa-ger}
+
+% I'm puzzled why I have this foonote speciality,
+% I wonder if it's part of my problem I've been having, but wont look
+% into it now.
+\usepackage[flushmargin]{footmisc}
+% \usepackage[hang,flushmargin]{footmisc}
+
+
+% So much for my personal template.
+
+
+% Everything that follows is copied from the pandoc default template:
+% I will interpolate a few comments, the comments that are in
+% the default template will be marked % --
+
+% Paragraph format:
+% Pandoc prefers unindented paragraphs in the European style:
+\setlength{\parindent}{0pt}
+%  ... with paragraph breaks marked by a slight lengthening of
+% the space between paragraphs:
+\setlength{\parskip}{6pt plus 2pt minus 1pt}
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+% Page format:
+% \pagestyle{plain}
+% The default `plain` pagestyle just numbers the pages,
+% whereas
+\pagestyle{empty}
+% would give you no numbering.
+% After one-million man-years of macro-composition,
+% there are also fancy pagestyles with much wilder options
+% for headers and footers, of course.
+
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+\fancyhf{}
+\rfoot{\color{clgraycolor}\thepage}
+\renewcommand{\headrulewidth}{0pt}
+\renewcommand{\footrulewidth}{0pt}
+
+
+% Footnotes
+% if you have code in your footnotes, the million macro march
+% kind of bumps into itself.
+% Pandoc, having just rendered your text into LaTeX,
+% knows whether the 'variable' `verbatim-in-note` is True, and
+% If it is, it asks for a  LaTeX package that solves the dilemma:
+$if(verbatim-in-note)$
+\usepackage{fancyvrb}
+$endif$
+
+% Lists formatting:
+% note sure what 'fancy enums' are; something to do with lists,
+% as the further comment suggests:
+$if(fancy-enums)$
+% -- Redefine labelwidth for lists; otherwise, the enumerate package will cause
+% -- markers to extend beyond the left margin.
+\makeatletter\AtBeginDocument{%
+  \renewcommand{\@listi}
+    {\setlength{\labelwidth}{4em}}
+}\makeatother
+\usepackage{enumerate}
+$endif$
+
+
+% Table formatting:
+% What if you make a table? -- Pandoc knows, of course, and
+% then declares that its  variable `table` is True and
+% imports a table package suitable to its pleasantly simple tables.
+% Needless to say infinitely   complicated tables are possible in
+% LaTeX with suitable packages. We are spared the temptation:
+
+$if(tables)$
+\usepackage{array}
+
+% Continuing on the topic of tables ... (we havent reached `endif`).
+% The commented out line below is in the default pandoc  latex.template.
+% Some unpleasantness with table formatting must be corrected.
+
+% -- This is needed because raggedright in table elements redefines \\:
+\newcommand{\PreserveBackslash}[1]{\let\temp=\\#1\let\\=\temp}
+\let\PBS=\PreserveBackslash
+
+$endif$
+
+
+% Subscripts:
+% Pandoc remembers whether you used subscripts, assigning True to
+% its `subscript` variable
+% It then needs to adopt a default with an incantation like this:
+$if(subscript)$
+\newcommand{\textsubscr}[1]{\ensuremath{_{\scriptsize\textrm{#1}}}}
+$endif$
+
+
+% Web-style links:
+
+% markdown inclines us to use links, since our texts can be made into html.
+% Why not have clickable blue links even in
+% learned, scientific, religious, juridical, poetical and other suchlike texts?
+% Never mind that they have been proven to destroy the nervous system!
+
+% First, what about the fact that links like http://example.com are
+% technically code and thus must not be broken across lines?
+% [breaklinks=true] to the rescue!
+
+% Nowadays LaTeX can handle all of this with another half million macros:
+
+\usepackage[dvipsnames]{xcolor}
+\definecolor{linkcolor}{RGB}{0, 136, 170}
+\definecolor{linkcolortoc}{RGB}{51,51,51} % same as text color
+\definecolor{clgreencolor}{RGB}{136,170,0}
+\definecolor{clgraycolor}{RGB}{51,51,51}
+\definecolor{cctpcolor}{RGB}{0,136,170}
+
+\usepackage[breaklinks=true]{hyperref}
+\hypersetup{colorlinks,%
+citecolor=linkcolor%
+filecolor=linkcolor,%
+linkcolor=linkcolor,
+urlcolor=linkcolor}
+$if(url)$
+\usepackage{url}
+$endif$
+
+
+% Images.
+% In ye olde LaTeX one could only import a limited range of image
+% types, e.g. the forgotten .eps files.  Or else one simply drew the image with suitable
+% commands and drawing packages.  Today we want to import .jpg files we make with
+% our smart phones or whatever:
+
+\usepackage{lscape}
+\usepackage{graphicx}
+\usepackage{pdfpages}
+
+%$if(graphics)$
+%\usepackage{graphicx}
+% -- We will generate all images so they have a width \maxwidth. This means
+% -- that they will get their normal width if they fit onto the page, but
+% -- are scaled down if they would overflow the margins.
+%\makeatletter
+%\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth
+%\else\Gin@nat@width\fi}
+%\makeatother
+%\let\Oldincludegraphics\includegraphics
+%\renewcommand{\includegraphics}[1]{\Oldincludegraphics[width=\maxwidth]{#1}}
+%$endif$
+
+
+\makeatletter
+\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
+\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi}
+\makeatother
+% Scale images if necessary, so that they will not overflow the page
+% margins by default, and it is still possible to overwrite the defaults
+% using explicit options in \includegraphics[width, height, ...]{}
+\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
+
+$if(csl-refs)$
+\newlength{\cslhangindent}
+\setlength{\cslhangindent}{1.5em}
+\newenvironment{cslreferences}%
+  {$if(csl-hanging-indent)$\setlength{\parindent}{0pt}%
+  \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces$endif$}%
+  {\par}
+$endif$
+
+% Section numbering.
+% Here again is a variable you can specify on the commandline
+% `markdown2pdf my.txt --number-sections --xetex --template=/wherever/this/is -o my.pdf`
+$if(numbersections)$
+$else$
+\setcounter{secnumdepth}{0}
+$endif$
+
+% Footnotes:
+% Wait, didn't we already discuss the crisis of code in footnotes?
+% Evidently the order of unfolding of macros required that
+% we import a package to deal with them earlier
+% and issue a command it defines now. (Or maybe that's not the reason;
+% very often the order does matter as the insane system of macro expansion
+% must take place by stages.)
+$if(verbatim-in-note)$
+\VerbatimFootnotes % -- allows verbatim text in footnotes
+$endif$
+
+% Other stuff you specify on the command line:
+% You can include stuff for the header from a file specified on the command line;
+% I've never done this, but that stuff will go here:
+$for(header-includes)$
+$header-includes$
+$endfor$
+
+% Title, authors, date.
+% If you specified title authors and date at the start of
+% your pandoc-markdown file, pandoc knows the 'values' of the
+% variables: title authors date and fills them in.
+
+$if(title)$
+\title{$title$}
+$endif$
+\author{$for(author)$$author$$sep$\\$endfor$}
+$if(date)$
+\date{$date$}
+$endif$
+
+% Package tcolorbox for making nice boxes around some texts
+\usepackage{tcolorbox}
+
+
+% Adaptations pour la SNCF
+
+% créer un toc jusqu'au niveau 4
+\setcounter{tocdepth}{3}
+
+% Eviter l'erreur "Environment Shaded undefined"
+$if(highlighting-macros)$
+$highlighting-macros$
+$endif$
+
+% missing environment longtable
+\usepackage{booktabs}
+\usepackage{longtable}
+
+
+
+% At last:
+% The document itself!:
+
+% After filling in all these blanks above, or erasing them
+% where they are not needed, Pandoc has finished writing the
+% famous LaTeX *preamble* for your document.
+% Now comes the all-important command \begin{document}
+% which as you can see, will be paired with an \end{document} at the end.
+% Pandoc knows whether you have a title, and has already
+% specified what it is; if so, it demands that the title be rendered.
+% Pandoc knows whether you want a table of contents, you
+% specify this on the command line.
+% Then, after fiddling with alignments, there comes the real
+% business: pandoc slaps its rendering of your text in the place of
+% the variable `body`
+% It then concludes the document it has been writing.
+
+\color{clgraycolor}
+\begin{document}
+
+
+$if(title)$
+\maketitle
+$endif$
+
+
+%\begingroup
+%\hypersetup{linkcolor=linkcolortoc}
+
+%\tableofcontents
+
+%\listoffigures
+
+%\listoftables
+
+%\endgroup
+
+
+$if(alignment)$
+\begin{$alignment$}
+$endif$
+
+$body$
+
+%$if(alignment)$
+\end{$alignment$}
+$endif$
+
+
+\end{document}