Campagna improve man page...

[Guglie]

Originariamente inviato da Andre00
io non dico plichi di help...solo degli esempi eventualmente funzionanti ed empiricamente verificabili...

degli esempi....

Tutto qui...

sono d'accordo: alcuni man scarseggiano in fatto si esempi, altri invece sono fatti meglio

[Ikitt]

Originariamente inviato da Andre00
Prendete ad esempio mknod...

Voglio crearmi un dispositivo per il collegamento per il cellulare...

alura

man mknod

bella la spiegazione...
so tutto su character, block device major minor ecc..

eppoi come me lo creo sto pirla di dispositivo...

aggiungi un file lista device creabili con mknod ...cos'è occupa 50kb? E il gioco sarebbe fatto... ma no

Nel caso specifico di mknod la cosa e` sostanzialmente corretta cosi`.
O meglio, che non ci sia la lista delle associazioni device/major-minor e` sicuramente non sbagliato. Probabilmente subottimale, ma sicuramente non sbagliato.

Il punto e` che, come diceva piu` su ilmalcom, 'man' va interpretato letteralmente: 'manuale di riferimento'. Documenta cosa fa il comando XYZ, la relativa opzione --foo piuttosto che -k o -F o -p, ma qui si ferma il suo scopo.
Dire COSA si puo`, si deve, NON si puo`, NON si deve, si dovrebbe fare con un dato comando non e` compito del manuale di riferimento, ma di una guida, dispensa, tutorial, qualsiasi altra cosa che non e` appunto il manuale.

Mi viene in mente il manuale della macchina fotografica digitale di mia madre. Spiega quali batterie e schede di memoria usare, come si imposta il flash, come si collega al PC, a cosa servono i pulsanti etc. etc. Ma non contiene un corso di fotografia, salvo consigli talmente rarefatti e stringati da risultare poco degni di nota.

Al pari, il manuale d'uso e manutenzione della macchina elenca solo le norme di guida e -appunto- manutenzione minime necessarie, oltre che quelle necessarie per legge. Non contiene alcun riferimento o guida ad un corso di guida sportiva o particolarmente efficiente.

E, alla fine, e` giusto cosi`.
Potrebbe essere apprezzabile se queste cose ci fossero, o fosse indicato dove procurarsele; ma la loro assenza non e` sicuramente un'errore.

Torniamo al caso di mknod. Premesso che non e` responsabilita` dell'estensore della manpagina di mknod fornire le associazioni device/major-minor, e` anche sconsigliabile che detta manpagina le fornisca.
In primis tali associazioni possono variare nel tempo; possono addirittura perdere di significato nel tempo, come si discutevano tempo fa i kernel hacker a proposito della gestione automatica dei device.
Il posto giusto dove fornire tale associazione e`, come detto, tra la documentazione del kernel, dove infatti e`.
Per comodita` ulteriore e` comunque disponibile uno script, MAKEDEV, che semplifica tale creazione.

Se, e questo e` importate, l'esistenza del detto database di coppie device/major-minor e dello script MAKEDEV, NON e` segnalata nella pagina di manuale di mknod, questo si e` un'errore o comunque un'imprecisione da correggere.

scambi opinioni con qualcuno che ha "INVESTITO" 50 ore nella sua vita a sapere quali erano il major e minor number di /dev/rfcomm0 (che poi dovevo prima capire che era rfcomm0)

Idem anche qui: se non e` specificato che il device e` rfcommX nella documentazione del caso, questo e` uno sbaglio. Certo, sarebbe anche molto desiderabile che fossero direttamente documentati i major/minor da usare, o fosse spiegato come fare.

Non parliamo poi se uno dovesse mai usare linux per lavoro...

Come per tutte le cose, basta imparare a fare le cose secondo la giusta mentalita`. Certo, poi ci sono i difetti, e a volte ce ne sono di piu` e a volte meno, ma se uno sa usare solo il martello trovera` senz'altro "rognose" e "poco utili" le viti.

Faccio un esempio banale... quando abbiamo tutti imparato ad andare in bici...la bici aveva le ruote...si o no?
noi non sapevamo ancora andare senza mani e magari impennare...volevamo solo imparare ad andare in bici...ma se ce la davano da montare....per imparare anche solo a cadere ci passavano almeno 1 mese ...

Usare mknod equivale a montarsi le ruote da soli, a partire da mozzo, cerchione, raggi, camera d'aria e copertone separati, per la cronaca.

[edit]
Tutto cio` detto, trovo anch'io che la qualita` delle pagine di manuale, e anche della documentazione in genere, sotto linux sia generalmente migliorabile e che sarebbe necessario fare qualcosa prima che il problema diventi serio.
[/edit]

[Andre00]

A proposito della metafora della bicicletta mi aspettavo una risposta quale
mknod equivale però non solo ad andare in bici ma anche a montarsi le ruote...
Ma il punto non è forse che nel qual caso io prendessi il manuale del mozzo o della ruota...dovrei trovarci scritto come smontarlo e rismontarlo... ?

una misera illustrazione...
anche solo un esempietto....

Se compro la macchina fotografica digitale, nel manuale ci deve essere spiegato come usarla o no?
Non il corso di fotografia...ma come usarla..
allora a me piacerebbe esistesse un man di come usare almeno una prima volta quel dato comando..magari con le opzioni più usate e utili allo scopo..
due esempi e poi ci lavoro un po' con le altre opzioni da solo

