Discussion:
Neu: man-Pages auf eisfair
(zu alt für eine Antwort)
Marcus Röckrath
2020-11-22 11:56:45 UTC
Permalink
Hallo Paketentwickler,

ab sofort dürfen auch man-Pages auf dem eisfair "installiert" werden.

Die man-Pages sollen/müssen aber in ein eigenes Paket ausgelagert werden,
ähnlich einem -dev-Paket.

Beispiel:

Paket: xyz
man-Paket: xyz-doc


In der Infodatei des xyz-doc-Paketes:

<name>xyz-doc</name>
<section>doc</section>
<system>eisfair-noarch</system>

Hat das xyz-Paket das <short>-Tag

<short>xyz - Tool for ...</short>

dann bekommt das doc-Paket den Tag

<short>DOC: xyz - Tool ...</short>

Der <description> Abschnitt wird/kann aus dem zugehörigen Grundpaket leicht
variiert übernommen werden, z. B.:

<description>
xyz a.b (The man files)
...
...
</description>

Ein doc-Paket hat kein Verzeichnis /usr/share/doc/<paketname>, wie dies auch
für lib- und -dev-Pakete gilt, also insbesondere auch keine changes-Datei.

Das info-File des Hauptpaketes bekommt zusätzlich

<linked-package>xyz-doc <versionsnummer></linked-package>


Es erledigt sich damit die manchmal geübte Praxis, man-Pages als
umgewandelte Textdateien in der Dokumentation des Hauptpaketes
in /usr/share/doc/<paketname>/<paketname.txt> unterzubringen.

Derzeit gibt es schon eine Handvoll Pakete, die das nun so umsetzen, die man
sich auch mal anschauen kann:

nano, minipro, picocom, hstr, columscat

PS: Packeis warnt derzeit noch beim Hochladen, wenn man-Pages in einem Paket
stecken.
--
Gruß Marcus
[eisfair-Team]
Kay Martinen
2020-11-22 13:39:32 UTC
Permalink
Post by Marcus Röckrath
Hallo Paketentwickler,
Bin ich zwar nicht, dennoch my 2ct.
Post by Marcus Röckrath
ab sofort dürfen auch man-Pages auf dem eisfair "installiert" werden.
Ich wusste nicht mal das die bisher *nicht* installiert werden *durften*!
Post by Marcus Röckrath
Die man-Pages sollen/müssen aber in ein eigenes Paket ausgelagert werden,
ähnlich einem -dev-Paket.
Warum? Warum nicht in einem Paket das z.b. joe enthielte, oder den
inetutils-deprecated (oder wie auch immer netstat, route usw. jetzt heißen)?

Vermutung: Weil Eisman kein Recommend vs. suggest als Beziehung zwischen
Paketen kennt?
Post by Marcus Röckrath
Paket: xyz
man-Paket: xyz-doc
Fände ich; als user; unlogisch. xyz-man wäre deutlich intuitiver - wenn
es denn schon so sein muß.
Post by Marcus Röckrath
<name>xyz-doc</name>
<section>doc</section>
<system>eisfair-noarch</system>
Hat das xyz-Paket das <short>-Tag
<short>xyz - Tool for ...</short>
dann bekommt das doc-Paket den Tag
<short>DOC: xyz - Tool ...</short>
Warum eigentlich DOC und nicht MAN?

Bei DOC denke ich direkt erst mal an Komplett-DokumentationsPakete (bei
$otherlinux, z.b. für Exim-Doc) oder an das 'info' tool das IMHO
historisch eher das ist was die längeren und ausführlicheren
Dokumentationen enthielte. man-pages sehe ich eher als "ausführlicher
als 'tool -h'" aber kürzer als 'info <tool>'

Mein Vorschlag:
<short>MAN: xyz - Tool, man-pages...</short>
Post by Marcus Röckrath
Ein doc-Paket hat kein Verzeichnis /usr/share/doc/<paketname>, wie dies auch
für lib- und -dev-Pakete gilt, also insbesondere auch keine changes-Datei.
Ich kenne bei man-pages nur eine art "Version x.y <date>" am Ende des
Textes.
Post by Marcus Röckrath
Das info-File des Hauptpaketes bekommt zusätzlich
<linked-package>xyz-doc <versionsnummer></linked-package>
Sorgt das dann für das automatische nachladen des man-paket wenn man das
tool installiert?
Post by Marcus Röckrath
Es erledigt sich damit die manchmal geübte Praxis, man-Pages als
umgewandelte Textdateien in der Dokumentation des Hauptpaketes
in /usr/share/doc/<paketname>/<paketname.txt> unterzubringen.
Ach so. Die Verwandschaft ist mir bisher nicht sehr aufgefallen da
zuerst die TOOL_X_NAME u.s.w. Parameter und das Menü beschrieben werden.

