Πώς να δημιουργήσετε μια σελίδα ανθρώπου στο Linux

Θέλετε το νέο σας πρόγραμμα Linux να φαίνεται επαγγελματικό; Δώστε του μια σελίδα ανθρώπου. Θα σας δείξουμε τον πιο εύκολο και γρήγορο τρόπο να το κάνετε.

Ο άνθρωπος Σελίδες

Υπάρχει ένας πυρήνας αλήθειας στο παλιό αστείο του Unix, «το μόνο εντολή που χρειάζεστε να ξέρεις είναι άνθρωπος». Οι σελίδες man περιέχουν πλήθος γνώσεων και θα πρέπει να είναι το πρώτο μέρος που γυρίζετε όταν θέλετε να μάθετε για μια εντολή.

Η παροχή μιας σελίδας man για ένα βοηθητικό πρόγραμμα ή εντολή που έχετε γράψει την ανυψώνει από ένα χρήσιμο κομμάτι κώδικα σε ένα πλήρως διαμορφωμένο πακέτο Linux. Οι άνθρωποι περιμένουν να παρέχεται μια σελίδα ανθρώπου για ένα πρόγραμμα που έχει γραφτεί για Linux. Εάν υποστηρίζετε εγγενώς το Linux, μια σελίδα man είναι υποχρεωτική εάν θέλετε να ληφθεί σοβαρά υπόψη το πρόγραμμά σας.

Ιστορικά, οι σελίδες man έχουν γραφτεί χρησιμοποιώντας ένα σύνολο μακροεντολών μορφοποίησης. Όταν καλείς τον άνθρωπο να ανοίξει μια σελίδα, καλεί το γκροφ διαβάστε το αρχείο και δημιουργήστε μορφοποιημένη έξοδο, σύμφωνα με τις μακροεντολές στο αρχείο. Η έξοδος διοχετεύεται σε λιγότερα, και στη συνέχεια εμφανίζεται για εσάς.

Αν δεν δημιουργείτε συχνά σελίδες man, η σύνταξη μιας και η μη αυτόματη εισαγωγή των μακροεντολών είναι σκληρή δουλειά. Η πράξη της δημιουργίας μιας σελίδας ανθρώπου που αναλύει σωστά και φαίνεται σωστά μπορεί να ξεπεράσει τον στόχο σας να παρέχετε μια συνοπτική, αλλά ενδελεχή περιγραφή της εντολής σας.

Θα πρέπει να επικεντρωθείτε στο περιεχόμενό σας, όχι να παλεύετε με ένα σκοτεινό σύνολο μακροεντολών.

πανδόκ στη διάσωση

ο πρόγραμμα pandoc διαβάζει αρχεία σήμανσης και δημιουργεί νέα σε περίπου 40 διαφορετικές γλώσσες σήμανσης και μορφές εγγράφων, συμπεριλαμβανομένου αυτού της σελίδας man. Μεταμορφώνει πλήρως τη διαδικασία γραφής man page, ώστε να μην χρειάζεται να παλεύετε με ιερογλυφικά.

Για να ξεκινήσετε, μπορείτε να εγκαταστήσετε το pandoc στο Ubuntu με αυτήν την εντολή:

sudo apt-get install pandoc

Στο Fedora, η εντολή που χρειάζεστε είναι η εξής:

sudo dnf install pandoc

Στο Manjaro, πληκτρολογήστε:

sudo pacman -Syu pandoc

Τμήματα ενός ανθρώπου Σελίδα

Οι σελίδες man περιέχουν ενότητες που ακολουθούν μια τυπική σύμβαση ονομασίας. Οι ενότητες που χρειάζεται η σελίδα man σας υπαγορεύονται από την πολυπλοκότητα της εντολής που περιγράφετε.

Τουλάχιστον, οι περισσότερες σελίδες man περιέχουν αυτές τις ενότητες:

