AUTHORS
=======
* H. Kienle (See source file for contact information.)
* Kai Mertens (See source file for contact information.)
___
(See source file for copyright information.)
Copying
=======
Zerocat Label Documentation ships copyrighted work.
See [AUTHORS][] for a list of people which have contributed.
Zerocat Label Documentation is free software. It makes use of free software
approved licenses only and should be freely distributable:
* [GNU General Public License][GNU GPL]
* [GNU Free Documentation License][GNU FDL]
* [CreativeCommons Attribution-ShareAlike License][CC BY-SA]
Authorship, copyright and license information may be provided in more
detail on a per-folder and/or per-file basis. Check the sources.
Please report a bug if you find the distribution hindered by any
obstacle. See [Zerocat Website][] for contact information.
___
[AUTHORS]: ../doc/AUTHORS.md
[GNU-GPL]: ../doc/GNU-GPL.md
[GNU-FDL]: ../doc/GNU-FDL.md
[CC BY-SA]: https://creativecommons.org/licenses/by-sa/4.0/
[Zerocat Website]: http://www.zerocat.org/
___
(See source file for copyright information.)
README
======
Project Goal
------------
The goal of Zerocat Label Documentation is to provide you with some
general information about the label itself, in opposite to project
specific infos.
Paths
-----
All paths within this document are relative in respect to the original
location of this source file, which is located in the project’s `doc/`
folder.
Prerequisites
-------------
If you are on GNU Guix System, create your environment:
guix environment --pure -m ../guix/manifest.scm
Otherwise, check the manifest file and install the listed packages with
the package manager of your distro. Adapt package names as required.
Make Documentation
------------------
To build the documentation, type:
make -C ../doc
To get a full list of available targets, type:
make -C ../doc help
Note we are currently migrating the documentation system. For the time
being, you might still generate the obsolete documentation using
doxygen:
cd ../doc-doxygen
make
Contributing
------------
Once you have contributed, add yourself to [AUTHORS][].
### Documentation Files
In order to enrich this documentation:
* add more `*.md` markdown text files to `../doc/`
* maintain copyright footer within new files
* add more folders, images or other files
... and adapt `../doc/Makefile` to produce nice output.
In case more tools are needed, don't forget to update
`../guix/manifest.scm`.
### Shell Scripts
If you intend to write shell scripts, use this skeleton to make them
work for GNU Guix:
#!/bin/sh
# Re-exec if we are not using Bash or are using Bash in POSIX mode.
if [ -z "$BASH" ] || [ "$BASH" = "/bin/sh" ]; then
bash=`command -v bash`
if [ -z "$bash" ]; then
echo "Couldn't find Bash, sorry!"
exit 1
else
exec "$bash" "$0" "$@"
fi
fi
# We're using Bash now.
set -o errexit
set -o nounset
set -o pipefail
# Your code goes here ...
### Code Files
This project may ship non-code, graphic sources, which cannot be
covered by the standard GNU General Public License. The license header
for code source files thus has been adapted accordingly, please use it
if you intend to write code:
Zerocat Label Documentation --- General infos
Copyright (C) 2021 Authors of Zerocat Label Documentation
This file is part of Zerocat Label Documentation.
This file is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License,
or (at your option) any later version.
This file is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with Zerocat Label Documentation.
If not, see <http://www.gnu.org/licenses/>.
Version Tags
------------
Within this project’s git repository, versions are tagged according to
the following pattern:
v<major>.<minor>.<revision>
* major – The resulting product is a major change or upgrade.
* minor – Additional functionality or new features are introduced.
* revision – Bug fixes, minor changes, graphical stuff.
___
[AUTHORS]: ../doc/AUTHORS.md
[Git]: https://git-scm.com/
[Zerocat Team]: http://www.zerocat.org/team.html
___
(See source file for copyright information.)
Zerocat Git Repositories
========================
Server Information
------------------
The domain names “www.zerocat.org” and “www.zerocat.de” are both pointing
to our server.
The server’s IP address is “185.242.113.29”.
The Git Gatekeeper
------------------
Zerocat’s git repositories are hosted by user `git`, and access control
is managed by a gatekeeper. A client can talk to the server’s
gatekeeper using SSH authentication, thus the generation of an
SSH keypair might be required.
### Prerequisites
Please make sure the following programs are availbale on your machine:
* `git` – Distributed version control system
* `openssh` – Client and server for the secure shell (ssh) protocol
Get yourself prepared by studying the output of:
* `man git-clone`
* `man ssh`
* `man ssh-keygen`
* `man ssh-config`
### Generate SSH Keypair
You can generate a new pair of SSH keys by running:
$ ssh-keygen \
-t rsa \
-b 4096 \
-C "" \
-f ~/.ssh/my-zerocat-ssh-id
Adapt settings to your needs. This will create a pair of keys – a
secret and a public one, i.e.: `~/.ssh/my-zerocat-ssh-id` and
`~/.ssh/my-zerocat-ssh-id.pub`
### Access via SSH-Key Authentication
In case your public SSH key has been deposited on the server, you
might talk to the gatekeeper over `ssh` and use the `info` command to get
a full overview of repositories and of your current access permissions:
$ ssh -2 -4 \
-i ~/.ssh/my-zerocat-ssh-id \
-p 32323 \
git@zerocat.org info
Note, as default, this would look up your `~/.ssh/id_rsa` file for
authentication, but you specified an individual identity file with the
`-i` option.
The gatekeeper offers some more commands, like:
* `help` (lists all available commands)
* `desc` (describes a specified repository)
Example:
$ ssh -2 -4 \
-i ~/.ssh/my-zerocat-ssh-id \
-p 32323 \
git@zerocat.org desc zerocat/projects/chipflasher
Note the server’s SSH Daemon is listening to port 32323 only.
### SSH Configuration File
The `ssh` client supports a configuration file named `~/.ssh/config`,
where you can manually bundle the required credentials to make things
easier to deal with, e.g.:
~/.ssh/config
--------------------------------------
host git-gatekeeper-zerocat
user git
hostname 185.242.113.29
port 32323
identityfile ~/.ssh/my-zerocat-ssh-id
addressfamily inet
Getting Started with 'Git Clone'
--------------------------------
### Private Repositories
$ git clone ssh://git-gatekeeper-zerocat/zerocat/projects/<project-name>
This will download the repository and sets `origin` to the same used
URL.
Now change into the newly created project folder and run `git log`
to see the project’s history.
### Public Repositories
Some repositories are publically accessible without authentication, i.e.:
* zerocat/projects/doc
* zerocat/projects/chipflasher
* zerocat/projects/coreboot-machines
* zerocat/projects/ps2-keyboard
* zerocat/projects/turning-hook
Cloning can therefor be done using the git protocol:
$ git clone git://zerocat.org/zerocat/projects/chipflasher
These public projects are promoted on our website: [www.zerocat.org][]
___
[www.zerocat.org]: http://www.zerocat.org/
___
(See source file for copyright information.)
Zerocat Git Usage
=================
Resources
---------
- Pro Git, Apress, 2nd edition, 2014
- <https://www.git-scm.com/book/en/v2>
- <https://www.git-scm.com/book/en/v2/Git-Branching-Remote-Branches#Deleting-Remote-Branches>
- <https://www.git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging>
- Git from the Bottom Up
- <https://jwiegley.github.io/git-from-the-bottom-up/>
- <http://newartisans.com/2008/04/git-from-the-bottom-up/>
- The Thing About Git, explains `git add --patch`
- <http://2ndscale.com/rtomayko/2008/the-thing-about-git>
- fetch/merge vs. pull
- <http://longair.net/blog/2009/04/16/git-fetch-and-merge/>
- gitk example run-through: Use gitk to understand git – merge and rebase
- <https://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git/>
- <https://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git-merge-and-rebase/>
- How to Write good Commit Messages
- <http://chris.beams.io/posts/git-commit/>
Configuration Template
----------------------
To ease collaboration, we would like to suggest the follwing settings
for your Git Configuration. You might place them in the `.git/config`
file of a project’s root folder, or – as an alternative – in your
global Git Configuration File `~/.gitconfig`.
~~~
[user]
name = <your name>
email = <your email address>
signingkey = <your PGP key ID>
[commit]
gpgsign = true
[core]
editor = nano
[alias]
# git log:
# l: log, g: --graph --color,
# c: --oneline, s: --pretty=short, f: --pretty=format,
# a: --all
lg = log --graph --color --decorate
lga = log --graph --color --decorate --all
lgc = log --graph --color --decorate --oneline
lgca = log --graph --color --decorate --oneline --all
lgs = log --graph --color --decorate --pretty=short
lgsa = log --graph --color --decorate --pretty=short --all
lgf = log --graph --color --decorate --pretty=format:'%C(auto) %h %d %G? %aN %s'
lgfa = log --graph --color --decorate --pretty=format:'%C(auto) %h %d %G? %aN %s' --all
# git diff:
check = diff --check
[push]
default = simple
~~~
The `[alias]` section now contains some aliases for `git log`, and
commands like `git lgca` should help you to get a quick overview of the
repository’s history. In case you need to verify authors, use `git
lgfa` instead.
To see whether your changes would introduce misplaced white-space, run
`git check` as an alias of `git diff --check`.
When using GPG-signed commits as suggested by `gpgsign = true` in
section `[commit]`, please check your `~/.gnupg/gpg-agent.conf` to have
a line available which specifies a pinentry program, i.e.:
~~~
pinentry-program /usr/bin/pinentry
~~~
Some Useful Invokes
-------------------
They mostly come from reading the "Pro Git" book.
# get started with a repository
git init
git clone
# show changes
git diff
git diff --cached # same as `--staged`
git status
git status -uno
git status -s
# commit changes
git commit -am "<commit message>" # fast commit of *all* changes
git add <file>
git add --patch
git commit -m "<commit message>" # fast commit of *staged* changes
git commit --no-status
git commit --uno
# rename or delete files
git mv
git rm
# work with branches
git branch # list local branches, mark current one
git branch <a-new-branch> # create a new local branch, but stay on current one
git checkout -b <a-new-branch> # create *and* checkout a new local branch
git stash # push away current changes which might hinder you to checkout elsewhere
git stash pop # pop previously pushed changes
## set up new-branch to track remote new-branch
git checkout new-branch
## delete branch upstream
git push origin :my-obsolete-branch
## delete local copies of already deleted upstream branches
git fetch --prune # refers to all local copies of remotes
# show history of commits
git log
git log --pretty=format:"%h %an %s" --graph
git log --abbrev-commit --pretty=oneline --graph
git log --abbrev-commit --pretty=medium
git log -p -2
git log --follow <filename>
# git configuration
git config --list
git config --add format.pretty oneline
git remote -v
git difftool --tool-help
# show differences between commits/ branches/ tags/ etc.
# in detail...: git diff <from> <to>
git diff master documentation
# in short...: git diff --stat <from> <to>
git diff --stat <refspec> HEAD # you can omit 'HEAD'
Roles and Responsibilities
--------------------------
- Project Initiator and Maintainer...
- performs the merges into `master` or asks contributors to do so
- pushes branches as a call for contribution
- Contributors...
- announce their branch and its purpose in advance by mail
- don't forget to delete their branches in origin when the merge is done
- or explain shortly why the branch is kept
Workflow: Contributing via branching
------------------------------------
### Contributor:
git branch my-new-branch ; git checkout my-new-branch
git add new-file-in-branch
...
git commit
...
git push origin my-new-branch # Announce this via email
git branch --set-upstream-to=origin/my-new-branch my-new-branch
...
...
git push origin --delete my-new-branch # We are done with the branch, delete on server
### Others:
git pull origin # Now new remote branches are visible
git checkout my-new-branch # Sets up tracking branch (git branch -vv)
...
...
git branch --delete my-new-branch # We are done with the branch, delete locally
### Project Maintainer:
git checkout master ; git merge my-new-branch
Tools
-----
- gitk (comes with git)
Beyond Git
----------
- git-annex: <https://git-annex.branchable.com/>
___
(See source file for copyright information.)
(See source file for copyright information.)
Zerocat Markdown Usage
======================
The Original Markdown
---------------------
The (original) language is described here:
<https://daringfireball.net/projects/markdown/>
Plenty of variants and extensions are around:
- Doxygen: <http://www.stack.nl/~dimitri/doxygen/manual/markdown.html>
- GitHub: <https://help.github.com/categories/writing-on-github/>
- kramdown: <http://kramdown.gettalong.org/syntax.html>
Implementations
---------------
There a many different translators available.
### CommonMark's cmark
This is a C/C++ implementation with an extensive test suite:
<https://github.com/jgm/cmark>
To run it:
cmark in.md > out.html
### discount
To get something quickly up and running for openSUSE there is the
"discount" package available:
- <https://github.com/Orc/discount>
- <https://software.opensuse.org/package/discount>
- <http://www.pell.portland.or.us/~orc/Code/discount/>
Emacs mode
----------
It consists of a single lisp file `markdown-mode.el` that needs to be
found in the Emacs load path. (Does not work with XEmacs.)
<https://github.com/defunkt/markdown-mode>
Markdown Styleguide
-------------------
### Goals
This is supposed to be as brief as possible. The goal is to capture a
minimal subset of Markdown that is sufficent for our needs and is
understood widely by various tools.
### Styleguide
How to write markdown files, some guides:
* Wrap headlines with *two empty lines* before *and* after.
* Justify paragraphs, break long lines.
* Indent/justify text of list items if spread over multiple lines.
* Maintain two spaces at the end of line to force a line break.
* Delete trailing, single spaces.
* Put words that require to be escaped into backticks: `<value>`
* Set paths into code style font, i.e.: `../doc/`
* Use three characters to mark a horizontal rule: `___`
* Mark *italic font* with one asteric: `*italic*`
* Mark **bold font** with two asterics: `**bold**`
* Mark ***bold italic font*** with three asterics: `***bold italic***`
* Maintain a copyright footer, introduced with an horizontal rule.
Maintain copyright notes without introducing spaces, but with two
spaces inbetween and at the end in order to force a line break:
___
Copyright (C) 2021, 2022 Somebody <Email-Address>
... License Note ...
### Other Styleguides
We can take inspiration from others, for example
- <http://www.cirosantilli.com/markdown-style-guide/>
- <http://tirania.org/blog/archive/2014/Sep-30.html>
___
(See source file for copyright information.)
(See source file for copyright information.)
Documentation for “Zerocat Label Documentation” as of Tue, 26 Oct 2021 10:06:29 +0200
Repository: git://zerocat.org/zerocat/projects/doc
Version: v0.1.7-45-2e60aa6
Branch: master