Oft kommt am Ende dann etwas das eher so aussieht.
Post by Marcus Röckrath
Derzeit gibt es schon eine Handvoll Pakete, die das nun so umsetzen, die man
nano, minipro, picocom, hstr, columscat
Davon habe ich nur nano installiert, benutze ihn aber selten.

Eine Anregung hätte ich noch aber ich weiß nicht ob die schwer oder
unmöglich um zu setzen wäre. Die Kontext-Hilfe (F1) im ECE enthält bei
vielen Einträgen keine Infos.

Ob es möglich wäre den Parameter den so ein Eintrag manipuliert in der
man-page automatisiert zu lokalisieren und für diesen Hilfetext zu
markieren, taggen oder zu importieren. Das könnte entweder beim
Paket-erstellen einmalig oder beim Installieren/update durch einen
indizierungs-durchlauf einmalig gemacht werden. Und es würde die
verfügbarkeit von aussagekräftigeren Hilfstexten im ECE sicherlich
schnell und deutlich verbessern.

Z.B. Wenn im Samba paket der Parameter für WORKGROUP keine F1 Hilfe im
ECE hätte dann könnte man in 'man 5 smb.conf' danach suchen. Nur wie man
dann alles andere ausfiltert und nur den Passenden Block wie diesen hier
(aus meinem ubuntu)
Post by Marcus Röckrath
workgroup (G)
This controls what workgroup your server will appear to be in when queried by clients. Note that this parameter also
controls the Domain name used with the security = domain setting.
Default: workgroup = WORKGROUP
Example: workgroup = MYGROUP
findet und übernimmt weiß ich nicht. Bei Samba könnte man noch nach dem
(G) für globale Parameter filtern aber es scheint als müsse man das
Konfig-bezogen jeweils neu an passen. Doch wohl nicht so leicht... Oder?


Kay
--
Posted via leafnode
Marcus Röckrath
2020-11-22 14:47:03 UTC
Permalink
Hallo Kay,
Post by Kay Martinen
Post by Marcus Röckrath
ab sofort dürfen auch man-Pages auf dem eisfair "installiert" werden.
Ich wusste nicht mal das die bisher *nicht* installiert werden *durften*!
Ein Paketentwickler bekommen eine fette Warnung, wenn ein Paket man-Pages
enthält!

Auch das notwendige Anzeigeprogramm hat erst spät Einzug in eisfair
gefunden.
Post by Kay Martinen
Post by Marcus Röckrath
Die man-Pages sollen/müssen aber in ein eigenes Paket ausgelagert werden,
ähnlich einem -dev-Paket.
Warum? Warum nicht in einem Paket das z.b. joe enthielte, oder den
inetutils-deprecated (oder wie auch immer netstat, route usw. jetzt heißen)?
Z. B. ist ein doc-Paket vom Typ noarch, also in E1 und E64 gleichermaßen
installierbar und es müssen die gleichen Dateien nicht in beiden
Binärpaketen vorzuhalten.
Post by Kay Martinen
Post by Marcus Röckrath
Paket: xyz
man-Paket: xyz-doc
Fände ich; als user; unlogisch. xyz-man wäre deutlich intuitiver - wenn
es denn schon so sein muß.
Eine Manpage ist ein Dokument, deshalb ist doc logisch. Auch wenn es bei uns
derzeit keine Rolle spielt, gibt es auch info-Dateien (und das zugehörige
info Programm) mit dem man Dokumentation zu Programmen zur Verfügung
stellen könnte.

Also nicht jetzt für jede (eventuell zukünftig) denkbare
Dokumentationsdarstellungsart neue Paketnamenregeln.
Post by Kay Martinen
Warum eigentlich DOC und nicht MAN?
Passend zu -doc im Paketnamen.
Post by Kay Martinen
Ich kenne bei man-pages nur eine art "Version x.y <date>" am Ende des
Textes.
Wir liefern man-Pages exakt so aus, wie sie in der zugrundeliegnden Source
drin stehen.
Post by Kay Martinen
Post by Marcus Röckrath
Das info-File des Hauptpaketes bekommt zusätzlich
<linked-package>xyz-doc <versionsnummer></linked-package>
Sorgt das dann für das automatische nachladen des man-paket wenn man das
tool installiert?
Nein, das ist kein require. Der linked-Tag sorgt für eine Verknüpfung zu
einem anderen Paket, so dass dies zum Beispiel bei einer Updateinstallation
mit

eisman install paketname

ein in diesem Paket angegebenes Linked-Paket mit upgedatet wird, falls
installiert.

