diff --git a/documentation/README.md b/documentation/README.md new file mode 100644 index 0000000..6f21af8 --- /dev/null +++ b/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 diff --git a/documentation/build.sh b/documentation/build.sh new file mode 100755 index 0000000..1925b74 --- /dev/null +++ b/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 \ diff --git a/documentation/documentation-biommap.pdf b/documentation/documentation-biommap.pdf new file mode 100644 index 0000000..ac6700e Binary files /dev/null and b/documentation/documentation-biommap.pdf differ diff --git a/documentation/image-path.lua b/documentation/image-path.lua new file mode 100644 index 0000000..376f4d1 --- /dev/null +++ b/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 + diff --git a/documentation/src/001-cover.md b/documentation/src/001-cover.md new file mode 100644 index 0000000..7d2433a --- /dev/null +++ b/documentation/src/001-cover.md @@ -0,0 +1,6 @@ + + + +\includepdf{./src/cover.pdf} + +\newpage \ No newline at end of file diff --git a/documentation/src/002-toc.md b/documentation/src/002-toc.md new file mode 100644 index 0000000..a72b97a --- /dev/null +++ b/documentation/src/002-toc.md @@ -0,0 +1,18 @@ +```{=latex} + +\begingroup + +\hypersetup{linkcolor=linkcolortoc} + +\tableofcontents + +\listoffigures + +\listoftables + +\endgroup + +``` + + + diff --git a/documentation/src/cover.pdf b/documentation/src/cover.pdf new file mode 100644 index 0000000..7ca7c59 Binary files /dev/null and b/documentation/src/cover.pdf differ diff --git a/documentation/src/cover.svg b/documentation/src/cover.svg new file mode 100644 index 0000000..3d512b2 --- /dev/null +++ b/documentation/src/cover.svg @@ -0,0 +1,261 @@ + + + +image/svg+xmlCourriel : info@champs-libres.coop Téléphone : +32 81 13 69 17 Adresse : Rue Nanon, 98 5000 Namur, Belgique + + + + +Documentationtechnique + + + + +Champs-Libres - atelier cartographique + + + + + + + + + + + + + + + + + + + + + +Libres + + +Champs + + +Développement d'un outil d'assurance qualité des données OpenStreetMapVersion 14 décembre 2020 \ No newline at end of file diff --git a/documentation/template.tex b/documentation/template.tex new file mode 100644 index 0000000..e521466 --- /dev/null +++ b/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}