[linux-l] Warum gibt es keine einheitliche Dokumentation? (war: dwww)

[Volker Grabsch]

On Tue, Jan 02, 2007 at 07:25:05PM +0100, Steffen Dettmer wrote:
> * Volker Grabsch wrote on Tue, Jan 02, 2007 at 03:41 +0100:
> > On Mon, Jan 01, 2007 at 10:36:36PM +0100, Steffen Dettmer wrote:
> > > Ich hab da auch noch den Vorschlag vom kompliziert zu bedienenden,
> > > GUI-freien Kommunikationstool. 
> > 
> > Im Gegenteil: Wären die graphischen IRC-Werkzeuge von den "Konsolen-
> > Freaks" entwickelt worden, wäre in diese viel mehr Standardkonformität
> > hinein gekommen. Das gilt umso mehr für Newsreader.
> 
> IRC ist ja nicht blöd, weil die Werkzeuge nicht konform sind, sondern
> weil sich da Herrscharen von 12 jährigen als sonstwas ausgeben und
> rumnörgeln und so weiter. Man konnte sich damals irgendwann einfach
> nicht mehr unterhalten. Das war kein technisches Problem.

Da ist was dran. Jedoch im Usenet waren's auch technische Probleme.

> > Stattdessen werden die GUIs verpönt, aber der Bedarf ist trotzdem da.
> > Ist doch klar, dass dann gerade diejenigen die GUI-Clients
> > programmieren, von denen man es nicht will. Und dass dort viel mehr
> > fehlgeleitetes Design hinein kommt, als hätte es ein Experte
> > entworfen. Aber selbst schuld.
> > 
> > Wenn sich die Fähigen dafür zu fein sind, wird es eben von Unfähigen
> > gemacht.
> 
> Wieso, die GUIs sind doch von Fähigen gemacht. Sie sind nur zu gut. Weil
> jeder sie benutzen kann, um das Internet mit einen Forenbeiträgen zu
> polluten usw.

Stimmt. Meine Ausführungen waren jedoch allgemeiner gehalten. Es ging
um die prinzipielle Tendenz, Anfänger auszuschließen. Und konkret im
Usenet hatte das auch viel mit schlechten, aber anfängerfreundlichen
Newsreadern zu tun.

>  [...] 
> > Aber diese "durchdachte, hochentwickelte Doku" kann man doch wiederum
> > als Wiki zur Verfügung stellen. Was spricht denn dagegen? Diese ist doch
> > nun, dank ihrer durchdachten strukturierung, noch viel leichter
> > anzupassen, zu korrigieren und zu ergänzen.
> 
> Gut, mag sein dass meine Vorstellungskraft für ein "Buch im Wiki"
> einfach nicht ausreicht. Natürlich könnte man ein "export" oder sowas
> machen. Dann ist das für mich aber eher HTML und kein Wiki.

Nein, du hast mich immer noch nicht ganz verstanden.

Ich meinte, dass du diese Umstrukturierung, Korrektur, etc.
mit dem Wiki-Quellcode machen könntest. Und diesen dann wieder
anderen zugänglich machst.

Erst danach bräuchtest du dann HTML- oder PDF-Konvertierung anwerfen,
zusammen mit irgendwelchen optischen Korrekturen.

Natürlich benötigst du dazu ein Wiki, auf dessen Seiten du auch
per Editor+SCM zugreifen kannst, das ist klar. Aber darum geht es
ja, dass wir das wollen. Außerdem ist eine Umstrukturierung mit dem
Browser auch noch erträglich. Zumindest mit lynx, der dir bei großen
Textfeldern den Lieblingseditor aufruft. :-)

> > > Ahh, OK, das klingt cool. Gibt's sowas?
> > 
> > Es gibt SubWiki, das intern Subversion verwendet. Weiß aber nicht, wie
> > gut das mittlerweile ist. Die guten und bekannten Wikis (MediaWiki,
> > DokuWiki) kochen da leider ihr eigenes Süppchen. MediaWiki mit MySQL,
> > DokuWiki mit RCS.
> 
> DokuWiki? Was deutsches? Ich nutze noch ein altes Perl Wiki "TWiki" aus
> 2000, das nutzt auch RCS. Könnte man ja vuielleicht mal updaten BTW :)

