Skip to content
Snippets Groups Projects
Commit 0825b42e authored by Rainer Perske's avatar Rainer Perske
Browse files

Markdown-Hinweise ergänzt

parent 8df13a7f
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 102 additions and 67 deletions
README.md
+ 102
− 67
View file @ 0825b42e
......@@ -20,35 +20,45 @@ und (Pseudo-) Gruppen können im IT-Portal diese Zustimmung erteilen,
einsehen oder widerrufen.
Solange die Anzahl der Datenverarbeitungssysteme sich in Grenzen hält,
sollten alle Dateien im Hauptverzeichnis liegen (ansonsten wird der "/"
sollten alle Dateien im Hauptverzeichnis liegen (ansonsten wird der „/“
Teil dieses Namens xxxxxxxx.)
Markdown
--------
Die Einbindung ins IT-Portal erfolgt mit Parsedown <https://parsedown.org> ohne
Extensions, diese versteht die Markdown-Variante „GitHub Flavored Markdown“
Die Einbindung ins IT-Portal erfolgt mit Parsedown
<https://parsedown.org> ohne Extensions, diese versteht die
Markdown-Variante „GitHub Flavored Markdown“
<https://github.github.com/gfm/>.
Da an anderen Stellen andere Markdown-Parser zum Einsatz kommen, sollte auf
Erweiterungen möglichst verzichtet werden: Tabellen ja, Fußnoten nein.
Da an anderen Stellen andere Markdown-Parser zum Einsatz kommen, sollte
auf Erweiterungen möglichst verzichtet werden: Tabellen ja, Fußnoten
nein.
Markdown-Syntax-Übersicht:
<https://www.heise.de/mac-and-i/downloads/65/1/1/6/7/1/0/3/Markdown-CheatSheet-Deutsch.pdf>
(ohne Fußnoten, aber mit Tabellen)
Da die Texte nicht nur von verschiedenen Markdown-Parsern verstanden werden
müssen, sondern zusätzlich auch als Plaintext in E-Mails eingebettet werden
und dort gut aussehen sollen, sollten folgende Empfehlungen eingehalten werden:
Da die Texte nicht nur von verschiedenen Markdown-Parsern verstanden
werden müssen, sondern zusätzlich auch als Plaintext in E-Mails
eingebettet werden und dort gut aussehen sollen, sollten folgende
Empfehlungen eingehalten werden:
* Die Zeilenlänge sollte weniger als 80 Zeichen betragen. (Der in zivgitlab
eingebaute Editor markiert die 80 Spalten mit einer vertikalen Linie.)
* Die Zeilenlänge sollte weniger als 72 Zeichen betragen. (Der in
zivgitlab eingebaute Editor markiert die 80 Spalten mit einer
vertikalen Linie.)
* Auf Tabulatorzeichen sollte verzichtet werden.
* Absätze aller Art sollten durch Leerzeilen getrennt werden, auch wenn es
nicht syntaktisch notwendig ist.
* Absätze aller Art sollten durch Leerzeilen getrennt werden, auch
wenn es nicht syntaktisch notwendig ist.
* Vor Überschriften (und nur dort) sollte die Leerzeile verdoppelt
werden.
* Überschriften sollten durch Unterstreichung (nicht `#`) markiert
werden.
* Einrückungen sollten immer genau vier Zeichen tief sein.
......@@ -56,17 +66,35 @@ und dort gut aussehen sollen, sollten folgende Empfehlungen eingehalten werden:
`␣␣*␣` oder `␣␣+␣` oder `␣␣-␣` oder `␣␣>␣`
* Geordnete Aufzählungen sollten linksbündig korrekt durchnummeriert sein:
* Geordnete Aufzählungen sollten linksbündig korrekt durchnummeriert
sein:
`1.␣␣` bis `9.␣␣` und `1 0.␣ . _` bis `9 9 . _`
`1.␣␣` bis `9.␣␣` und `10.␣` bis `99.␣`
* Überschriften sollten durch Unterstreichung (nicht `#`) markiert werden.
* Vor Überschriften (und nur dort) sollte die Leerzeile verdoppelt werden.
* URLs und E-Mail-Adressen sollten explizit in `<...>` eingeschlossen
werden.
* Hyperlinks und Bilder funktionieren in E-Mails nicht und sollten
nicht genutzt werden. Stattdessen kann man die URL in den Text
einbetten.
* Weniger ist mehr: Auf Text-Auszeichnungen für Fett- und
Kursivschrift kann oft verzichtet werden.
* Wörtlich einzutippende Textteile sollten in Backtick-Zeichen
eingeschlossen werden.
* „Indented Code Blocks“ sind meist besser als „Fenced Code Blocks“.
* URLs und E-Mail-Adressen sollten explizit in `<...>` eingeschlossen werden.
* Tabellen sollten auch links und rechts das Pipe-Symbol nutzen und
auch im Quelltext sauber ausgerichtet sein.
* Weniger ist mehr: Auf Text-Auszeichnungen kann oft verzichtet werden.
* Im Fließtext sollten korrekte „deutsche“ oder “englische”
Anführungszeichen – und auch korrekte Binde- und Gedankenstriche –
verwendet werden. (Es kann nicht schaden, sich einmal im
Rechtschreibduden die Richtlinien zum Schriftsatz anzuschauen.)
Der Quelltext dieser README.md hält sich an diese Regeln.
Hinweise zur Bearbeitung auf der Kommandozeile
......@@ -75,60 +103,63 @@ Hinweise zur Bearbeitung auf der Kommandozeile
Diese Hinweise sind für mich als absoluten Git(lab)-Neuling gedacht.
Repository klonen:
```
cd && mkdir work
cd && cd work && git clone git@zivgitlab.uni-muenster.de:wwuit-sys/zustimmungen-zur-datenverarbeitung.git
cd zustimmungen-zur-datenverarbeitung
git config user.name "Rainer Perske"
git config user.email "rainer.perske@uni-muenster.de"
```
cd && mkdir work
cd && cd work && git clone git@zivgitlab.uni-muenster.de:wwuit-sys/zustimmungen-zur-datenverarbeitung.git
cd zustimmungen-zur-datenverarbeitung
git config user.name "Rainer Perske"
git config user.email "rainer.perske@uni-muenster.de"
Jetzt alles bearbeiten.
Änderungen festschreiben und hochladen:
```
git add *.md *.access
git commit -m "xxxxxxxx"
git push
git add *.md *.access
git commit -m "xxxxxxxx"
git push
cd && rm -rf work
```
cd && rm -rf work
Für das IT-Portal benötigte Zugriffe
------------------------------------
Hashwert des letzten Commit zu einer Datei herausfinden:
```
git rev-list -1 HEAD neuanmeldung.de.md
```
git rev-list -1 HEAD neuanmeldung.de.md
Oder, wenn man nicht klonen will (2574 ist die Project ID von
wwuit-sys/zustimmungen-zur-datenverarbeitung):
```
curl -s -H 'PRIVATE-TOKEN: xxxxx' 'https://zivgitlab.uni-muenster.de/api/v4/projects/2574/repository/files/neuanmeldung.de.md?ref=master'
```
Das Ergebnis ist JSON und enthält in "last_commit_id" den benötigten Hashwert
und in "content" den Base64-kodierten Dateiinhalt.
Dann kann man auf drei verschiedene Weisen später immer wieder dieselbe Version
abrufen:
```
curl -s -H 'PRIVATE-TOKEN: xxxxx' 'https://zivgitlab.uni-muenster.de/api/v4/projects/2574/repository/files/neuanmeldung.de.md?ref=HASHWERT
curl -s -H 'PRIVATE-TOKEN: xxxxx' 'https://zivgitlab.uni-muenster.de/api/v4/projects/2574/repository/files/neuanmeldung.de.md/raw?ref=HASHWERT
curl -s https://zivgitlab.uni-muenster.de/wwuit-sys/zustimmungen-zur-datenverarbeitung/-/raw/HASHWERT/neuanmeldung.de.md
```
curl -s -H 'PRIVATE-TOKEN: xxxxx' 'https://zivgitlab.uni-muenster.de/api/v4/projects/2574/repository/files/neuanmeldung.de.md?ref=master'
Das Ergebnis ist JSON und enthält in „last_commit_id“ den benötigten
Hashwert und in „content“ den Base64-kodierten Dateiinhalt.
Dann kann man auf drei verschiedene Weisen später immer wieder dieselbe
Version abrufen:
curl -s -H 'PRIVATE-TOKEN: xxxxx' \
'https://zivgitlab.uni-muenster.de/api/v4/projects/2574/repository/files/neuanmeldung.de.md?ref=HASHWERT'
curl -s -H 'PRIVATE-TOKEN: xxxxx' \
'https://zivgitlab.uni-muenster.de/api/v4/projects/2574/repository/files/neuanmeldung.de.md/raw?ref=HASHWERT'
curl -s \
'https://zivgitlab.uni-muenster.de/wwuit-sys/zustimmungen-zur-datenverarbeitung/-/raw/HASHWERT/neuanmeldung.de.md'
Die erste Zeile liefert JSON wie oben, die beiden anderen den nackten
Dateiinhalt. In den ersten beiden Zeilen kann man anstelle von HASHWERT das
Wort "master" einsetzen, dann wird die neueste Version geholt.
Dateiinhalt. In den ersten beiden Zeilen kann man anstelle von HASHWERT
das Wort „master“ einsetzen, dann wird die neueste Version geholt.
Das "Personal Access Token" für die API-Zugriffe kann auf
<https://zivgitlab.uni-muenster.de/profile/personal_access_tokens> eingerichtet
werden. Benötigt werden die Kreuzchen bei api und read_repository.
Das „Personal Access Token“ für die API-Zugriffe kann auf
<https://zivgitlab.uni-muenster.de/profile/personal_access_tokens>
eingerichtet werden. Benötigt werden die Kreuzchen bei api und
read_repository.
Die dritte Zeile funktioniert nur, wenn das Repository "public" ist. In diesem
Fall kann aber auch bei der ersten und zweite Zeile die Angabe des Token
entfallen.
Die dritte Zeile funktioniert nur, wenn das Repository „public“ ist. In
diesem Fall kann aber auch bei der ersten und zweite Zeile die Angabe
des Token entfallen.
Die zweite Zeile hat gegenüber der dritten Zeile den Vorteil, dass nicht der
Repository-Name (wwuit-sys/zustimmungen-zur-datenverarbeitung), sondern mit der
......@@ -137,26 +168,30 @@ Das Projekt kann also umbenannt werden, ohne dass gespeicherte URLs ungueltig
werden.
Eine JSON-Liste aller Dateien im Projekt kann man so abholen:
```
curl -s -H 'PRIVATE-TOKEN: xxxxx' \
'https://zivgitlab.uni-muenster.de/api/v4/projects/2574/repository/tree'
```
curl -s -H 'PRIVATE-TOKEN: xxxxx' \
'https://zivgitlab.uni-muenster.de/api/v4/projects/2574/repository/tree'
API-Zugriff zum Eintragen und Abfragen von Zustimmungen
-------------------------------------------------------
```
curl -s -F secret=xxxxx -F nutzer=xxxxx -F dienst=xxxxx -F action=xxxxx \
-F url=xxxxx https://it-portal.uni-muenster.de/consent/
```
curl -s -F secret=xxxxx -F nutzer=xxxxx -F dienst=xxxxx -F action=xxxxx \
-F url=xxxxx https://it-portal.uni-muenster.de/consent/
* secret = vereinbartes Shared Secret, dieses identifiziert den Abfragenden
und legt fest, welche Dienste er sehen und bearbeiten darf.
* nutzer = Nutzerangabe (local@scope); scope kann sein:
* eine Internetdomain (FQDN)
* die Entity-ID eines Identity Providers in <...>
- eine Internetdomain (FQDN)
- die Entity-ID eines Identity Providers in <...>
* dienst = vereinbarte Kennung des genutzten Dienstes
* action = get oder set oder del (Abfragen, Erteilen, Widerrufen)
* url = (nur bei set) die *permanente* URL der konkreten Version der
Erklaerung, der der Nutzer zugestimmt hat (also keine URL, die immer auf die
neueste Version verweist!)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment