some streamlining, opens #140 #138

_site.yml

@@ -8,6 +8,13 @@ navbar:
   - icon: fa-code
     text: Stack
     href: stack.html
+  - icon: fa-cogs
+    text: More
+    menu:
+    - text: Bibliography Management
+      href: biblio.html
+    - text: Going Linux
+      href: linux.html
   - icon: fa-chalkboard-teacher
     text: Instructor
     href: http://www.maxheld.de

biblio.Rmd

@@ -0,0 +1,117 @@
+---
+title: "Bibliography Setup"
+author:
+  - name: "Thomas Roppelt"
+    affiliation: "Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU)"
+  - name: "Maximilian Held"
+    affiliation: "Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU)"
+date: "`r format(file.info('biblio.Rmd')$mtime, '%d %B, %Y')`"
+bibliography: library.bib
+---
+
+```{r setup, echo = FALSE}
+knitr::opts_chunk$set(echo = FALSE)
+```
+
+Bibliography managers (also known as reference management software) are important to keep all the literature you work with well organized.
+These programs help you keep bibliographic metadata (author, year, etc.) in a small database, sometimes also including links to full-text PDFs or your own annotations.
+
+This page will help you understand pros and cons of different bibliography managers as well as help you set up Zotero, a free and open-source bibliography manager.
+
+
+## Comparison
+
+There are many different bibliography managers available, including Citavi, Colwiz, EndNote, JabRef, Mendeley, Zotero and ZoteroBib.
+Any reference manager that is capable of exporting clean `.bib` files, plain text files adhering to the [BibTex format](https://de.wikipedia.org/wiki/BibTeX), will work with a pandoc-based toolchain (such as ours).
+
+However, you may want to consider using one of the open source reference managers.
+Reference collections are an investment (of your time) you might want to use for a long time (years or even decades), and the best way to ensure that is to a) use an open source program with b) an easy way to get out your data if you want to use a different tool.
+
+Of the named software, only JabRef, Zotero and ZoteroBib are free and open source.
+For a detailed feature comparison, you may want to look [here (german)](https://ub.fau.de/schreiben-publizieren/literaturverwaltung/) or [here (english)](https://en.wikipedia.org/wiki/Comparison_of_reference_management_software).
+While the following paragraphs will cover Zotero, please feel free to use any of the other open source bibliography managers.
+
+
+## Zotero setup
+
+To get started with Zotero, there are some components that should be set up:
+
+
+### [Zotero](https://www.zotero.org/)
+
+*Linux:
+   Best way is to use the included package manager.
+   Most likely you can find it there.
+
+*Mac:
+   Download from the Zotero website or using [homebrew](brew.sh) `brew cask install zotero`.
+
+*Windows:
+   Best way is to install via chocolatey package manager.
+   Run `choco install zotero` in the command line.
+
+*Alternative way for all supported platforms:
+   Download and install via the [Zotero website](https://www.zotero.org/)
+
+
+### [Better BibTex Add-on](https://retorque.re/zotero-better-bibtex/installation/)
+
+This add-on makes it easier to work with plain-text based authoring formats such as Markdown and LaTeX.
+You should [install](https://retorque.re/zotero-better-bibtex/installation/) it *after* installing Zotero.
+
+
+### Automatically Export `.bib`
+
+Zotero maintains only *one* database for your entire system or Zotero user account.
+This makes a lot of sense, because you'll often want to *reuse* references across different projects.
+
+However, remember that every *single* project (say, a git repository with some `* rmd`s) will require it's *own* exported copy of that system-wide database, or a subset thereof.
+This is because *pandoc*, or any other command-line conversion program (such as *rmarkdown*, or *LaTeX*) will expect the references in a plain text `.bib` file, *not* the database that Zotero is using.
+Programs other than Zotero actually cannot read or write to that database (which is a good thing).
+Additionally, if you're using git (as you should) with some CI/CD, *all* files necessary to render a project to output formats *must be present in that project directory*.
+
+This problem is easily solved by *exporting* your entire library (or parts of it, if you like), to `.bib` using the above Better BibTex add-on.
+Get to the below menu by clicking File > Export Library, and then save the file to your project root.
+
+```{r zotero_export, fig.cap="Zotero Export", out.width='100%'}
+knitr::include_graphics(path = "img/zotero-export.png")
+```
+
+Happily you can *also* have Zotero automatically *refresh* this `.bib`, whenever your (system wide) bibliography changes.
+If you're using git, this will cause diffs from your `.bib`, which you'll have to add and commit by hand.
+
+If you're adventurous, you can also set up Better BibTex to *automatically* [add, commit and push these changes for you](https://retorque.re/zotero-better-bibtex/push-and-pull/), but this isn't recommended.
+Git commits should always be deliberate, human interactions, not scripted artefacts.
+
+
+### Zotero Pickers
+
+There are also various pickers (or autocomplete plugins) that will make it easier for you to insert citekeys in your text editor of choice.
+
+- [Zotero picker Addon for Atom](https://atom.io/packages/zotero-picker)
+
+
+### [Zotero Connector for Your Browser](https://www.zotero.org/download/connectors) (optional, recommended)
+
+This enables you to add the websites or PDFs you view in your browser directly to your bibliography. 
+The connector will extract and add as much of the metadata as possible.
+
+
+## Using Zotero
+
+This should be pretty straightforward. 
+To learn about the available functions, have a look at the [Zotero Quick Start Guide](https://www.zotero.org/support/quick_start_guide)
+
+
+## Rendering Your Bibliography
+
+Pandoc and other command-line text conversion tools will accept your `.bib` file as an additional input, pass that to one of several bibliography *generation* programs (such as BibTex, Pandoc Citeproc or Biber) and insert the results into your output formats of choice.
+
+For example, in pandoc, you might run
+
+```
+pandoc homework.md --bibliography=mybib.bib -o .\Outputs\output.html
+```
+
+where `--bibliography=mybib.bib` specifies that you want to use your `mybib.bib`, expected at the project root.
+This would be the file that you'd have exported from Zotero.

index.Rmd

@@ -639,6 +639,8 @@ You should also study the [RStudio Cloud guide](https://rstudio.cloud/learn/guid
 
 ### Moving to Linux
 
+<a class="btn btn-info" href="linux.html" role="button">Learn More</a>
+
 Installation and usage may be easier on Unix-compatible operating systems, including macOS and Linux.
 Getting Windows to play nicely with open source software can be harder, and some convenient system utilities (such as a package manager) are often missing.
 It *is* technically possible to use most, if not all, of the tools above on Windows, but they may behave slightly differently, and supporting them may be more involved.

setup_linux.Rmd → linux.Rmd

@@ -3,7 +3,7 @@ title: "Linux Setup"
 author:
   name: "Thomas Roppelt"
   affiliation: "Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU)"
-date: "`r format(Sys.time(), '%d %B, %Y')`"
+date: "`r format(file.info('linux.Rmd')$mtime, '%d %B, %Y')`"
 bibliography: library.bib
 ---
 
@@ -12,21 +12,27 @@ knitr::opts_chunk$set(echo = FALSE)
 ```
 
 ## Linux distributions (distros)
+
 Looking at Linux distributions and deciding for one can be a daunting task for newcomers.
 Here are some key differences between distributions:
 
+
 ### Release Model
+
 The release model decides how frequently updates reach your system.
 Frequent smaller updates are called rolling release.
 If only very big updates are released, it is a point or major release model.
 Also, distros can either focus on well-tested and known software, while others focus on the bleeding edge.
 
+
 ### Basis and forks
+
 This is where a lot of names are being dropped, e.g. Arch, Debian, RedHat.
 While it is not important to remember every name in the beginning, it is important to understand the concept.
 If a distribution derives from another distribution, it is called a fork (similar to the git concept).
 The basis of a distribution defines e.g. which system tools you have available and thereby also which software packages you can install in general.
 [See the linux distribution timeline](https://upload.wikimedia.org/wikipedia/commons/1/1b/Linux_Distribution_Timeline.svg) to make out which distro forked from where.
+
 Example:
 Manjaro Linux is based on Arch Linux.
 Therefore, it is a fork of Arch.
@@ -38,12 +44,16 @@ Related distros have similar tools and may install the same packages.
 So it is basically not possible to install Debian packages in Manjaro, since they are not related.
 Luckily there are almost always ways to work around such limitations in case you need a specific program.
 
+
 ### Design principles
+
 Each distro has its own principles.
 Some try to be as beginner-friendly as possible (e.g. Ubuntu) and take a lot of choices from the user, while others encourage users to really learn the system (e.g. Arch).
 Pick a distro and read a little about it to find one that you believe suits your needs.
 
+
 ### User interface
+
 This is might be the most surprising aspect about linux and it is a big difference to other operating systems.
 Looking at a distro, you see its Desktop Environment.
 In the Linux world, this is just like another package you can install or remove anytime.
@@ -52,22 +62,38 @@ So if you find a distro that has everything you need, but does not look pleasing
 Summing it up, there are quite substantial differences between the linux distributions.
 Since it is impossible to understand every linux distro in the necessary detail to make an informed decision, think about what you really need and then just get started.
 
+
 ### Resources
+
 Here are some resources to help you with the first steps.
-- [DistroWatch](http://distrowatch.org/). This page has all the distros and sorts them by popularity. You will find key information about the distros and useful user ratings here.
+
+- [DistroWatch](http://distrowatch.org/). 
+  This page has all the distros and sorts them by popularity. You will find key information about the distros and useful user ratings here.
 - [A linux beginner's guide article](https://www.pcworld.com/article/2918397/how-to-get-started-with-linux-a-beginners-guide.html)
 - [Overview about the best linux distros 2019](https://linoxide.com/linux-how-to/what-are-best-linux-distros/)
 - [Choose the best linux distro for your need](https://www.lifewire.com/choose-best-linux-distro-for-needs-2201172)
 - [Choose the best linux distro for beginners in 2019](https://techlog360.com/linux-distro-beginners/)
--[Great and easy-to-understand comparison between several distros](https://haydenjames.io/best-linux-distro/)
+- [Great and easy-to-understand comparison between several distros](https://haydenjames.io/best-linux-distro/)
+
 
 ## Tools
-Software should ideally be installed via the package manager that comes with your distro.  Using package managers is more secure and faster than downloading the software from some website. So package managers should always be the starting point for installing software.
-Some examples for package managers are [pacman](https://wiki.archlinux.org/index.php/Pacman), [octopi](https://wiki.manjaro.org/index.php?title=Octopi), [APT](https://wiki.ubuntuusers.de/APT/) and [homebrew](https://brew.sh/)
+
+Software should ideally be installed via the package manager that comes with your distro. 
+Using package managers is more secure and faster than downloading the software from some website. 
+So package managers should always be the starting point for installing software.
+Some examples for package managers are:
+
+- [pacman](https://wiki.archlinux.org/index.php/Pacman)
+- [octopi](https://wiki.manjaro.org/index.php?title=Octopi)
+- [APT](https://wiki.ubuntuusers.de/APT/)
+- [homebrew](https://brew.sh/) (which now works for macOS *and* Linux)
+
 
 ### Backup
+
 Backups are essential.
 No matter if a system error was caused by an update or misconfiguration by the user, having a backup can save a lot of hassle.
+
   - Software: *Timeshift*, [Link to GitHub Project](https://github.com/teejee2008/timeshift)
   - Functionality: Timeshift makes it easy to create and restore backups.
   By default it saves the system configuration, but it can also be configured to backup configuration and all your files.
@@ -83,10 +109,14 @@ No matter if a system error was caused by an update or misconfiguration by the u
   A rescue system can be e.g. a USB-Drive or even a disk with a bootable linux distribution on it.
   Instructions how to create a bootable medium can be found on the website of most distros.
 
+
 ### Keyboard shortcuts
+
 CTRL+ALT+F1 to F12 switch virtual consoles.
 This means that with e.g. CTRL+ALT+F3 you get no graphical user interface, but only bash.
 This can help in combination with bash restoring of backups if your system breaks.
 
+
 ### Resources
+
 [Cheat sheet for essential linux commands](http://www.unixguide.net/linux/linuxshortcuts.shtml)

stack.Rmd

@@ -466,6 +466,8 @@ We will use it to learn the branch and pull-request model.
 - [Comparing Commits accross time](https://help.github.com/articles/comparing-commits-across-time/)
 
 
+## Technical & Scientific Authoring {#sciwri}
+
 ### Document Conversion {#conversion}
 
 <i class="far fa-file-alt fa-3x fa-pull-left"></i> <a class="btn btn-info" href="https://pandoc.org" role="button">Install Pandoc</a>
@@ -508,9 +510,9 @@ Still, it is important to learn some of the basics of LaTeX to use it programmat
 ### Bibliography Management {#bib}
 
 <a class="btn btn-info" href="https://github.com/jgm/pandoc-citeproc" role="button">Install Pandoc Citeproc</a>
-<a class="btn btn-default" href="https://en.wikipedia.org/wiki/Comparison_of_reference_management_software" role="button">Install a Bibliography Manager of Your Choice</a>
+<a class="btn btn-default" href="biblio.html" role="button">Install Zotero</a>
 
-Bibliography management is *not* the focus of this class.
+Bibliography management is *not* the focus of this class, but you can learn more about it [here](biblio.html).
 
 It is also one of those tools, where there is no strong reason to standardize on any one program, so as long as the bibliography manager exports to one of the formats [that pandoc can ingest](https://pandoc.org/MANUAL.html#citations).