search

ioniodi / site-gr

Moved to ioniodi/sitegr
https://vibrant-haibt-349f89.netlify.com
The Unlicense
3 stars 24 forks source link

Wiki: Διαχείριση της βιβλιογραφίας των courses #137

Closed p15zerv closed 4 years ago

p15zerv commented 4 years ago

Δήλωση Θέματος

Υπενθυμίσεις

p15zerv commented 4 years ago

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

Γενικά Στοιχεία και Τεχνολογίες

Η βιβλιογραφία εμφανίζεται σε κάθε course για τα βιβλία που προτείνονται από το αντίστοιχο μάθημα. Κάθε αναφορά σε βιβλίο στα courses συνοδεύεται από ένα link στη σελίδα κάθε βιβλίου, όπου παρατίθενται αναλυτικά τα στοιχεία του.

Η διαχείριση της βιβλιογραφίας, ώστε να είναι ευκολότερη η παραπάνω λειτουργικότητα, γίνεται μέσω του BibTeX. Η τεχνολογία αυτή συχνά χρησιμοποιείται με το εργαλείο LaTeX και είναι ειδικά σχεδιασμένη για επεξεργασία και διαχείριση βιβλιογραφικού περιεχομένου. Για να είναι δυνατή η χρήση του BibTeX στο Jekyll χρησιμοποιείται το gem jekyll-scholar.

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

Δομή ενός BibTeX Αρχείου

Το BibTeX χρησιμοποιεί συγκεκριμένο τρόπο αναπαράστασης των δεδομένων σε αρχεία με κατάληξη .bib. Η δομή ενός .bib είναι σχετικά σύνθετη, αν και μοιάζει λίγο με τον αρκετά πιο διαδεδομένο τύπο αρχείων .json. Παράδειγμα μιας τυπικής εγγραφής ενός .bib αρχείου:

@book{unique_book_id,
  author    = {Peter Babington}, 
  title     = {The title of the work},
  publisher = {The name of the publisher},
  year      = 1993,
  volume    = 4,
  series    = 10,
  address   = {The address},
  edition   = 3,
  month     = 7,
  note      = {An optional note},
  isbn      = {3257227892}
}

