Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

Contributing

This document is for people who want to contribute.

Software

Here is the required software you need to contribute:

git - we use git for version control. If you have never used git before, I suggest reading Pro Git by Scott Chacon.
Some text editor. Emacs is particularly good for LaTeX, although it does have quite a bit of a learning curve.
- If you use Emacs, you may be interested in Magit. Magit is an Emacs interface to git, which, unsurprisingly, is much more pleasant than the git command line interface.

TeXLive

TeX is the markup language in which LYSA is written, so you need a TeX distribution to compile it. Note that if you are only interested in the PDF file, we publish regular builds here. The target TeX distribution is TeXLive, but it probably works on other TeX distributions. Below you can find installation instructions for select operating systems. If you don't see your operating system there, but know what software is needed, please add it and send a pull request.

Credit: xkcd

Arch

To get the bare minimum for the English version:

# pacman -S texlive-core texlive-latexextra texlive-bibtexextra texlive-fontsextra

Alternatively, you can just get every TeXLive package under the sun so you don't have to worry about having the right package every time we change something.

# pacman -S texlive-most

Gentoo

Warning: this will spawn a ton of processes, but will make the build a lot faster (from several hours to a few minutes). If your memory is precious, use -av instead of -jav.

# emerge -jav dev-tex/biblatex dev-texlive/texlive-latexrecommended dev-texlive/texlive-xetex

Ubuntu 12.04

# apt-get install biblatex texlive texlive-latex-extra texlive-bibtex-extra texlive-xetex texlive-math-extra texlive-latex3

Ubuntu 14.04

# apt-get install texlive-latex-extra texlive-bibtex-extra texlive-xetex texlive-latex3 texlive-fonts-recommended

Content

If you add new content to the book, such as a new chapter, or a substantial portion of text, please feel free to add yourself to the \author field in book/lysa.ltx (you don't have to, if you don't want to). If you merely suggested changes, or made a number of trivial changes, add yourself to the \editors field.

Graphs and Code

For the time being, you can generate a graph with anything you want, as long as it's open-source. You just have to include the code to generate the graph (in case we want to change it). I recommend Sage.
We might use Idris as an interactive proof assistant. The other candidates are Coq and Agda.
Turing-complete code examples should be written in Haskell.
- If you want to learn Haskell, please see bitemyapp's guide.
- If you don't want to add code examples, you don't need to learn Haskell.
- If you do want to add code examples, but don't want to learn Haskell, you can write your code in something else, and ask someone in the channel to translate it for you. That said, there is no guarantee someone will be willing to do so, though.

Git

The git repo is hosted on GitLab. If you have a GitLab account, the easiest thing to do is to fork the repo with GitLab, and then submit a merge request. If you have a GitHub account, you can log into GitLab with your GitHub account.

If you don't use GitLab, and don't want to make a GitLab account, then you can host your git repository elsewhere (such as Gitorious or GitHub), and then email pharpend <pharpend2@gmail.com> with a link to the repository. It's recommended that you copy & paste the diff into the email, because pharpend will be less grumpy if you do. To generate the diff, run

git remote add upstream git@gitlab.com:lysa/lysa.git
git remote update
git diff upstream/master

Committing

Try to make sure that each commit only contains one change. It's a lot less annoying to have to sift through 20 commits each with 1 different change than 1 commit with 20 different changes. If the change is difficult to summarize in one line, then you should probably split up the commit with git add -p.

When in doubt, follow the Erlang OTP Git Commit Guide.

Sources

The sources are listed in the book/bibliographies/lysa.bib file. Here are some suggested readings:

Abstract Algebra, from Wikibooks
Foundations of Analysis, by Edmund Landau
The Foundations of Analysis, by Larry Clifton
Algebra, by Thomas W. Hungerford
Linear Algebra Done Right, by Sheldon Axler
Set Theory, by Thomas Jech
Foundations of Analysis, by Joe Taylor

contributing.md 6.0 KB Permalink Verlauf Originalformat