Όνομα: Το όνομα της εντολής και ένα pithy one-liner που περιγράφει τη λειτουργία της.
Σύνοψη: Μια συνοπτική περιγραφή των επικλήσεων που μπορεί να χρησιμοποιήσει κάποιος για να ξεκινήσει το πρόγραμμα. Αυτά δείχνουν τους τύπους των αποδεκτών παραμέτρων της γραμμής εντολών.
Περιγραφή: Περιγραφή της εντολής ή της συνάρτησης.
Επιλογές: Μια λίστα επιλογών της γραμμής εντολών και τι κάνουν.
Παραδείγματα: Μερικά παραδείγματα κοινής χρήσης.
Τιμές εξόδου: Οι πιθανοί κωδικοί επιστροφής και οι σημασίες τους.
Σφάλματα: Μια λίστα με γνωστά σφάλματα και ιδιορρυθμίες. Μερικές φορές, αυτό συμπληρώνεται (ή αντικαθίσταται από) με έναν σύνδεσμο προς την εφαρμογή παρακολούθησης ζητημάτων για το έργο.
Συγγραφέας: Το άτομο ή τα άτομα που έγραψαν την εντολή.
Πνευματικά δικαιώματα: Το μήνυμά σας για τα πνευματικά δικαιώματα. Αυτά συνήθως περιλαμβάνουν επίσης τον τύπο άδειας χρήσης βάσει της οποίας κυκλοφορεί το πρόγραμμα.

Αν κοιτάξετε μερικές από τις πιο περίπλοκες σελίδες man, θα δείτε ότι υπάρχουν και πολλές άλλες ενότητες. Για παράδειγμα, δοκιμάστε το man man. Δεν χρειάζεται να τα συμπεριλάβετε όλα, ωστόσο, μόνο αυτά που χρειάζεστε πραγματικά. Οι σελίδες man δεν είναι μέρος για λόγια.

Μερικές άλλες ενότητες που θα βλέπετε αρκετά συχνά είναι:

Δείτε επίσης: Άλλες εντολές που σχετίζονται με το θέμα κάποιοι θα θεωρούσαν χρήσιμες ή σχετικές.
Αρχεία: Μια λίστα με αρχεία που περιλαμβάνονται στο πακέτο.
Προειδοποιήσεις: Άλλα σημεία που πρέπει να γνωρίζετε ή να προσέχετε.
Ιστορικό: Ένα ιστορικό αλλαγών για την εντολή.

Ενότητες του Εγχειριδίου

Το εγχειρίδιο Linux αποτελείται από όλες τις σελίδες man, οι οποίες στη συνέχεια χωρίζονται σε αυτές τις αριθμημένες ενότητες:

Εκτελέσιμα προγράμματα: Ή, εντολές φλοιού.
Κλήσεις συστήματος: Λειτουργίες που παρέχονται από τον πυρήνα.
Κλήσεις βιβλιοθήκης: Λειτουργίες εντός βιβλιοθηκών προγραμμάτων.
Ειδικά αρχεία.
Μορφές και συμβάσεις αρχείων: Για παράδειγμα, “/etc/passwd”.
Παιχνίδια.
Διάφορα: Πακέτα μακροεντολών και συμβάσεις, όπως groff.
Εντολές διαχείρισης συστήματος: Συνήθως δεσμεύεται για root.
Ρουτίνες πυρήνα: Συνήθως δεν εγκαθίστανται από προεπιλογή.

Κάθε σελίδα χρήστη πρέπει να υποδεικνύει σε ποια ενότητα ανήκει και πρέπει επίσης να αποθηκευτεί στην κατάλληλη θέση για αυτήν την ενότητα, όπως θα δούμε στη συνέχεια. Οι σελίδες man για εντολές και βοηθητικά προγράμματα ανήκουν στην ενότητα ένα.

Η μορφή ενός άνδρα Σελίδα

Η μορφή μακροεντολής groff δεν είναι εύκολο να αναλυθεί οπτικά. Αντίθετα, το markdown είναι ένα αεράκι.

Παρακάτω είναι μια σελίδα ανθρώπου σε groff.

Η ίδια σελίδα φαίνεται παρακάτω σε σημάδι κάτω.

Μπροστινό θέμα

Οι τρεις πρώτες γραμμές σχηματίζουν κάτι που ονομάζεται μπροστινή ύλη. Όλα αυτά πρέπει να ξεκινούν με ένα σύμβολο ποσοστού (%), χωρίς προηγούμενα κενά, αλλά ένα μετά, ακολουθούμενα από:

Η πρώτη γραμμή: Περιέχει το όνομα της εντολής, ακολουθούμενη από την ενότητα manual σε παρένθεση, χωρίς κενά. Το όνομα γίνεται το αριστερό και το δεξί τμήμα της κεφαλίδας της σελίδας man. Κατά σύμβαση, το όνομα της εντολής είναι με κεφαλαία, αν και θα βρείτε πολλά που δεν είναι. Οτιδήποτε ακολουθεί το όνομα της εντολής και τον αριθμό της μη αυτόματης ενότητας γίνεται το αριστερό τμήμα του υποσέλιδου. Είναι βολικό να το χρησιμοποιήσετε για τον αριθμό έκδοσης λογισμικού.
Η δεύτερη γραμμή: Τα ονόματα του/των συγγραφέα/ών. Αυτά εμφανίζονται σε μια ενότητα συντακτών που δημιουργείται αυτόματα στη σελίδα man. Δεν χρειάζεται να προσθέσετε μια ενότητα “Συντάκτες”—απλώς συμπεριλάβετε τουλάχιστον ένα όνομα εδώ.
Η τρίτη γραμμή: Η ημερομηνία, η οποία γίνεται επίσης το κεντρικό τμήμα του υποσέλιδου.

Ονομα

Οι ενότητες υποδεικνύονται με γραμμές που ξεκινούν με ένα αριθμητικό σύμβολο (#), το οποίο είναι η σήμανση που υποδεικνύει μια κεφαλίδα στη σήμανση. Το αριθμητικό σύμβολο (#) πρέπει να είναι ο πρώτος χαρακτήρας στη γραμμή, ακολουθούμενο από ένα κενό.

Η ενότητα ονόματος περιέχει μια γρήγορη γραμμή που περιλαμβάνει το όνομα της εντολής, ένα κενό διάστημα, μια παύλα (-), ένα διάστημα και, στη συνέχεια, μια πολύ σύντομη περιγραφή του τι κάνει η εντολή.

Σύνοψη

Η σύνοψη περιέχει τις διαφορετικές μορφές που μπορεί να λάβει η γραμμή εντολών. Αυτή η εντολή μπορεί να δεχθεί ένα μοτίβο αναζήτησης ή μια επιλογή γραμμής εντολών. Οι δύο αστερίσκοι (**) σε κάθε πλευρά του ονόματος της εντολής σημαίνουν ότι το όνομα θα εμφανίζεται με έντονους χαρακτήρες στη σελίδα man. Ένας μόνο αστερίσκος

και στις δύο πλευρές κάποιου κειμένου κάνει τη σελίδα man να το εμφανίζει υπογραμμισμένο.

Από προεπιλογή, μια αλλαγή γραμμής ακολουθείται από μια κενή γραμμή. Για να αναγκάσετε ένα σκληρό διάλειμμα χωρίς κενή γραμμή, μπορείτε να χρησιμοποιήσετε μια πίσω κάθετο ().

Περιγραφή

Η περιγραφή εξηγεί τι κάνει η εντολή ή το πρόγραμμα. Θα πρέπει να καλύπτει συνοπτικά τις σημαντικές λεπτομέρειες. Θυμηθείτε, δεν γράφετε έναν οδηγό χρήστη.

Η χρήση δύο αριθμητικών σημάτων (##) στην αρχή μιας γραμμής δημιουργεί μια επικεφαλίδα επιπέδου δύο. Μπορείτε να τα χρησιμοποιήσετε για να σπάσετε την περιγραφή σας σε μικρότερα κομμάτια.

Επιλογές

Η ενότητα επιλογών περιέχει μια περιγραφή τυχόν επιλογών γραμμής εντολών που μπορούν να χρησιμοποιηθούν με την εντολή. Κατά σύμβαση, εμφανίζονται με έντονους χαρακτήρες, επομένως συμπεριλάβετε δύο αστερίσκους (**) πριν και μετά από αυτούς. Συμπεριλάβετε την περιγραφή κειμένου των επιλογών στην επόμενη γραμμή και ξεκινήστε την με άνω και κάτω τελεία (:), ακολουθούμενη από ένα κενό.

Εάν η περιγραφή είναι αρκετά σύντομη, ο άνθρωπος θα την εμφανίσει στην ίδια γραμμή με την επιλογή της γραμμής εντολών. Εάν είναι πολύ μεγάλο, εμφανίζεται ως μια παράγραφο με εσοχή που ξεκινά στη γραμμή κάτω από την επιλογή της γραμμής εντολών.

Παραδείγματα

Η ενότητα των παραδειγμάτων περιέχει μια επιλογή διαφορετικών μορφών γραμμής εντολών. Σημειώστε ότι ξεκινάμε τις γραμμές περιγραφής με άνω και κάτω τελεία (:), όπως κάναμε και στην ενότητα επιλογών.

Τιμές εξόδου

Αυτή η ενότητα παραθέτει τις τιμές που επιστρέφει η εντολή σας στη διαδικασία κλήσης. Αυτό μπορεί να είναι το κέλυφος εάν το καλέσατε από τη γραμμή εντολών ή ένα σενάριο εάν το εκκινήσετε από ένα σενάριο φλοιού. Ξεκινάμε τις γραμμές περιγραφής με άνω και κάτω τελεία (:) και σε αυτήν την ενότητα.

Σφάλματα

Η ενότητα σφαλμάτων παραθέτει γνωστά σφάλματα, παραξενιές ή παραξενιές που πρέπει να γνωρίζουν οι άνθρωποι. Για έργα ανοιχτού κώδικα, είναι σύνηθες να συμπεριλάβετε εδώ έναν σύνδεσμο προς την παρακολούθηση προβλημάτων του έργου για να ελέγξετε την κατάσταση τυχόν σφαλμάτων ή να αναφέρετε νέα.

Πνευματική ιδιοκτησία

Η ενότητα πνευματικών δικαιωμάτων περιέχει τη δήλωση πνευματικών δικαιωμάτων σας και, συνήθως, μια περιγραφή του τύπου άδειας χρήσης βάσει της οποίας κυκλοφορεί το λογισμικό.

Μια αποτελεσματική ροή εργασίας

Μπορείτε να επεξεργαστείτε τη σελίδα ανθρώπου στον αγαπημένο σας επεξεργαστή. Οι περισσότεροι που υποστηρίζουν την επισήμανση σύνταξης θα γνωρίζουν τη σήμανση και το χρώμα του κειμένου για την επισήμανση των επικεφαλίδων, καθώς και την έντονη γραφή και την υπογράμμισή του. Αυτό είναι υπέροχο όσο πάει, αλλά δεν κοιτάτε μια rendered man page, που είναι η πραγματική απόδειξη στην πουτίγκα.

pandoc ms.1.md -s -t man | /usr/bin/man -l -

Ανοίξτε ένα παράθυρο τερματικού στον κατάλογο που περιέχει το αρχείο σήμανσης. Με ανοιχτό στο πρόγραμμα επεξεργασίας, αποθηκεύετε περιοδικά το αρχείο σας στον σκληρό σας δίσκο. Κάθε φορά που το κάνετε, μπορείτε να εκτελέσετε την ακόλουθη εντολή στο παράθυρο του τερματικού:

Αφού χρησιμοποιήσετε αυτήν την εντολή, μπορείτε να πατήσετε το επάνω βέλος για να την επαναλάβετε και, στη συνέχεια, πατήστε Enter.

Αυτή η εντολή καλεί επίσης το pandoc στο αρχείο markdown (εδώ, ονομάζεται “ms.1.md”):
Η επιλογή -s (αυτόνομη) δημιουργεί μια πλήρη σελίδα χρήστη από πάνω προς τα κάτω, αντί απλώς κάποιο κείμενο σε μορφή man.

Η επιλογή -t (τύπος εξόδου) με τον τελεστή “man” λέει στο pandoc να δημιουργήσει την έξοδο του σε μορφή man. Δεν έχουμε πει στο pandoc να στείλει την έξοδο του σε ένα αρχείο, επομένως θα σταλεί στο stdout.

Διοχετεύουμε επίσης αυτή την έξοδο στον άνθρωπο με την επιλογή -l (τοπικό αρχείο). Λέει στον άνθρωπο να μην κάνει αναζήτηση μέσω της βάσης δεδομένων man αναζητώντας τη σελίδα man. Αντίθετα, θα πρέπει να ανοίξει το αρχείο με το όνομα. Εάν το όνομα αρχείου είναι -, ο man θα λάβει την είσοδό του από το stdin.

Αυτό συνοψίζεται στο ότι μπορείτε να αποθηκεύσετε από το πρόγραμμα επεξεργασίας σας και να πατήσετε Q για να κλείσετε τον χρήστη εάν εκτελείται στο παράθυρο του τερματικού. Στη συνέχεια, μπορείτε να πατήσετε το επάνω βέλος, ακολουθούμενο από το Enter για να δείτε μια αποδοθείσα έκδοση της σελίδας man, ακριβώς μέσα στον άνθρωπο.

Δημιουργία της σελίδας του άντρα σας

pandoc ms.1.md -s -t man -o ms.1

Αφού ολοκληρώσετε τη σελίδα man, πρέπει να δημιουργήσετε μια τελική έκδοση και, στη συνέχεια, να την εγκαταστήσετε στο σύστημά σας. Η ακόλουθη εντολή λέει στο pandoc να δημιουργήσει μια σελίδα ανθρώπου που ονομάζεται “ms.1”:

Αυτό ακολουθεί τη σύμβαση της ονομασίας της σελίδας man μετά την εντολή που περιγράφει και της προσθήκης του αριθμού ενότητας του εγχειριδίου σαν να επρόκειτο για επέκταση αρχείου.

manpath

Αυτό δημιουργεί ένα αρχείο “ms.1”, το οποίο είναι η νέα μας σελίδα man. Που το βάζουμε; Αυτή η εντολή θα μας πει πού αναζητά ο άνθρωπος σελίδες man:

Τα αποτελέσματα μας δίνουν τις ακόλουθες πληροφορίες:
/usr/share/man: Η θέση της τυπικής βιβλιοθήκης των σελίδων man. Δεν προσθέτουμε σελίδες σε αυτήν τη βιβλιοθήκη.
/usr/local/share/man: Αυτός ο συμβολικός σύνδεσμος οδηγεί στο “/usr/local/man”.

/usr/local/man: Εδώ πρέπει να τοποθετήσουμε τη νέα μας σελίδα man.

Σημειώστε ότι οι διαφορετικές ενότητες του εγχειριδίου περιέχονται στους δικούς τους καταλόγους: man1, man2, man3 και ούτω καθεξής. Εάν ο κατάλογος για την ενότητα δεν υπάρχει, πρέπει να τον δημιουργήσουμε.

sudo mkdir /usr/local/man/man1

Για να το κάνουμε αυτό, πληκτρολογούμε τα εξής:

sudo cp ms.1 /usr/local/man/man1

Στη συνέχεια, αντιγράφουμε το αρχείο “ms.1” στον σωστό κατάλογο: Ο άνθρωπος περιμένει ότι οι σελίδες man θα συμπιεστούν, επομένως θα χρησιμοποιήσουμε gzipνα το συμπιέσει

sudo gzip /usr/local/man/man1/ms.1

:

sudo mandb

Για να κάνετε τον χρήστη να προσθέσει το νέο αρχείο στη βάση δεδομένων του, πληκτρολογήστε τα εξής:

man ms

Αυτό είναι! Μπορούμε τώρα να καλέσουμε τη νέα μας σελίδα ανθρώπου όπως οποιαδήποτε άλλη πληκτρολογώντας:

Βρέθηκε και εμφανίζεται η νέα μας σελίδα ανθρώπου.

Μοιάζει όπως κάθε άλλη σελίδα ανθρώπου, με έντονο, υπογραμμισμένο και εσοχή κείμενο στα κατάλληλα σημεία.

Οι γραμμές περιγραφής που ταιριάζουν δίπλα στην επιλογή που περιγράφουν εμφανίζονται στην ίδια γραμμή. Οι γραμμές που είναι πολύ μεγάλες για να χωρέσουν εμφανίζονται κάτω από την επιλογή που περιγράφουν.

Επίσης, δημιουργήσαμε αυτόματα μια ενότητα “Συγγραφείς”. Το υποσέλιδο περιλαμβάνει επίσης τον αριθμό έκδοσης του λογισμικού, την ημερομηνία και το όνομα της εντολής, όπως ορίζονται στο μπροστινό μέρος.

Αν θέλεις . . .