Ps per colui che dice che potrei contribuire a migliorare le pagine....
io lo farei anche ma non credo di essere la persona più adatta a farlo... che ci metto io di più in man mknod ? quello che non so?
Pagine di quel tipo dovrebbero essere realizzate da chi davvero sa quasi tutto sull'argomento..se no ne viene fuori un mio man con l'avviso per gli altri...ci ho messo quel che sapevo... e molti rideranno di tutto ciò che ho omesso inconsciamente,,

La pagina del comando x... sarebbe meglio la stilasse l'autore, l'equipe ecc. del tal comando x...o no..?

in una certa maniera però, tale da mettere colui che per la prima volta si mette ad usare quel comando nella condizione di poterlo almeno usare e fare delle prove...

Voglio dire dovrebbe essere la politica dell'open source... desisero che tutti sappiano il più possibile..
Io ad esempio per conto mio mi sto giò facendo una specie di appunti di informatica libera su tutti i problemi dalla prima volta che ho installato linux ad adesso... se volete ve lo posto... ma vi assicuro che è incompleto è fara ridere qualcuno su tanti argomenti...è ovvio che sia così.. ma secondo me non deve essere così un manuale di riferimento...

Dite che sbaglio..?.e che ogni tanto mi trovo a dover affrontare dei problemi stupidissimi e ci perdi 50 ore e poi bastava mettere 2 esempi e ci arrivavi in 1 secondo...

Ti viene da dire .... ma che caz........

CIAO!!

anzi man-naggia..

[cacao74]

Originariamente inviato da Andre00
[cut]
anzi man-naggia..

Andre00, non ti stavo additando contro per divertimento!
Intendo dire che, prendendo l'esempio di 'mknod', dal mio punto di vista è chiarissimo, viene spiegato il suo utilizzo in modo, ehm, chiaro. Le informazioni che puoi passare a tale comando si trovano, giustamente (secondo me), in altri posti.
Ad esempio nella documentazione allegata al kernel, oppure nelle pagine di manuale alla sezione (4), /etc/MAKEDEV.
Hai già provato a leggere la pagina di manuale di 'man'?
E' fondamentale ed utilissima.
Poi una volta che avrai risolto con mknod, se lo ritieni opportuno, potresto aggiungere alla pagina di manuale qualche esempio e rendere disponibili alla comunità le tue idee.
Perche' mai ci sarebbe da deridere una persona che contribuisce alla documentazione? Potresti anche scrivere, chiedere all'autore l'inserzione di qualche esempio, ecc.
Questo voleva essere il senso del mio post, quello di non lamentarsi senza fare nulla, perchè cosi' non si muove niente.

ciao.

[Ikitt]

Originariamente inviato da Andre00
A proposito della metafora della bicicletta mi aspettavo una risposta quale
mknod equivale però non solo ad andare in bici ma anche a montarsi le ruote...

No no, mknod equivale solo a montarsi le ruote
Ma neanche a dire la verita`, teoricamente udev (o devfs) dovrebbe coprire un buon 75% delle esigenze.

Ma il punto non è forse che nel qual caso io prendessi il manuale del mozzo o della ruota...dovrei trovarci scritto come smontarlo e rismontarlo... ?

Si, tal manuale dovrebbe dire cosa va dove, il pezzo A si collega al pezzo B, non se usare il cacciavite o la chiave inglese...

E il manuale di mknod lo fa!
Se uno vuole creare la block device 8,19 dopo la lettura del manuale di mknod riesce a farlo...
Il punto che sollevi tu e`: ma se io voglio creare la device /dev/sdb3, come faccio a sapere che devo creare la block device 8,19?

Beh, questo e` un problema che non spetta alla documentazione di mknod risolvere.

Se compro la macchina fotografica digitale, nel manuale ci deve essere spiegato come usarla o no?
Non il corso di fotografia...ma come usarla..

Certo: premere il pulsante "A3" per scattare una foto, o premere "menu" per entrare nel menu interattivo...

allora a me piacerebbe esistesse un man di come usare almeno una prima volta quel dato comando..magari con le opzioni più usate e utili allo scopo..
due esempi e poi ci lavoro un po' con le altre opzioni da solo

Questo semplicemente non e` un man, se si cerca questo nel man mediamente si restara` delusi, ma questo pero` non e` un difetto del man (altri lo sono, come il poco aggiornamento e la poca precisione)...

[GiorgioM]

Originariamente inviato da weatherman
ma avete mai scritto una man page di un programma? una gran rottura di palle!

confermo!!!

[c montecristo]

secondo me infatti dovrebbero fare esempi pratici... e farla anche piu' user friendly di come lo e' adesso...

[Andre00]

ho aperto un uovo thread...

man live cd da zero

preso dai miei appunti di informatica ...

O fioi che ci volete fare... a me i manuali mi piacciono che abbiano il dono dell'immediatezza...

e che siano fatti a prova di ignorante quasi totale...

ma se uno copia quella roba li paro paro... vi assicuro che ottinene un live cd...

Però voi dite che è troppo per man?

Be forse si (un po' troppo prolisso) forse no...(a prova di stupido ma è così che si da l'oppurtunita di imparare a tutti)

CIAO!

[wolf64]

Io uso Linux da circa 4 anni, però una cosa di cui ho sempre sentito la mancanza in alcuni man, non tutti però, sono proprio gli esempi.

In questo senso do ragione a coloro che ritengono alcuni (ripeto, non tutti!) man carenti in tal senso, troppo spesso ho dovuto cercare degli esempi, e altrettanto spesso questi esempi erano abbastanza semplici! Alla fine metterne qualcuno in coda non sarebbe costato questo grande sforzo, non parlo di... raddoppiare il volume dello stesso man!!! ..ma magari di.. 3 o 4 righe in più....