Ich weiß nicht, woher DokuWiki kommt. Aber es ist recht gut. Ein Freund
von mir benutzt das intensiv. Ich benutze eher MediaWiki. Die beiden
haben jeweils ihre Vor- und Nachteile.

(DokuWiki hat viel schickere Tabellen. Dafür kann MediaWiki E-Mail bei
Seitenänderungen verschicken.)

TWiki habe ich mir mal angesehen, ist aber nichts für mich.

> > Diese und weitere Gedanken habe ich mal zusammengefasst:
> >     https://dev.njh6.de/wiki/index.php?title=Wikidok
> > 
> > Einen sehr interessanten Thread zu dem Thema gab's hier auf der Liste
> > auch mal.
> 
> (Warum geht das nicht ohne SSL/TLS? Da suggeriert ja so Sicherheit, die
> nicht da ist, weil selfsigned cert?! 

Erstmal: Die Sicherheit besteht in der Verschlüsselung. Und die ist
erstmal da. Das schützt vor einem großen Haufen von Attacken.
(Obwohl der Schutz vor dem Ausspähen von Daten, die ins Wiki eingetragen
werden, nicht wirklich sinnvoll ist, zugegeben. ;-))

Vor Man-in-the-Middle-Attacken schützt es nicht. Das stimmt.

Ich wollte eben nur einen Webzugang haben. Und weil dort noch
SVN-Repositories liegen (Überbleibsel von damals, als ich SVN noch
über HTTPS gemacht habe), habe ich mich für SSL entschieden, und
das konsequent umgesetzt.

Mittlerweile ist das Wiki umgezogen nach:
    http://wiki.njh.eu/

(Man beachte unsere neue schicke kurze EU-Domain. :-))

Aber ich bin nur mit den Artikeln umgezogen. Die Projektseiten bleiben.
Die will ich auf dem gleichen System haben wie die SVN-Repositories.
Und Wikidok ist eine Projektseite, weil mal angedacht war, dass daraus
Software entsteht. Passiert vielleicht sogar mal.

> ja, ich erinnere mich. Aber sowas muss sich dann auch erst
> durchsetzen... MediaWiki ist das von Wikipedia? Fragt sich, inwieweit
> das Standard ist, weil es am meisten kennen :)

Das auf jeden Fall. Aber Programmierer kennen eher reST. Genauer: Sie
kennen README-Dateien und haben sicher sehr oft Überschriften etc.
in Plaintext gemacht, und dabei intuitiv genau das gemacht, was reST
in Regeln fasst. (z.B. Kapitel mit "====" oder "----" unterstrichen)

> > > > > Wie schön könnte man einen aus plain-text automatisch erzeugten Druck
> > > > > überhaupt hinkriegen? Brauchbar?
> > > > 
> > > > Wie schon gesagt: LaTeX. Wo ist das Problem?
> > > 
> > > Ich hab mit LaTeX z.B. keine schönen Tabellen hinbekommen (kannte auch
> > > keinen LaTeX-Guru).
> > 
> > Lamport empfielt in seinem Buch, dass man in Tabellen möglichst auf
> > Linien verzichten sollte, das macht sie übersichtlicher. Es widerspricht
> > allem, was ich gewohnt bin, aber nachdem ich schon ein paar mal damit
> > herumgehadert habe, muss ich sagen: Der Mann hat recht. 
> 
> Kommt sicher drauf an. Wenn nur 1% der Felder belegt sind, sind Linien
> bestimmt eine Gute Idee :)

Aber dann ist die Tabelle selbst schon die schlechte Idee, oder?

Außer dünn besetzten Matrizen fällt mir nichts ein. Und selbst die sind
ohne Linien übersichtlicher.

> > Man ist viel zu leicht versucht, Doppel-Linien, dickere Linien etc.
> > reinzubringen, obwohl man die dünnen einfach weglassen sollte.
> > 
> > Das ist also eher ein Feature, kein Bug.
> 
> Ahh, Java-Argumentation. Geht nicht, also braucht mans eigentlich gar
> nicht, weil man einen Fall gefunden hat, wo's ohne sogar besser ist.
> 
> Nee, sorry aber das akzeptiere ich nicht :)

Nee, nicht ganz. Lamport scheint mir nämlich ein *fähiger* Designer zu
sein. (Im Gegensatz zu ...)

Von daher vertraue ich diesem Urteil, dass man wirklich sparsam mit
Tabellen-Linien umgehen soll. Und wenn ich sie doch brauche: LaTeX
hindert mich nicht daran. (Noch ein Gegesantz zu Java)

> Bleibt die Frage, ob die Tabelle ohne Linien dann übehaupt autoamtisch
> richtig formatiert wird. Ich glaub ja nicht, dass die Linien da so einen
> UNterschied machen.

Machen sie nicht. Das ist richtig.

> > > LaTeX ist ein Satz-System, kein automatischer Formatierer.
> > 
> > LaTeX ist beides. Um sehr, sehr viele typische Textsatz-Probleme
> > kümmert es sich automatisch.
> 
> Man bekommt aber Warnungen, wenn was nicht hinhaut (kann man natürlich
> ignorieren, klar).

Genau, dann darf man Hand anlegen. Aber LaTeX-Warnungen sind doch
meistens Fälle, die man erst kurz vor dem Druck korrigieren will,
und nicht in einer Arbeitsversion, bei der sich der Text noch ändert.

> > > oder mein Fachbegriff nicht ungünstig getrennt wird
> > 
> > Du kannst LaTeX Tenn-Hinweise geben:
> > 
> >     LangesWort\-HierTrennen
> > 
> > Dann trennt LaTeX dort, wenn es sich anbietet, ansonsten lässt es das
> > Wort ganz.
> 
> Ja, kann man, und genau das ist für mich händisch und nicht automatisch!

Ja, sicher. Aber das braucht man erst ganz zum Schluss. Aber das davor
(von Manpage/reST/Wiki nach LaTeX) kann man doch automatisch
konvertieren lassen. Besser gesagt: Man sollte es sogar, IMHO.

Ich sehe daher nicht, wieso dieses Argument dafür spricht, gleich alles
selbst in LaTeX zu tippen oder in OpenOffice oder so, und dann nach
PDF zu konvertieren.

Nur, weil du in LaTeX kleine End-Korrekturen machen musst, schreibst
du lieber den ganzen Text mehrfach?

> > > Leider hat CVS paar komische Bugs. Mit SVN hab ich keine
> > > Erfahrungen. Ich hab da nur ein einziges Repo. Aber das mit derm
> > > mergen und so ist IMHO alles nicht besser als bei CVS. 
> > 
> > Richtig. Hast du höhere Ansprüche, nimm Mercurial.
> 
> Dass ist das ganz langsame Beta-SCM? ;) Kenn ich nicht, keine Ahnung.

Mercurial ist schon lange darüber hinaus. Und es ist verdammt schnell.
Es kann locker mit GIT mithalten.

Im Gegensatz zu GIT ist es einfacher designt. Das finde ich sehr
angenehm.

> > Die Beta-Phase hat SVN längst überwunden. Mercurial, Darcs und GIT
> > übrigens auch.
> 
> CVS auch.

Hab ich nie bezweifelt. Ich sage ja auch nicht, dass der CVS-Code
Schrott ist. Nur die Konzepte sind überholt.

> Der .cvsignore-Ersatz über Properties ist IMHO übrigens eine Krankheit.
> Warum stört die meisten das bei SVN nicht?

Mich stört's. Mercurial hat eine .hgignore, das finde ich viel
angenehmer.

Ditto übrigens auch für Tags. Mercurial hat eine .hgtags-Datei. Sehr
clever gelöst, finde ich. In CVS natürlich nicht machbar, weil jede
Datei ihre eigene Rev.-Nummer hat.

> Weil man behauptet, es sei
> besser, nicht per default alle Dateien im Repo zu haben. Wo kommt das
> her? Find ich nämlich nicht.

Ich auch nicht. Das spricht aber mehr für Mercurial und GIT als für CVS.
;-)

Vielleicht hätte ich von Anfang an Mercurial empfehlen sollen. Aber
die meisten, die ich bisher kennenlernte, wollten lieber erstmal
Subversion haben. Und gröartige Keywords, Ignore-Datein etc. hatten
sie eh nicht.

> Warum
> stört die Java-Leute das nicht? Na, weil die kein automake haben und mit
> dem "ant" leben müssen. Das macht üblicherweise keinen Fehler, wenn ein
> paar .java Files fehlen. Die werden dann halt nicht kompiliert und
> fehlen im .jar dann halt.

Das ist ja übel. Wusste ich gar nicht.

Ich habe übrigens ein Makefile für meine Java-Sachen geschrieben.
Gut, damals gab es auch noch kein ant.

Dennoch: Das ist so einfach. Man hat ja auch viel weniger Detail-
Probleme zu beachten als bei C oder C++ - Programmen. Wieso ant?

Hat ant wenigstens ein paar mehr Features als make, oder hat es
lediglich eine umständlichere (XML-)Syntax?

> *Meine* Ansprüche erfüllt das nicht. Ich habe die Anforderung, dass
> Fehler so früh wie möglich erkannt werden sollen. Also beim kompilieren
> (nicht erst wenn nach dem Installieren ein anderes Programm nicht mehr
> läuft).

Full ACK.

> > In Mercurial z.B. sind Keywords schon nerviger (aber möglich). Habe das
> > aber zum Glück noch nie gebraucht. Wenn man seine Quellen nicht gerade per
> > E-Mail weitergibt und wieder einsammelt: Wozu braucht man dann die
> > Keyword-Ersetzung?
> 
> Dafür, genau. Und evtl. für Ausdrucke. Aber das mit dem Verteilen (nicht
> nur eMail) ist das, was ich in der Praxis lieben gelernt hab.

Ja, wenn nicht alle die VK verwenden, schon klar. Und man sich nicht
merken kann/will, wem man welche Version gab. Zum Glück hatte ich diese
Sorgen nie.

> > > Die Nummern *können* gar nicht repository-übergreifend
> > > funktionieren, also kann ich nicht repo-übergreifend mergen, oder?
> > > Na ja usw.
> > 
> > In Subversion kannst du mehrere Projekte in einem Repository haben,
> > und dann geht das.
> 
> Ich will ja ein Projekt mit mehreren Repositories haben. Nicht paar
> Unterverzeichnisse. Das das geht ist ja wohl selbstverständlich. (CVS
> kann das auch alles).

Wieso? Wo ist das Problem? Wo ist der Unterschied?

Egal, ob ganzes Repository oder Unterverzeichnis: in Subversion ist
das Auschecken dafür ein und der selbe Befehl. Das ist doch eine
rein technische Entscheidung, ob man seine Daten in mehrere oder
in ein Repository steckt.

Will man die Repositories auf vielen verschiedenen Servern haben,
sieht das natürlich anders aus. Dann verstehe ich aber nicht, wieso
man dann dazwischen mergen sollte. Auf welcher Grundlage? Wie kommt
es überhaupt, dass Daten über mehrere Repositories hinweg dupliziert
werden?

Dein konrektes Beispiel würde mich mal interessieren, das du im
Hinterkopf hat. Vielleicht bietet Subversion da ja was viel Eleganteres.

> > > > Darcs und Mercurial umso mehr.
> > > 
> > > Darcs ist Changeset-basiert, ja? Das klingt mächtiger als CVS, hab ich
> > > aber noch nicht benutzen dürfen, sowas. Na ja, ich glaub, hier war das
> > > Problem, dass es lahm ist?
> > 
> > Darcs ja. Mercurial und GIT nicht. Die sind hochoptimiert. CVS und SVN
> > sind dagegen lahm.
> 
> GIT ist das, was beim Kernel benutzt wird?

Genau. Mercurial und GIT sind grob gesehen etwa gleichwetig. Mercurial
ist halt leichtgewichtiger. Das kann man mögen oder auch nicht.

Darcs ist ne Sache für sich. Aber dennoch ziemlich cool, für kleinere
Projekte. Das hat ein phantastisches Kommandozeilen-Interface, an das
GIT und Mercurial in 100 Jahren noch nicht rankommen werden. Aber die
Performance und relativ kleine Community lassen Darcs (ungerechterwiese)
etwas unattraktiv aussehen.

> > > Mal sehen, vielleicht ist SVN vs. <anderen> sowas wie mySQL vs.
> > > PostgreSQL.
> > 
> > Nützt nichts. Schau dir mal die technischen Beschreibungen zu Mercurial
> > und/oder GIT an. Die Machen Es Richtig.[tm]
> > 
> > Ein zusätzlicher SQL-Layer brächte dort keine Vorteile, und unnötige.
> > Einschränkungen. (Man würde ja doch wieder nur einen Haufen BLOBs
> > abspeichern)
> 
> NEIN! Wie kommst Du denn jetzt da drauf! Mein Beispiel setzte doch
> SVN:SCM und mySQL:PostgreSQL in Relation aber nicht SCM:SQL...

Achso, dann habe ich dich falsch verstanden.

> Jedenfalls kann man ein SCM nicht einfach mal so wechseln, finde ich.

Richtig. aber bei neuen Projekten kann man neue SCM ausprobieren. Und
dazu kann ich heutzutage nur raten, wenn man bisher nur CVS und/oder
SVN kannte.

> Aber wenn man keine Anforderungen hat, ist SVN sicher ok.

SVN erfüllt auch Anforderungen, die CVS nicht hat.

Und selbst im Vergleich zu den "richtigen" :-)  SCM wie Mercurial,
Darcs und GIT hat Subversion manchmal aufgrund seiner Einfachheit
Vorteile.

> GIT oder so anzugucken nützt leider mir so allein auch nicht sooo viel,
> weil allein brauch ich das ja auch nicht.

Du hast keine privaten Projekte?

Ich starte dauernd mal was, für das ich ein SCM gebrauchen kann. Und
wenn ich für das SCM kein extra zentrales Repository einrichten muss
wie bei CVS und SVN, sondern das Arbeitsverzeichnis schon das Repository
ist, dann ist das sehr angenehm.

> Zu genau dem Thema gabs ja hier auch schon mal einen längeren Thread.

Ja, damals habe ich dann angefangen, die ganzen Dinger durchzuprobieren.
Außer GIT, dazu kam ich noch nicht.

> > [Dokus für Anfänger]
> > > Bei OpenSource könnte das ja ein VoIP Call sein oder eine IRC
> > > Sitzung.
> > 
> > Stimmt. Auch eine gute Idee. Ich hab schon von Projekten gehört, die das
> > machen.
> 
> Ja? Cool. Ja, hat bestimmt Vorteile.

Firmenbesprechung im IRC ist was nettes. Zumal der Protokollant weniger
Arbeit hat.

> > > > Dann ja. Und zwar alles generiert aus einheitlichen Quellen. Gepflegt
> > > > von Freiwilligen, ggf. Eingebunden von woanders. Ähnlich eine Distri,
> > > > aber mit hoffentlich weniger Wartungs- audwand. Daher auch meine
> > > > Fragen nach geschickten Mechanismen und Ideen.
> > > 
> > > Nette Theorie, aber halte ich leider für kaum möglich...
> > 
> > Mit Manpages hat es doch auch funktioniert. Naja, meistens. Aber
> > immerhin, wie bereits an anderer Stelle bemerkt wurde, war das schonmal
> > der richtige Weg.
> 
> Die wurden doch gerade neu geschrieben? bzw. auch neuen "--help" Seiten
> erzeugt etc?

Nein, aber Manpages werden von fast jedem Projekt bereit gestellt.

Nicht das eine nur in PDF, das andere in HTML, das dritte nur Infopages.
Nein, jeder liefert Manpages, seit langer Zeit. Alle? Nein, ein kleines
Dorf ...
Für diese Gallier gibt es eine Debian-Policy, die regelmäßig Römer
dorthin schickt ...
Diese Römer schreiben dann die Manpages, zur Not mit nichts außer
"--help" und etwas gesundem Menschenverstand.

