Manual-pages

[das.chaos]

Moin,

da hier in diesem Forum erfahrene Systementwickler anwesend
sind, die bzgl. beruflicher Praxis im Feld der Systementwicklung
bzw. Systemprogrammierung im Kontext von Unixderivaten mir
um Lichtjahre voraus sind, bewegt mich die Frage, wie man denn
nun inhaltlich eine Manualpage schreibt?

Das troff(1) verwendet wird, ist mir bekannt, diesbezueglich bin ich
in der Lage mir selbst zu helfen.

Welche Kapitel bzw. Sektionen [1;9] existieren und welchen Kontext
diese beschreiben habe ich schon verstanden.

Wie Konstanten (bspw. von ioctl(2) akzeptierte Service Primitives
bzw. Dienstprimitive) erklaert werden, habe ich auch verstanden.

Was mich mehr interessiert ist die Frage, nach welchen Kriterien
die Referenzen in Sektion SEE ALSO erwaehnung finden?

Kann mir Irgendjemand das erklaeren oder ein Paper empfehlen
bzw. eine literarische Quelle (Webpage, Text in Maillingliste, ...)
benennen?

Oder wonach muss ich mittels ${SUCHMASCHINE} suchen bzgl.
Hilfe zur Selbsthilfe?

Ich bin nun nicht wirklich denkfaul, aber wenn man, mangels
Erfahrung, nicht wissen kann wonach man suchen muss, so
ist es manchmal, als ob man sei wie ein Ochs vorm' Berge.

 

[KobRheTilla]

Ich würde in der SEE ALSO verwandte Programme unterbringen oder Programme, die von dem beschriebenen Programm genutzt werden.
Letztendlich steht es dir auch frei, die Sektion komplett wegzulassen, es ist ja deine Manpage.

Rob

 

[goblin]

Die wenigen Male, die ich eine Manual-Page geschrieben habe, hab ich mir diverse OpenBSD-Manualpages von ähnlichem Umfang angeschaut und deren Struktur imitiert.
Einen Standard gibt es soweit ich weiß nicht, auf zusammengewurschtelten Systemen wie den meisten Linux-Distributionen ist das gut zu sehen. Da schwankt die Qualität unglaublich, je nach den wo die Software halt herkommt.

 

[double-p]

troff(1) wird nicht ueberall verwendet - von daher waere die Zielplattform schon interessant.

Nach 'SEE ALSO' gehoert einfach alles, das einen *direkten* Bezug zu diesem Tool/API/ioctl/... hat, sonst hat man irgendwann
ueberall zumindest ls(1) oder aehnlich generisches mit drin ;-).

Da ich zu pf(4) und Verwandten genug beigetragen habe und OpenBSD sowieso als das beste System hinsichtlich
manpages sehe (nicht nur dort, aber das besonders) - fang doch mal in einem "man 8 pfctl" (geht auch via web) an und schau, wie weit (oder nicht)
Dich zum Beispiel SEE ALSO leitet.

 

[das.chaos]

troff(1) wird nicht ueberall verwendet - von daher waere die Zielplattform schon interessant.

Momentan FreeBSD 10.1-RELEASE, nach Tests und Refaktorisieren dann 10.2.

Nach 'SEE ALSO' gehoert einfach alles, das einen *direkten* Bezug zu diesem Tool/API/ioctl/... hat, sonst hat man irgendwann
ueberall zumindest ls(1) oder aehnlich generisches mit drin ;-).

Da ich zu pf(4) und Verwandten genug beigetragen habe und OpenBSD sowieso als das beste System hinsichtlich
manpages sehe (nicht nur dort, aber das besonders) - fang doch mal in einem "man 8 pfctl" (geht auch via web) an und schau, wie weit (oder nicht)
Dich zum Beispiel SEE ALSO leitet.

Ahhh, perfekt... da habe ich einen Katalog an sehr vielen Fragen.

Ich Portiere (oder erzeuge mehr oder weniger ein Derivat) momentan
den in OpenBSD 4.7-RELEASE implementierten MPLS Protokollstapel
nach o. g. Betriebssystem, da ich die interne Struktur von erwaehnten
Betriebssystemen verstehen will.

Nun bzgl. Manualpages kann ich nicht direkt die Existierenden aus
OpenBSD uebernehmen, da bzgl. Integration von Protokolldomaenen in
Netzwerkprotokollstapel doch (signifikante) Unterschiede zwischen den
erwaehnten Betriebssystemen bestehen.

