Μπορείτε να χρησιμοποιήσετε το pandoc σε Linux για μετατροπή μεταξύ περισσότερων από 40 μορφών αρχείων. Μπορείτε επίσης να το χρησιμοποιήσετε για να δημιουργήσετε ένα απλό σύστημα doc-as-code γράφοντας στο Markdown, αποθηκεύοντας στο git και δημοσιεύοντας σε οποιαδήποτε από τις υποστηριζόμενες μορφές του.
Πίνακας περιεχομένων
Μετατροπή εγγράφου και Έγγραφα ως Κώδικας
Εάν έχετε ένα έγγραφο σε οποιοδήποτε από τα pandoc’s πολλές υποστηριζόμενες μορφές αρχείων, η μετατροπή του σε οποιοδήποτε από τα άλλα είναι μια δυσκολία. Αυτό είναι ένα εύχρηστο εργαλείο για να έχετε!
Αλλά η πραγματική δύναμη του pandoc γίνεται εμφανής όταν το χρησιμοποιείτε ως βάση ενός απλού συστήματος docs-as-code. Η αρχή του docs-as-code είναι να υιοθετήσει ορισμένες από τις τεχνικές και τις αρχές της ανάπτυξης λογισμικού και να τις εφαρμόσει στη συγγραφή τεκμηρίωσης, ειδικά για έργα ανάπτυξης λογισμικού. Ωστόσο, μπορείτε να το εφαρμόσετε στην ανάπτυξη οποιουδήποτε είδους τεκμηρίωσης.
Οι προγραμματιστές λογισμικού χρησιμοποιούν τον αγαπημένο τους επεξεργαστή ή ολοκληρωμένο περιβάλλον ανάπτυξης (IDE) για να γράψουν τα προγράμματά τους. Ο κώδικας που πληκτρολογούν αποθηκεύεται σε αρχεία κειμένου. Αυτά περιέχουν το πηγαίος κώδικας για το πρόγραμμα.
Χρησιμοποιούν α σύστημα ελέγχου έκδοσης, ή VCS (Git είναι το πιο δημοφιλές), για να καταγράψετε αλλαγές στον πηγαίο κώδικα καθώς αναπτύσσεται και βελτιώνεται. Αυτό σημαίνει ότι ο προγραμματιστής έχει ένα πλήρες ιστορικό όλων των εκδόσεων των αρχείων πηγαίου κώδικα. Αυτός ή αυτή μπορεί να έχει γρήγορη πρόσβαση σε οποιαδήποτε προηγούμενη έκδοση ενός αρχείου. Το Git αποθηκεύει αρχεία σε ένα αποθετήριο. Υπάρχει ένα τοπικό αποθετήριο στον υπολογιστή κάθε προγραμματιστή και ένα κεντρικό, κοινόχρηστο, απομακρυσμένο αποθετήριο που συχνά φιλοξενείται στο cloud.
Όταν είναι έτοιμοι να παράγουν μια λειτουργική έκδοση του προγράμματος, χρησιμοποιούν α μεταγλωττιστής για να διαβάσετε τον πηγαίο κώδικα και να δημιουργήσετε ένα δυαδικό εκτελέσιμο αρχείο.
Γράφοντας τα έγγραφά σας σε μια ελαφριά γλώσσα σήμανσης που βασίζεται σε κείμενο, μπορείτε να χρησιμοποιήσετε ένα VCS για τον έλεγχο έκδοσης της γραφής σας. Όταν είστε έτοιμοι να διανείμετε ή να δημοσιεύσετε ένα έγγραφο, μπορείτε να χρησιμοποιήσετε το pandoc για να δημιουργήσετε όσες διαφορετικές εκδόσεις της τεκμηρίωσής σας χρειάζεστε, συμπεριλαμβανομένης της διαδικτυακής (HTML), επεξεργασία κειμένου ή στοιχειοθέτηση (LibreOffice, Microsoft Word, TeX), φορητή μορφή εγγράφου (PDF), ηλεκτρονικό βιβλίο (ePub), και ούτω καθεξής.
Μπορείτε να τα κάνετε όλα αυτά από ένα σύνολο ελεγχόμενων από την έκδοση, ελαφρών αρχείων κειμένου.
Εγκατάσταση pandoc
Για να εγκαταστήσετε το pandoc στο Ubuntu, χρησιμοποιήστε αυτήν την εντολή:
sudo apt-get install pandoc
Στο Fedora, η εντολή που χρειάζεστε είναι η εξής:
sudo dnf install pandoc
Στο Manjaro, πρέπει να πληκτρολογήσετε:
sudo pacman -Syu pandoc
Μπορείτε να ελέγξετε ποια έκδοση έχετε εγκαταστήσει χρησιμοποιώντας την επιλογή –version:
pandoc --version
Χρήση του pandoc χωρίς αρχεία
Εάν χρησιμοποιείτε το pandoc χωρίς επιλογές γραμμής εντολών, δέχεται επίσης πληκτρολογημένη είσοδο. Απλώς πατάτε Ctrl+D για να υποδείξετε ότι έχετε ολοκληρώσει την πληκτρολόγηση. Το pandoc περιμένει από εσάς να πληκτρολογήσετε σε μορφή Markdown και δημιουργεί έξοδο HTML.
Ας δούμε ένα παράδειγμα:
pandoc
Πληκτρολογήσαμε μερικές γραμμές Markdown και πρόκειται να πατήσουμε Ctrl+D.
Μόλις το κάνουμε, το pandoc δημιουργεί την ισοδύναμη έξοδο HTML.
Ωστόσο, για να κάνουμε οτιδήποτε χρήσιμο με το pandoc, πρέπει πραγματικά να χρησιμοποιήσουμε αρχεία.
Βασικά στοιχεία Markdown
Η Markdown είναι μια ελαφριά γλώσσα σήμανσης και δίνεται ειδικό νόημα σε ορισμένους χαρακτήρες. Μπορείτε να χρησιμοποιήσετε ένα πρόγραμμα επεξεργασίας απλού κειμένου για να δημιουργήσετε ένα αρχείο Markdown.
Το Markdown μπορεί να διαβαστεί εύκολα, καθώς δεν υπάρχουν οπτικά δυσκίνητες ετικέτες που να αποσπούν την προσοχή από το κείμενο. Η μορφοποίηση στα έγγραφα Markdown μοιάζει με τη μορφοποίηση που αντιπροσωπεύει. Παρακάτω είναι μερικά από τα βασικά:
Για να δώσετε έμφαση στο κείμενο με πλάγιους χαρακτήρες, τυλίξτε το με αστερίσκους. *Αυτό θα τονιστεί*
Για έντονη γραφή, χρησιμοποιήστε δύο αστερίσκους. **Αυτό θα είναι με έντονους χαρακτήρες**
Οι επικεφαλίδες αντιπροσωπεύονται από το αριθμητικό σύμβολο/σήμα κατακερματισμού (#). Το κείμενο διαχωρίζεται από τον κατακερματισμό με ένα κενό. Χρησιμοποιήστε ένα κατακερματισμό για μια επικεφαλίδα ανώτατου επιπέδου, δύο για ένα δεύτερο επίπεδο και ούτω καθεξής.
Για να δημιουργήσετε μια λίστα με κουκκίδες, ξεκινήστε κάθε γραμμή της λίστας με έναν αστερίσκο και εισαγάγετε ένα κενό πριν από το κείμενο.
Για να δημιουργήσετε μια αριθμημένη λίστα, ξεκινήστε κάθε γραμμή με ένα ψηφίο ακολουθούμενο από μια τελεία και, στη συνέχεια, εισαγάγετε ένα κενό πριν από το κείμενο.
Για να δημιουργήσετε έναν υπερσύνδεσμο, περικλείστε το όνομα του ιστότοπου σε αγκύλες ([]), και τη διεύθυνση URL σε παρένθεση [()] όπως έτσι: [Link to How to Geek](https://www.wdzwdz.com/).
Για να εισαγάγετε μια εικόνα, πληκτρολογήστε ένα θαυμαστικό αμέσως πριν από τις αγκύλες (![]). Πληκτρολογήστε οποιοδήποτε εναλλακτικό κείμενο για την εικόνα στις αγκύλες. Στη συνέχεια, περικλείστε τη διαδρομή προς την εικόνα σε παρένθεση [()“]. Ιδού ένα παράδειγμα: .
Θα καλύψουμε περισσότερα παραδείγματα όλων αυτών στην επόμενη ενότητα.
Μετατροπή αρχείων
Οι μετατροπές αρχείων είναι απλές. Το pandoc μπορεί συνήθως να βρει τις μορφές αρχείων με τις οποίες εργάζεστε από τα ονόματα των αρχείων τους. Εδώ, θα δημιουργήσουμε ένα αρχείο HTML από ένα αρχείο Markdown. Η επιλογή -o (έξοδος) λέει στο pandoc το όνομα του αρχείου που θέλουμε να δημιουργήσουμε:
pandoc -o sample.html sample.md
Το δείγμα του αρχείου Markdown, sample.md, περιέχει τη σύντομη ενότητα του Markdown που φαίνεται στην παρακάτω εικόνα.
Δημιουργείται ένα αρχείο που ονομάζεται sample.html. Όταν κάνουμε διπλό κλικ στο αρχείο, το προεπιλεγμένο πρόγραμμα περιήγησής μας θα το ανοίξει.
Τώρα, ας δημιουργήσουμε ένα Ανοίξτε τη Μορφή εγγράφου έγγραφο κειμένου στο οποίο μπορούμε να ανοίξουμε LibreOffice Writer:
pandoc -o sample.odt sample.md
Το αρχείο ODT έχει το ίδιο περιεχόμενο με το αρχείο HTML.
Ένα καθαρό άγγιγμα είναι το εναλλακτικό κείμενο για την εικόνα που χρησιμοποιείται επίσης για την αυτόματη δημιουργία λεζάντας για τη φιγούρα.
Καθορισμός μορφών αρχείων
Οι επιλογές -f (από) και -t (προς) χρησιμοποιούνται για να πείτε στο pandoc ποιες μορφές αρχείων θέλετε να μετατρέψετε από και προς. Αυτό μπορεί να είναι χρήσιμο εάν εργάζεστε με μια μορφή αρχείου που μοιράζεται μια επέκταση αρχείου με άλλες σχετικές μορφές. Για παράδειγμα, TeX, και Κόμμι και οι δύο χρησιμοποιούν την επέκταση “.tex”.
Χρησιμοποιούμε επίσης την επιλογή -s (αυτόνομο), ώστε το pandoc να δημιουργήσει όλο το προοίμιο LaTeX που απαιτείται για ένα έγγραφο να είναι ένα πλήρες, αυτόνομο και καλά διαμορφωμένο έγγραφο LaTeX. Χωρίς την επιλογή -s (αυτόνομο), η έξοδος θα εξακολουθούσε να είναι καλά διαμορφωμένο LaTeX που θα μπορούσε να τοποθετηθεί σε άλλο έγγραφο LaTeX, δεν θα αναλύονταν σωστά ως αυτόνομο έγγραφο LaTeX.
Πληκτρολογούμε τα εξής:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Εάν ανοίξετε το αρχείο “sample.tex” σε ένα πρόγραμμα επεξεργασίας κειμένου, θα δείτε το LaTeX που δημιουργήθηκε. Εάν διαθέτετε πρόγραμμα επεξεργασίας LaTeX, μπορείτε να ανοίξετε το αρχείο TEX για να δείτε μια προεπισκόπηση του τρόπου ερμηνείας των εντολών στοιχειοθεσίας LaTeX. Η συρρίκνωση του παραθύρου για να ταιριάζει στην παρακάτω εικόνα έκανε την οθόνη να φαίνεται στενή, αλλά, στην πραγματικότητα, ήταν μια χαρά.
Χρησιμοποιήσαμε έναν επεξεργαστή LaTeX που ονομάζεται Texmaker. Εάν θέλετε να το εγκαταστήσετε στο Ubuntu, πληκτρολογήστε τα εξής:
sudo apt-get install texmaker
Στο Fedora, η εντολή είναι:
sudo dnf install texmaker
Στο Manjaro, χρησιμοποιήστε:
sudo pacman -Syu texmaker
Μετατροπή αρχείων με πρότυπα
Πιθανότατα αρχίζετε να καταλαβαίνετε την ευελιξία που παρέχει το pandoc. Μπορείτε να γράψετε μία φορά και να δημοσιεύσετε σχεδόν σε οποιαδήποτε μορφή. Αυτό είναι ένα μεγάλο κατόρθωμα, αλλά τα έγγραφα φαίνονται λίγο βανίλια.
Με τα πρότυπα, μπορείτε να υπαγορεύσετε ποια στυλ χρησιμοποιεί το pandoc όταν δημιουργεί έγγραφα. Για παράδειγμα, μπορείτε να πείτε στο pandoc να χρησιμοποιεί τα στυλ που ορίζονται στο α Cascading Style Sheets (CSS) με την επιλογή –css.
Δημιουργήσαμε ένα μικρό αρχείο CSS που περιέχει το παρακάτω κείμενο. Αλλάζει το διάστημα πάνω και κάτω από την κεφαλίδα επιπέδου ένα στυλ. Αλλάζει επίσης το χρώμα του κειμένου σε λευκό και το χρώμα του φόντου σε μια απόχρωση του μπλε:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Η πλήρης εντολή είναι παρακάτω—σημειώστε ότι χρησιμοποιήσαμε επίσης την αυτόνομη επιλογή (-s):
pandoc -o sample.html -s --css sample.css sample.md
Το pandoc χρησιμοποιεί το μοναδικό στυλ από το μινιμαλιστικό μας αρχείο CSS και το εφαρμόζει στην κεφαλίδα επιπέδου ένα.
Μια άλλη επιλογή λεπτομέρειας που έχετε διαθέσιμη όταν εργάζεστε με αρχεία HTML είναι να συμπεριλάβετε τη σήμανση HTML στο αρχείο Markdown. Αυτό θα περάσει στο αρχείο HTML που δημιουργήθηκε ως τυπική σήμανση HTML.
Ωστόσο, αυτή η τεχνική θα πρέπει να προορίζεται για όταν δημιουργείτε μόνο έξοδο HTML. Εάν εργάζεστε με πολλές μορφές αρχείων, το pandoc θα αγνοήσει τη σήμανση HTML για αρχεία που δεν είναι HTML και θα μεταβιβαστεί σε αυτά ως κείμενο.
Μπορούμε επίσης να καθορίσουμε ποια στυλ χρησιμοποιούνται όταν δημιουργούνται αρχεία ODT. Ανοίξτε ένα κενό έγγραφο του LibreOffice Writer και προσαρμόστε την επικεφαλίδα και τα στυλ γραμματοσειράς ανάλογα με τις ανάγκες σας. Στο παράδειγμά μας, προσθέσαμε επίσης μια κεφαλίδα και ένα υποσέλιδο. Αποθηκεύστε το έγγραφό σας ως “odt-template.odt”.
Μπορούμε τώρα να το χρησιμοποιήσουμε ως πρότυπο με την επιλογή –reference-doc:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Συγκρίνετε αυτό με το παράδειγμα ODT από το προηγούμενο. Αυτό το έγγραφο χρησιμοποιεί διαφορετική γραμματοσειρά, έχει χρωματιστές επικεφαλίδες και περιλαμβάνει κεφαλίδες και υποσέλιδα. Ωστόσο, δημιουργήθηκε από το ίδιο ακριβώς αρχείο Markdown “sample.md”.
Τα πρότυπα εγγράφων αναφοράς μπορούν να χρησιμοποιηθούν για να υποδεικνύονται διαφορετικά στάδια της παραγωγής ενός εγγράφου. Για παράδειγμα, μπορεί να έχετε πρότυπα που έχουν υδατογραφήματα “Πρόχειρο” ή “Για έλεγχο”. Ένα πρότυπο χωρίς υδατογράφημα θα χρησιμοποιηθεί για ένα οριστικό έγγραφο.
Δημιουργία PDF
Από προεπιλογή, το pandoc χρησιμοποιεί τη μηχανή LaTeX PDF για τη δημιουργία αρχείων PDF. Ο ευκολότερος τρόπος για να βεβαιωθείτε ότι έχετε ικανοποιήσει τις κατάλληλες εξαρτήσεις LaTeX είναι να εγκαταστήσετε ένα πρόγραμμα επεξεργασίας LaTeX, όπως το Texmaker.
Αυτή είναι μια πολύ μεγάλη εγκατάσταση, ωστόσο – το Tex και το LaTeX είναι και τα δύο αρκετά βαριά. Εάν ο χώρος στον σκληρό σας δίσκο είναι περιορισμένος ή εάν γνωρίζετε ότι δεν θα χρησιμοποιήσετε ποτέ TeX ή LaTeX, ίσως προτιμήσετε να δημιουργήσετε ένα αρχείο ODT. Στη συνέχεια, μπορείτε απλώς να το ανοίξετε στο LibreOffice Writer και να το αποθηκεύσετε ως PDF.
Docs-as-Code
Υπάρχουν πολλά πλεονεκτήματα από τη χρήση της Markdown ως γλώσσας γραφής, συμπεριλαμβανομένων των εξής:
Η εργασία σε αρχεία απλού κειμένου είναι γρήγορη: Φορτώνουν γρηγορότερα από αρχεία επεξεργασίας κειμένου παρόμοιου μεγέθους και τείνουν επίσης να μετακινούνται πιο γρήγορα μέσα στο έγγραφο. Πολλοί συντάκτες, συμπεριλαμβανομένων των gedit , Vim και Emacs, χρησιμοποιούν επισήμανση σύνταξης με κείμενο Markdown.
Θα έχετε ένα χρονοδιάγραμμα για όλες τις εκδόσεις των εγγράφων σας: Εάν αποθηκεύετε την τεκμηρίωσή σας σε ένα VCS, όπως το Git, μπορείτε εύκολα να δείτε τις διαφορές μεταξύ οποιωνδήποτε δύο εκδόσεων του ίδιου αρχείου. Ωστόσο, αυτό λειτουργεί πραγματικά μόνο όταν τα αρχεία είναι απλού κειμένου, καθώς αυτό περιμένει να λειτουργήσει ένα VCS.
Ένα VCS μπορεί να καταγράψει ποιος έκανε αλλαγές και πότε: Αυτό είναι ιδιαίτερα χρήσιμο εάν συνεργάζεστε συχνά με άλλους σε μεγάλα έργα. Παρέχει επίσης ένα κεντρικό αποθετήριο για τα ίδια τα έγγραφα. Πολλές υπηρεσίες Git που φιλοξενούνται στο cloud, όπως το GitHub, GitLab, και BitBucket, έχουν δωρεάν επίπεδα στα μοντέλα τιμολόγησης τους.
Μπορείτε να δημιουργήσετε τα έγγραφά σας σε πολλές μορφές: Με μερικά απλά σενάρια φλοιού, μπορείτε να τραβήξετε τα στυλ από το CSS και τα έγγραφα αναφοράς. Εάν αποθηκεύετε τα έγγραφά σας σε αποθετήριο VCS που ενσωματώνεται με Συνεχής ενσωμάτωση και συνεχής ανάπτυξη πλατφόρμες (CI/CD), μπορούν να δημιουργηθούν αυτόματα κάθε φορά που κατασκευάζεται το λογισμικό.
Τελικές σκέψεις
Υπάρχουν πολλές περισσότερες επιλογές και δυνατότητες μέσα παντοκ από αυτό που καλύψαμε εδώ. Οι διαδικασίες μετατροπής για τους περισσότερους τύπους αρχείων μπορούν να τροποποιηθούν και να βελτιωθούν. Για να μάθετε περισσότερα, ρίξτε μια ματιά στα εξαιρετικά παραδείγματα στο επίσημο (και εξαιρετικά λεπτομερές) ιστοσελίδα pandoc.