Beiträge zu “asciidoctor”

Git: Erste Babyschritte mit Branches und Mergen

Warnung: Das sind die Aufzeichnungen einen Anfängers und keinesfalls als “Best Practise” geeigent. Use at your own risk**

Aber vielleicht hilft es ja auch mal anderen die ersten Schritte zu wagen.

Bisher benutze ich Git nur zu einfachen Versionierung in einem Entwicklungszweig. An Branches und Merges habe ich mich bisher nicht getraut. Es gab noch keinen echten Anwendungsfall.

Folgendes Ziel möchte ich erreichen. Ich habe eine Webseite die ich kopieren und in verschiedenen Situationen einsetzen möchte (die Lizenz lässt das zu). Für die unterschiedlichen Bereiche sollen sowohl textuelle als auch farbliche Anpassungen geschehen. Nun möchte ich natürlich Änderungen die ich im Hauptzeig vollziehe auch automatisch in die verschiedenen anderen Versionen übernehmen.

Git bietet die Funktion von Branches. Die sind zwar eigentlich nicht für so einen Fall vorgesehen da man Branches dazu benutzen soll um Entwicklungen später wieder in den Hauptzweig überführen zu können. Das ist in meinem Fall zwar nicht der Fall aber trotzdem scheint mir dies aktuell die einfachste Möglichkeit zu sein. Wenn man es richtig machen würde sollte man wohl eher mit anderen Ansätzen arbeiten.

Wir haben also ein Git Repository. Von diesem Repository erstellen ich einen Branch

  git checkout -b rc-its

Wechseln zwischen den Branches geht mit

 git checkout master
 git checkout rc-its

In welchem Branch ich bin und welche Branches es gibt findet man so:

 git branch -a      
 * master
   rc-its
   remotes/origin/master

Wenn ich also auf dem Master Änderungen durchführe (z.B. ein sed-Befehl )

  git:(master) find ./ -type f -exec sed -i -e 's/BITS/ITS-RC/g' {} \;

und diese dann einchecke

 git:(master) ✗ git commit * -m "bits nach rc-its in allen dokumenten "
 git:(master) git push  

So kann ich die jetzt durch einen Wechsel des Branches und einen anschließenden Merge aus dem Master in den anderen Zweig übernehmen.

git:(master) git checkout rc-its    
git:(rc-its) git merge master

Um jetzt noch den Branch auf gitlab zu pflegen

 git:(rc-its) git push -u origin rc-its

Wenn ich jetzt im Branch ein anderes Logo haben möchte dann tauschen ich das einfach aus. Danach sehen wir

  git status
  Auf Branch rc-its
  Ihr Branch ist auf dem selben Stand wie 'origin/rc-its'.
  Änderungen, die nicht zum Commit vorgemerkt sind:
  (benutzen Sie "git add <Datei>...", um die Änderungen zum Commit vorzumerken)
  (benutzen Sie "git checkout -- <Datei>...", um die Änderungen im Arbeitsverzeichnis zu verwerfen)

  geändert:       bits/images/design/header.jpg

  keine Änderungen zum Commit vorgemerkt (benutzen Sie "git add" und/oder "git commit -a")

Ein Commit für das neue Logo

   git:(rc-its) ✗ git commit bits/images/design/header.jpg -m " kunden logo"
   [rc-its 593eef6]  kunden logo
   1 file changed, 0 insertions(+), 0 deletions(-)
   rewrite bits/images/design/header.jpg (99%)

und dann hoch schieben:

  git push
  Zähle Objekte: 6, Fertig.
  Delta compression using up to 4 threads.
  Komprimiere Objekte: 100% (5/5), Fertig.
  Schreibe Objekte: 100% (6/6), 67.52 KiB | 0 bytes/s, Fertig.
  Total 6 (delta 3), reused 0 (delta 0)
  remote:
  remote: To create a merge request for rc-its, visit:
  remote:   https://g.........%5D=rc-its
  remote:
  To git.......git
  d0f277c..593eef6  rc-its -> rc-its

Jetzt wechseln wir wieder in den master

  git checkout master
  Zu Branch 'master' gewechselt
  Ihr Branch ist auf dem selben Stand wie 'origin/master'.

Und sehen das originale Logo. Nun wollen wir die nächste Hauptänderung machen

   git:(master) find ./ -type f -exec sed -i -e 's/Behörden-IT-Sicherheitstraining/IT-Sicherheitstraining/g' {} \;
   git:(master) ✗ git commit * -m "Behörden-it-sicherheits... in IT-Sicherheitstraining geändert"
   git:(master) git push     

Der Branchwechsel

      git:(master) git checkout rc-its
      Zu Branch 'rc-its' gewechselt
      Ihr Branch ist auf dem selben Stand wie 'origin/rc-its'.
      ➜  ...... git:(rc-its)

Die Webseite hat noch das Kundenlogo und den alten Titel

 git:(rc-its) git merge master

TATATAA: Die Webseite hat das Kundenlogo und neuen Titel

23.3.19
Weitere Beiträge zu: asciidoctor  

Asciidoctor: Texte mit Bedingungen

Asciidoctor ist inzwischen mein Standardwerkzeug wenn es um Dokumentationen geht.

Was mir bisher immer Kopfzerbrechen bereitet hat ist das man interne Dokumentationsanteile von den “Kundendokumentationen” getrennt aufbereitet muss.

Bei Asciidoctor kann man Texte in Abhängigkeit von Variablen einbinden. Zum Beispiel so

  ifdef::internal[]
  include::internal-intro.adoc[]
  endif::internal[]

Und dann kann man durch

  asciidoctor-pdf index.adoc -a internal=1

ein PDF erstelle das die internen Anteile dabei hat und mit

  asciidoctor-pdf index.adoc

das externe Dokument erstellen. Und man kann beide Informationsarten in einem Dokument zusammenpflegen.

8.3.19
Weitere Beiträge zu: asciidoctor  

Asciidoctor mit deutschen Begriffen

Asciidoctor ist ein Werkzeug zum erstellen von Dokumentation das mich momentan immer mehr begeistert.

Ein Punkt ist allerdings das im Standart Begriffe wie “Chapter” oder “Index” verwendet werden. Möchte man dort lieber “Kapitel” oder “Inhaltsverzeichnis” stehen haben geht das recht einfach

Im Verzeichnis das die Dokumentation enthält:

  mkdir locale/
  cd locale/
  wget https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/data/locale/attributes.adoc
  wget https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/data/locale/attributes-de.adoc

Und dann in der Im Index.adoc dann noch :lang: de include::locale/attributes.adoc[]

Und dann kann man durch

  asciidoctor-pdf index.adoc

die deutschen Begrifflichkeiten im Text bekommen

19.10.18
Weitere Beiträge zu: asciidoctor  

Froscon 13: Documentation with any editor

Der Froscon13 Vortrag auf den ich am gespanntesten war da ich mit Christoph schon im Vorfeld darüber gesprochen hatte.

Create beautiful documentation in the editor of your choice and organize your stuff in git and co

Und ich wurde nicht enttäuscht. Dieses asciidoctor werde ich auf jeden Fall in dem nächste Dokumentationsprojekt verwenden.

Also jeder der mit seiner aktuellen Art Dokumentation zu schreiben nicht zufrieden ist sollte sich dieses Replay unbedingt ansehen.

25.8.18
Weitere Beiträge zu: Froscon   Documentation   asciidoctor  

Dies ist ein privater Blog von Hagen Bauer- berufstätiger Vater, Ehemann, Naturliebhaber, Läufer, Zelter, technikverliebt.


Creative Commons License
This blog is licensed under a Creative Commons License