Für ein eisman update wäre der linked-Tag nicht wichtig, da dies alle
verfügbaren Updates installiert.
Post by Kay Martinen
Post by Marcus Röckrath
Es erledigt sich damit die manchmal geübte Praxis, man-Pages als
umgewandelte Textdateien in der Dokumentation des Hauptpaketes
in /usr/share/doc/<paketname>/<paketname.txt> unterzubringen.
Ach so. Die Verwandschaft ist mir bisher nicht sehr aufgefallen da
zuerst die TOOL_X_NAME u.s.w. Parameter und das Menü beschrieben werden.
Oft kommt am Ende dann etwas das eher so aussieht.
Genau, ich habe zu Kommandozeilentools meist konvertierte man-Pages in die
Doku reinkopiert.
Post by Kay Martinen
Eine Anregung hätte ich noch aber ich weiß nicht ob die schwer oder
unmöglich um zu setzen wäre. Die Kontext-Hilfe (F1) im ECE enthält bei
vielen Einträgen keine Infos.
Ob es möglich wäre den Parameter den so ein Eintrag manipuliert in der
man-page automatisiert zu lokalisieren und für diesen Hilfetext zu
markieren, taggen oder zu importieren.
Was haben die man-Pages von (in der Regel) Kommandozeilentools mit den
Optionen der eisfair spezifischen Konfigurationsparameter zu tun?

In der Regel nichts.
Post by Kay Martinen
Z.B. Wenn im Samba paket der Parameter für WORKGROUP
In der Regel sind die Optionen in den eisfair-Konfigurationsdateien nicht
1:1 auf reale existierende Optionen der zugrundeliegenden Software
abbildbar.

Und für den Fall, dass eine Option exakt zu einer Option des "Programms"
passt, muss eine 1:1-Namenübersetzung vorgehalten werden.

Vielmehr führen einzelne eisfair-Paket-Konfigurationsoptionen zu einer
Vielzahl von Operationen auf tieferen Ebene, also z. B. auch zur
Verknüpfung von verschiedneen Optionen des zugrundeliegenden Programms.
--
Gruß Marcus
[eisfair-Team]
Marcus Röckrath
2020-11-22 14:48:51 UTC
Permalink
Hallo,
Post by Marcus Röckrath
PS: Packeis warnt derzeit noch beim Hochladen, wenn man-Pages in einem
Paket stecken.
Falsch, basierte auf einem falsch gesetzten section-Tag, wo ich vergessen
hatte, dieses auf doc zu setzen. In Paketen mit der section doc wird eine
enthaltene man-Page nicht bemängelt, sehr wohl aber in Paketen aller
anderer Sektionen.
--
Gruß Marcus
[eisfair-Team]
Thomas Quast
2020-11-24 05:46:00 UTC
Permalink
Post by Marcus Röckrath
ab sofort dürfen auch man-Pages auf dem eisfair "installiert" werden.
Wann steht dazu etwas in der Entwicklerdokumentation?
Post by Marcus Röckrath
Ein doc-Paket hat kein Verzeichnis /usr/share/doc/<paketname>, wie dies auch
für lib- und -dev-Pakete gilt, also insbesondere auch keine changes-Datei.
Aber ein /usr/share/man/... gibt es dann schon?

Gruss,
Thomas
--
Packageserver: https://www.oritopha.de/index.txt
Marcus Röckrath
2020-11-24 05:59:10 UTC
Permalink
Hallo Thomas,
Post by Thomas Quast
Post by Marcus Röckrath
Ein doc-Paket hat kein Verzeichnis /usr/share/doc/<paketname>, wie dies
auch für lib- und -dev-Pakete gilt, also insbesondere auch keine
changes-Datei.
Aber ein /usr/share/man/... gibt es dann schon?
Das wäre doch schlicht egal und kann auch nicht sagen, ob das auf jedem eis
schon existiert.

Da dort die man-Pages hingehören (in Unterverzeichnisse davom), wird es
spätestens dann erzeugt, wenn das erste Paket mit man-Pages installiert
wird.
--
Gruß Marcus
[eisfair-Team]
Sebastian Ertz
2020-11-24 19:37:16 UTC
Permalink
Hallo,

bin gerade dabei meine Pakete ipset, ipset-dev und libipset13 von 7.6
auf 7.9 zu aktualisieren.
Aber es gibt zwei Manpages ipset.8 und libipset.3
Im Suse RPM sind die beiden Manpages im Paket ipset drinnen.
Welche Variante ist nun gewÃŒnscht?
1. Ein Paket 'ipset-doc' mit beiden Manpages ipset.8 und libipset.3
2. Oder Zwei Pakete 'ipset-doc' mit Manpage ipset.8 und 'libipset13-doc'
mit Manpage libipset.3

Gruß
Sebastian
Marcus Röckrath
2020-11-24 19:46:45 UTC
Permalink
Hallo Sebastian,
Post by Sebastian Ertz
1. Ein Paket 'ipset-doc' mit beiden Manpages ipset.8 und libipset.3
Wäre mein Favorit.
--
Gruß Marcus
[eisfair-Team]
Loading...