Vergleiche das mal mit Howtos: Das einzige Standardformat dafür sind
HTML-Seiten, und die können nichtmal ordentlich auf die Dokus anderer
Projekte verlinken, geschweige denn dass sie ein Einheitliches Aussehen
hätten.

Siehst du diesen Unterschied? Und genauo sowas würde ich gerne mal
Abschaffen. Meinetwegen behalten wir das Manpage-Format, aber dann
sollten auch die Howtos über "man" verfügbar sein. Und wer die HTML
haben will, kriegt sie einheitlich von einem man2html-Tool präsentiert,
mit funktionierenden Cross-Projekt-Links und allem drum und dran.

> > Ein interaktives Tutorial kann keine Manpage oder PDF sein. Aber wieso
> > kann ich mit "man" nicht auch Howtos ansehen? Wieso können API-Docs
> > keine Manpages sein? (mit memcopy & Co. geht's doch auch!)
> 
> Ja, oder man hätte eine Art übertool, was alles delegiert anzeigt oder
> so, aber das Übertool sollte nicht einfach ein Browser sein. Obwohl
> ziemlich genau das ja mal die Idee des Browsers war, der Name stimmt ja
> noch.

Ein guter Manpage-Browser könnte das schon leisten.

Aber die vielen HTML-Dokus sind nervig und unnötig schwer unter einen
Hut zu bringen. Eine Notlösung, die das von dir beschriebene Übertool
gerade darstellt, ist dwww. (womit wir wieder beim Aufgangsthema wären ;-))

> > Verschiedene Manpages kann man wenigstens aufeinander verweisen lassen,
> > *ohne* gleich Internet zu benötigen. Es müsste doch sogar *leichter* für
> > JavaDoc, EpyDoc, Doxygen & Co. sein, Manpages statt HTML-Seiten oder gar
> > PDF zu erzeugen. 
> 
> doxygen kann das schon ;)
> 
> Bloss macht man nicht, weil man bei HTML links kriegt und bei man nicht.

... was aber nur an schlechten Manpage-Readern liegt.

> > Ich habe leider immer noch nicht erfahren dürfen, wieso es für API-Docs
> > und Howtos *besser* sein soll, als HTML statt als Manpages vorzuliegen.
> 
> hyperlinks.

Okay, das ist'n Argument. Aber interne Links (auf andere lokal
installierte Doku) sind ein graus. Also stimmt das nicht ganz.

Und wenn man externe Links haben will ... bietet "man" nicht auch sowas
wie URLs an? Und sei es nur, dass der Manpage-Reader URLs im Text
erkennen kann und als Hyperlinks darstellt.

> Websuche kann das auch gleich.

Websuche ist ne nette Sache, du meinst Google. Dass die API-Doc für
die Veröffentlichung auf der Projekt-Homepage nach HTML konvertiert
werden sollte, das ist mir völlig klar.

Aber lokal sind sie nicht wirklich gut durchsuchbar. Jedenfalls
nicht so gut, wie das bei Manpages der Fall ist.

> Kannste mit'm Windowsbrowser drucken.

Ditto. Klar sollte es im WWW als HTML vorliegen. Aber lokal sollte
es doch was besseres als HTML geben.

Und die Konvertierung nach HTML oder PDF sollte nicht im Vorfeld
geschehen und die Pakete bloaten, sondern on-the-fly, z.B. mit
einem Manpage-Betrachter, der drucken und PDF/HTML-Export beherrscht.
(und entsprechende Kommandozeilentools natürlich)


Man wäre da wirklich ne Option. Ordentliche man -> HTML Konvertierer
scheint es ja zu geben. Gute man -> LaTeX Konvertierer gibt's vielleicht
auch. Fehlt nur noch ein guter Viewer und jemand, der die Howtos
ins man-Format bringt. :-)


Viele Grüße,

    Volker

-- 
Volker Grabsch
---<<(())>>---
Administrator
NotJustHosting GbR