= Document Version Control with GIT :customcss: custom_css.css :imagesdir: img :title-slide-background-image: intro.jpg :background-image: normal.jpg :revealjs_theme: white :revealjs_margin: 0.1 :revealjs_width: 1920 :revealjs_height: 1200 == Before we start... image::nocloud.jpg[scaledwith=60%] == What is version control? [%step] * Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later. * Has existed for almost as long as writing has existed (ex. document version) * Today, the most capable (as well as complex) revision control systems are those used in software development. === Why? [%step] * Revert files back to a previous state * "Freeze" important versions of a document * Compare changes over time * Track progress of a project * See who modified something, and when === Modern version control systems [%step] * Remote backup of files * Powerful tool for collaboration == GIT [%step] * Developed by Linus Torvalds in 2005 * The linux Kernel: ** ~63000 files ** Roughly 15,600 developers from more than 1,400 companies === Characteristics [%step] * Free and open source * Distributed * Powerful and flexible * Learning curve can be steep === ! image:xkcd_git.png[] === How does it work? image::architecture.png[] === Installation https://git-scm.com/download/win Package managers are heavily recommended! === Creating a remote repository [%step] * register at the remote git server ** https://git.webhosting.rug.nl/ * create repository * add participants __ssh public keys__ * clone the repository in your machine === README and .gitignore Every repository should have these 2 files: * **README**: project description and useful information * **.gitignore**: special file indicating GIT which files are **not** to be tracked === workflow image::git_workflow.jpg[] === copying remote repository: clone * **git clone __repository__** * Clones the remote repository into the local one === staging changes (local) [%step] * **git add __files__** * Adds the changes into the local staging area === Saving changes: commit (local) [%step] * **git commit "message"** * Saves the changes in the staging area into the repository * Creates a "snapshot" of the current state of one or more files * A message describing the changes must be provided === history and revert (local) [%step] * **git log __files__** * returns a history of the file modifications * **git revert __commit__** * removes one or more commits from the local files, changes must be committed after === upload to remote repository: push [%step] * **git push** * Uploads the state of the local repository to the remote one === Download from remote repository: pull [%step] * **git pull** * Fetch and merges the documents in the remote repository into the local one * Merging files can generate conflicts, git will ask us to fix them and commit the changes === Branching image::version-control-flow.png[] === other (advanced) stuff * tags * partial reverts * change history * ... == Docs as code [%step] * Software is a small part of the documents a project must handle * Still, version control and remote collaboration are needed for all the documents * In the last years there is a big push of treating documents the same way as programming files ** https://www.writethedocs.org/guide/docs-as-code/ === Advantages [%step] * Working in plain text files (rather than binary file formats like Word) * Collaborating using version control such as git and GitHub * Storing docs in the same repositories as the programming code itself * Versioning docs through git tags/releases (rather than duplicating all the files to archive each release) * Generate other formats or websites without modifying the document === Just a little problem... [%step] * The most common document formats: word, pdf... are binary files * git (text based) doesn't work with them === Solutions? [%step] * Markup languages: * Markup languages are ways of annotating an electronic document. * Usually markup will either specify how something should be displayed or what something means. ** html, xml, latex... === Markup languages [%step] * Documents are written in plain text, then a program convert them into the final document * The same document can be used to generate files in other formats: latex, word, pdf or even slides * Formating is done by the computer, output is always consistent * Fast and light * Can be used in version control systems === Markup languages: Advanced features [%step] * Automatic generation of documents * Inline comments (not rendered in the final document) * Split one the document into several. Ex: main document, chapters and bibliography * Code executed and plots rendered __in__ the document === Latex [%step] * Extensively used for technical papers * Beautiful generated documents * Very powerful... * ...and very heavy * Setup and document customization are complex === Latex: example ---- \documentclass{article} \usepackage{graphicx} \begin{document} \title{Introduction to \LaTeX{}} \author{Author's Name} \maketitle \begin{abstract} The abstract text goes here. \end{abstract} \section{Introduction} Here is the text of your introduction. \begin{equation} \label{simple_equation} \alpha = \sqrt{ \beta } \end{equation} \subsection{Subsection Heading Here} Write your subsection text here. \begin{figure} \centering \includegraphics[width=3.0in]{myfigure} \caption{Simulation Results} \label{simulationfigure} \end{figure} \section{Conclusion} Write your conclusion here. \end{document} ---- === Latex: example II ---- \documentclass[12pt]{article} \usepackage{lingmacros} \usepackage{tree-dvips} \begin{document} \section*{Notes for My Paper} Don't forget to include examples of topicalization. They look like this: {\small \enumsentence{Topicalization from sentential subject:\\ \shortex{7}{a John$_i$ [a & kltukl & [el & {\bf l-}oltoir & er & ngii$_i$ & a Mary]]} { & {\bf R-}clear & {\sc comp} & {\bf IR}.{\sc 3s}-love & P & him & } {John, (it's) clear that Mary loves (him).}} } \subsection*{How to handle topicalization} I'll just assume a tree structure like (\ex{1}). {\small \enumsentence{Structure of A$'$ Projections:\\ [2ex] \begin{tabular}[t]{cccc} & \node{i}{CP}\\ [2ex] \node{ii}{Spec} & &\node{iii}{C$'$}\\ [2ex] &\node{iv}{C} & & \node{v}{SAgrP} \end{tabular} \nodeconnect{i}{ii} \nodeconnect{i}{iii} \nodeconnect{iii}{iv} \nodeconnect{iii}{v} } } \subsection*{Mood} Mood changes when there is a topic, as well as when there is WH-movement. \emph{Irrealis} is the mood when there is a non-subject topic or WH-phrase in Comp. \emph{Realis} is the mood when there is a subject topic or WH-phrase. \end{document} ---- === Latex alternative: Lyx [%step] * WYSIWYG latex editor * Documents are generated in .lyx, a subset of latex * Can be used together with version control * Provides, by default, templates for many of the biggest scientific journals === Lyx: example image::nvbqz.png[] === Lyx: example II image::lyxlilipond.png[] === Lightweight Markup languages [%step] * Also called Plain Text Markup or humane markup language * Provide a way of formating the document, while still being readable * Widely used on websites and code documentation === LML: current options * Markdown * reStructuredText (rst) * Asciidoc === Markdown [%step] * Created for minimal formating of web text * used **__everywhere__**: web, jupyter notebooks, r-markdown... * There is no standard, currently exist many flavours of it (github, commonmark, pandoc) * Originally not intended for documents, very limited * Different flavors and tools try to overcome this limitation ** (+ pandoc) === Markdown: example image::quicktourexample_small.png[] === Asciidoc [%step] * Developed for book creation. * Limited number of users * Standardized and extensible, great documentation * Lack of resources makes that bugs or request take time to be fixed === reStructuredText [%step] * Originally intended for python documentation * medium sized but very tech-savvy community * Syntax is a little different than the other two * Very powerful and extensible === Which one to use? * Notetaking: ** Markdown ** Asciidoc ** reStructuredText * Anything more serious: ** reStructuredText ** Latex/Lyx == Resources https://chocolatey.org ---- choco install git vscode pandoc ---- == Questions?