Ένα .bib αρχείο αποτελείται συνήθως από πολλές τέτοιες εγγραφές. Το @book υποδηλώνει ότι η συγκεκριμένη εγγραφή αφορά βιβλίο. Επίσης, το (μοναδικό!) αναγνωριστικό ενός βιβλίου στη συλλογή μας δηλώνεται αμέσως μετά το @book{, δηλαδή εδώ το αναγνωριστικό είναι unique_book_id. Για ένα βιβλίο, απαραίτητα είναι τα πεδία: author, title, journal, year, ενώ τα εξής είναι προαιρετικά: volume, number, pages, month, note.

Όσον αφορά το πεδίο author, μιας και δεν είμαστε τόσο τυπικοί στη δομή που περιμένει το BibTeX, οι συγγραφείς πρέπει να περικλείονται πάντα σε διπλές αγκύλες. Δηλαδή, στο site μας παρατηρήστε πως η δομή από (σχεδόν) όλες τις εγγραφές μοιάζει με author = {{Peter Babington}}, αντί της ενδεικτικής δομής του παραδείγματος. Ακόμα, για τις ανάγκες του site μας, έχουν προστεθεί τα εξής custom πεδία:

  • cover για το URL από το εξώφυλλο του βιβλίου.
  • eudoxusid για το ID του βιβλίου στον Εύδοξο.
  • num_pages για τον αριθμό των σελίδων του βιβλίου.

Σημαντικό είναι να αναφερθεί πως η δομή ενός .bib αρχείου είναι αρκετά αυστηρή! Αυτό συμβαίνει διότι τα περισσότερα πεδία υφίστανται αρκετή επεξεργασία μέχρι τελικά να εμφανιστούν όταν γίνεται μία αναφορά. Επομένως, συνίσταται προσοχή κατά την επεξεργασία τους και θα ήταν συνετό αυτή να γίνει από άτομα που έχουν (έστω βασική) γνώστη της δομής αυτής.

Αναφορά σε ένα Βιβλίο

Για την εμφάνιση ενός νέου βιβλίου σε ένα course, αρχικά πρέπει να προστεθεί η σχετική εγγραφή στο αρχείο _bibliography/references.bib. Αν είστε τυχεροί, το βιβλίο ίσως να είναι διαθέσιμο στο Google Scholar, ή κάποιο αντίστοιχο site, όπου η εξαγωγή σε BibTeX παρέχεται αυτόματα. Εναλλακτικά, θα πρέπει να δημιουργηθεί μια νέα εγγραφή "με το χέρι". Προτείνεται να αντιγραφεί μία υπάρχουσα εγγραφή και να τροποποιηθούν απαραιτήτως τα πεδία της. Αν κάποιο πεδίο είναι κενό, χρησιμοποιείστε την έκφραση {} ως την τιμή του, π.χ. abstract = {}.

Εφόσον υπάρχει η σχετική εγγραφή για ένα βιβλίο, αρκεί να προστεθεί το μοναδικό αναγνωριστικό του (όχι το eudoxusid!) στο πεδίο books ενός course. Το αναγνωριστικό ενός βιβλίου συνήθως είναι της μορφής isbn_ με τον κωδικό ISBN να ακολουθεί, αφότου έχουν αντικατασταθεί οι - με _, π.χ. ένα βιβλίο με ISBN 960-03-2718-1 θα μπορούσε να έχει αναγνωριστικό isbn_960_03_2718_1. Να σημειωθεί πως αυτός δεν είναι αυστηρός κανόνας, αλλά σύμβαση η οποία δεν χρειάζεται να τηρείται απαραίτητα!

Εφόσον υπάρχουν τα απαραίτητα πεδία, το jekyll-scholar αναλαμβάνει την εμφάνισή τους με ένα κοινό και διαδεδομένο format. Σε αυτή την περίπτωση, χρησιμοποιείται το APA, όμως αυτό μπορεί να αλλάξει από τις σχετικές ρυθμίσεις.

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

Ρυθμίσεις του jekyll-scholar

Για την περαιτέρω κατανόηση της λειτουργικότητας του jekyll-scholar, απαραίτητο θα είναι να γνωρίζουμε την παραμετροποίηση του στο site μας. Οι ρυθμίσεις για το jekyll-scholar περιλαμβάνονται στο αρχείο config.yml. Κατά τη συγγραφή αυτής της σελίδας, οι ρυθμίσεις έχουν ως εξής:

scholar:
  details_dir: bibliography
  details_layout: bibtex.html
  details_link: Details
  details_permalink: /:details_dir/:key:extension

Πιο αναλυτικά:

  • Η επιλογή details_dir καθορίζει το φάκελο στον οποίο υπάρχει το .bib αρχείο, το οποίο πρέπει να έχει όνομα references.bib (αυτό μπορεί επίσης να αλλάξει από τις ρυθμίσεις).
  • Η επιλογή details_layout έχει ως αποτέλεσμα τη δημιουργία μιας σελίδας για κάθε εγγραφή στο .bib αρχείο, η οποία χρησιμοποιεί το αντίστοιχο html αρχείο ως layout.
  • Το relative URL της κάθε σελίδας καθορίζεται από την επιλογή details_permalink.
  • Τέλος, το details_link καθορίζει το κείμενο που δημιουργείται για την προβολή του URL όταν γίνεται αναφορά σε ένα βιβλίο. Ως έχει μέχρι στιγμής, η τελευταία αυτή γραμμή δε χρησιμοποιείται με κάποιο τρόπο στο site, οπότε θα μπορούσε να αφαιρεθεί.

Διαδικασία Εμφάνισης ενός Βιβλίου

Εφόσον υπάρχει ένα ή περισσότερα βιβλία σε κάποιο course, αυτά παρατίθενται στη σελίδα του course. Αυτό γίνεται μέσω του layout courses.html που βρίσκεται στο minimal-ionio. Για την ακρίβεια, στο συγκεκριμένο layout χρησιμοποιείται η γραμμή {% include book.html %}, η οποία αναλαμβάνει την παράθεση κάθε βιβλίου. Για κάθε βιβλίο, χρησιμοποιείται ο συνδυασμός των tags details_link και reference για να εμφανιστεί το URL για τη σελίδα του βιβλίου καθώς και τα στοιχεία του βιβλίου στο προκαθορισμένο format.

Για την ξεχωριστή σελίδα κάθε βιβλίου, αυτή δημιουργείται αυτόματα μέσω του jekyll-scholar. Μία τέτοια σελίδα χρησιμοποιεί το layout bibtex.html, που βρίσκεται στο site, σε αντίθεση με τα υπόλοιπα layouts, διότι το jekyll-scholar δεν μπορούσε να χρησιμοποιήσει το αρχείο όταν βρισκόταν απομακρυσμένα στο theme (βλ. PR #24).

Στη σελίδα κάθε βιβλίου εμφανίζεται ένας πίνακας με διάφορα στοιχεία και μία σύντομη περιγραφή (εφόσον υπάρχει), τα οποία διαχειρίζεται το layout. Ακόμα, Οι συγγραφείς και το εξώφυλλο του βιβλίου, καθώς κι ένα link προς το βιβλίο στον Εύδοξο εμφανίζονται σε ένα sidebar, μέσω του book_sidebar στο frontmatter του layout. Για την ακρίβεια, το bibtex.html επεκτείνει τη λειτουργικότητα του layout single.html, το οποίο παρέχει τη δυνατότητα χρήσης sidebar. Το sidebar.html ανιχνεύει τι είδους sidebar χρησιμοποιείται στη σελίδα μέσω των σχετικών μεταβλητών (εδώ book_sidebar) και καλεί το αντίστοιχο include (book_sidebar.html).

Εναλλακτικές Προσεγγίσεις και Μετατροπή

Αν και η χρήση του BibTeX και του jekyll-scholar είναι τεχνικά η μάλλον ευκολότερη επιλογή, καθώς μεγάλο μέρος της απαραίτητης λειτουργικότητας παρέχεται από αυτά, προσθέτει αρκετό "overhead" στο project με διάφορους τρόπους. Η πιο εμφανής έκφανση αυτού, που γίνεται αντιληπτή από όσους τρέχουν τοπικά το site για δοκιμές, είναι η επιβάρυνση του χρόνου δημιουργίας του site. Από την άλλη, η επεξεργασία και προσθήκη βιβλιογραφίας γίνεται αρκετά πιο περίπλοκη για έναν απλό χρήστη και ένα λάθος σε αυτή τη διαδικασία μπορεί να οδηγήσει σε σφάλματα κατά τη λειτουργία του site. Επομένως, είναι μάλλον συνετό να εξεταστούν μερικές εναλλακτικές.

Δομή σε Data File

Ας ξεκινήσουμε με τη δομή που χρησιμοποιήθηκε για λίγο καιρό, προτού μεταβούμε στην τωρινή λύση του BibTeX. Η δομή αυτή προστέθηκε στο PR #80 και χρησιμοποιούσε ένα data file για τη διατήρηση των απαραίτητων στοιχείων. Ένα course, αντί του τωρινού αναγνωριστικού στο .bib, χρησιμοποιούσε το αντίστοιχο αναγνωριστικό στο data file. Έτσι, το layout courses αναλάμβανε να αναζητήσει στο αρχείο τα αναγνωριστικά που βρίσκονταν στο πεδίο books και εμφάνιζε με ένα συγκεκριμένο format κάποια πεδία του βιβλίου.

Η συγκεκριμένη λύση είναι αρκετά κομψή και αρκετά κοντά στη φιλοσοφία του Jekyll. Η αναζήτηση σε ένα data file είναι αρκετά γρήγορη, ενώ η δομή του είναι πιο οικεία και κατανοητή (και λιγότερο αυστηρή!). Ο κύριος περιορισμός της συγκεκριμένης λύσης είναι η αδυναμία δημιουργίας σελίδας για κάθε βιβλίο. Όμως, αυτό θα μπορούσε να παρακαμφθεί, αν η εμφάνιση των στοιχείων ενός βιβλίου γινόταν με άλλο τρόπο (βλ. issue #74).

Για τη μελλοντική μετατροπή σε μία τέτοια δομή, παρέχονται βοηθητικά αρχεία στο helper repo: https://github.com/p15zerv/site-gr-bib-helpers. Συγκεκριμένα, το αρχείο bib_to_data_yaml.py αναλαμβάνει τη μετατροπή του αρχείου references.bib στο books.yml, που περιέχει ακριβώς τα ίδια στοιχεία. Αυτό μπορεί να χρησιμοποιηθεί μελλοντικά για οποιοδήποτε references.bib αρχείο, εφόσον η δομή του παραμείνει όμοια. Έτσι, μελλοντικά, θα μπορούσαν να γίνουν "revert" οι αλλαγές για τη λειτουργικότητα του BibTeX, ώστε το layout courses.html να διαχειρίζεται τη συγκεκριμένη δομή. Έπειτα, θα μπορούσε να προστεθεί περαιτέρω λειτουργικότητα για την αναλυτικότερη εμφάνιση των στοιχείων ενός βιβλίου.

Δομή σε Collection

Ένας άλλος τρόπος αναπαράστασης της βιβλιογραφίας θα μπορούσε να είναι τα collections. Η βασική ιδέα είναι η δημιουργία ένος collection books, το οποίο θα κρατάει ένα αρχείο .md για κάθε βιβλίο. Αυτά θα χρησιμοποιούσαν ένα κοινό layout (το υπάρχον bibtex.html αν μετατρέπονταν τα page.entry σε σκέτο page), οπότε η εμφάνιση κάθε βιβλίου στη δικιά του σελίδα θα ήταν απλή. Έτσι, θα έμενα απλώς να προστεθεί η λειτουργικότητα παράθεσης της βιβλιογραφίας σε ένα course, που θα μπορούσε να γίνει με τρόπο αντίστοιχο με τα data files.

Για τη μετάβαση σε τέτοιου είδους δομή, παρέχεται και πάλι μετατροπή στο helper repo: https://github.com/p15zerv/site-gr-bib-helpers. Το αρχείο bib_to_collection.py αναλαμβάνει τη μετατροπή κάθε εγγραφής σε ένα ξεχωριστό .md αρχείο σε ένα φάκελο books, ώστε αυτό να αποτελεί απευθείας ένα collection. Με τις απαραίτητες αλλαγές στο layout και στο config, η εμφάνιση παραμένει ακριβώς η ίδια. Επομένως, μετέπειτα, θα έπρεπε απλώς να γίνει η διασύνδεση μεταξύ courses και books.

Δομή σε JSON

Τέλος, μιας και όλες οι προηγούμενες λύσεις έχουν να κάνουν με το Jekyll, παρέχεται και μία πιο γενική εναλλακτική. Η λογική εδώ είναι απλώς η μετατροπή της πληροφορίας σε ένα πιο γενικό format, ώστε η διαθέσιμη πληροφορία να μπορεί να αξιοποιηθεί από άλλου είδους συστήματα, όπως βάσεις δεδομένων. Η λύση αυτή παρέχει τη λιγότερη "out of the box" λειτουργικότητα, αφού πλέον μιλάμε για τελείως διαφορετικές τεχνολογίες και αρχιτεκτονικές.

Και πάλι, στο helper repo: https://github.com/p15zerv/site-gr-bib-helpers παρέχεται το αρχείο bib_to_json.py για τη μετατροπή του .bib σε .json. Το νέο αρχείο περιέχει όλες τις υπάρχουσες πληροφορίες για κάθε εγγραφή. Πιθανό σενάριο χρήσης θα ήταν η αξιοποίηση συστήματος διαχείρισης βάσης δεδομένων, όπου συνήθως επιτρέπεται η εισαγωγή γραμμών σε κάποιο πίνακα μέσω αρχείου json, εφόσον οι δομές μεταξύ πίνακα και json μπορούν να αντιστοιχιστούν. Επομένως, δεδομένου ότι έχουμε έναν πίνακα με την κατάλλλη δομή, μπορεί να γίνει "populated" και να διασυνδεθεί με τα αντίστοιχα course αντικείμενα. Έπειτα, θα μπορούσε να προστεθεί λειτουργικότητα αντίστοιχη με αυτή των collections, ώστε να εμφανίζονται οι παραθέσεις στις σελίδες των μαθημάτων, καθώς και ξεχωριστές σελίδες για κάθε βιβλίο.

Σχετικά Θέματα

Σχετικά issues: #96, #38 #74

epidrome commented 4 years ago

άριστη και πολύ αναλυτική τεκμηρίωση!

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

αν θες να δεις και τα (όποια) σχόλια από τους άλλους και ας μπει στο γουικι για τους μελλοντικούς συνεργάτες

p15zerv commented 4 years ago

Μιας και δε βλέπω να υπάρχουν άλλα σχόλια, κλείνω το issue για να μην πάρει το tag από το bot και θεωρηθεί μελλοντικά ως πιθανό issue. Αν υπάρξουν σχόλια μπορεί φυσικά να ξανά-ανοίξει.