Es ist moeglich aber eine Teilmenge von bestehender Dokumentation
zu Zitieren, wobei sich bspw. die Implementierung von mpls_control
auf Zielplattform (von urspruenglicher) erheblich unterscheidet.

Auf den Mailinglisten habe ich mich (noch) nicht getraut zu fragen, da
ich nicht in den Verdacht von SEO geraten will.

 

[double-p]

Und was war jetzt der Fragenkatalog?

 

[das.chaos]

Moin,

das tonnenweise Fehler enthalten sind, steht ausser Frage (daher bitte nicht lachen)!

Wenn einem die Decke auf den Kopf faellt, dann sollte man irgendwie kreativ werden, bevor man
aus Langeweile (es wagt) die Glotze einzuschalten oder anfaengt anderweitig zu verbloeden (da
gibt es vielfaeltige Moeglichkeiten, die einen in eine Anstalt oder Ausnuechterungszelle bringen
koennen kann).

Und was war jetzt der Fragenkatalog?

1. Verwende ich die BSD Lizenz fehlerhaft?
   
   Denn Ich habe einige Komponenten (bspw. netgraph/ng_ether.c) "Wiederveroeffentlicht",
   obwohl nur die um ca. eine Zeile Code modifiziert wurde.
   
   Macht es bei einer Modifikation um nur einer Zeile Code ueberhaupt Sinn, bspw. o. g.
   Beispiel mit einem "ueberfluessigen" Lizenzvermerk zu "verzieren" oder "verunstalten"?
   
   Ich habe definitiv keine Profilneurose bzw. kein intergalaktisches Ego und habe es nicht
   noetig mir ein "Denkmal" zu setzen. Ich betrachte das hier als kleine Turnuebung bzw. als
   Spielerei (man darf sich doch wohl mal ein bisschen austoben), um die interne Struktur
   von BSD basierten Unixderivate besser zu verstehen.
   
   Ich habe wenig Ambitionen, dass der Mob mit Mistgabeln... aeeehh dass eine Horde von
   Anwaelten mit Abmahnungen (oder aehnlichen Schikanen) mir die Tuer einrennt (oder
   eintritt, denn das ist nicht witzig).
   
   
2. Macht es Sinn die Funktionen zur Identifikation von Next Hop Label Forwarding Entries (nhlfe)
   in netmpls/mpls.c beizubehalten?
   
   Ich halte diese fuer haesslich und ueberfluesig, da diese nicht wirklich Redundanzen neutralisieren.
   
   
3. Muss immer eine rt_addrmsg freigesetzt werden, wenn ein von ifaddr{} (polymorph) abgeleiteter nhlfe
   mit einer ueber ifnet(9) implementierten Schnittstelle assoziiert (oder auch inverse Operation) wird?
   
   
4. Wiso muss die Schnittstellenspezifikation einer beliebiger Protokolldomaene xxx bzw. netxxx
   in netxxx/xxx.h und netxxx/xxx_var.h unterteilt werden?
   
   Beruht diese Tatsache auf einer technischen Norm oder beruht dies auf einer Konvention?

Da fallen mir noch mehr ein, aber ich denke dass dann das sich dann in einem Overkill manifestieren kann.

 

[Yamagi]

Verwende ich die BSD Lizenz fehlerhaft?

Denn Ich habe einige Komponenten (bspw. netgraph/ng_ether.c) "Wiederveroeffentlicht",
obwohl nur die um ca. eine Zeile Code modifiziert wurde.

Es kommt drauf an... Im Prinzip darfst du dein Copyright einfügen, sobald du nur ein Zeichen innerhalb der Datei änderst. In der Datei befinden sich fortan Änderungen von dir, folglich bist du Mitinhaber des Copyrights. In der Praxis ist es nun aber so, dass in dem Fall die Copyright-Liste bald länger als der Source wäre. Zumindest im FreeBSD Projekt ist daher der ungeschriebene Konsens, dass man sich erst bei "signifikanten Änderungen" einträgt. Also wenn man einen nennenswerten Teil des Codes angefasst hat (so als grobe Faustregel 10% oder mehr), wenn man bedeutende technische Änderungen vorgenommen hat (zum Beispiel einen Algorithmus überarbeitet) oder die Änderung einiges an Arbeit gekostet hat.

Mir ist übrigens kein Fall bekannt, wo sich jemand beschwert hätte, dass ein anderer Entwickler nach einer Änderung ein Mit-Copyright beansprucht hätte. Die Probleme liegen eher auf der anderen Seite. Also das jemand die Lizenz bricht und Copyrights wieder entfernt.