Χρειαζόμαστε μια νέα γλώσσα σήμανσης εγγράφων - εδώ είναι ο λόγος

Εισαγωγή: Ποιο είναι το πρόβλημα;

Υπάρχουν πολλές διαθέσιμες γλώσσες σήμανσης εγγράφων. Η Wikipedia παραθέτει πάνω από 70 παραλλαγές στη λίστα των γλωσσών σήμανσης εγγράφων - μεταξύ των οποίων HTML, Markdown, Docbook, Asciidoctor, reStructuredText κ.λπ.

Γιατί λοιπόν ο τίτλος αυτού του άρθρου υποδηλώνει ότι χρειαζόμαστε ένα άλλο ;;;

Ποιο είναι το πρόβλημα?

Υπάρχουν δύο θεμελιώδη προβλήματα με τις υπάρχουσες γλώσσες σήμανσης εγγράφων: Είτε δεν είναι εύχρηστες είτε δεν είναι κατάλληλες για τη σύνταξη σύνθετων εγγράφων, όπως τεχνικά άρθρα, εγχειρίδια χρήστη ή βιβλία. Ένα παράδειγμα «όχι εύκολο στη χρήση, αλλά κατάλληλο για σύνθετα έγγραφα» θα ήταν το Docbook. Ένα παράδειγμα "εύχρηστο, αλλά δεν είναι κατάλληλο για σύνθετα έγγραφα" θα ήταν το Markdown.

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

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

Προκαταρκτικές παρατηρήσεις

Παρακαλώ σημειώστε:

  • Αυτό το άρθρο αφορά τις γλώσσες σήμανσης εγγράφων που χρησιμοποιούνται για τη σύνταξη εγγράφων κειμένου , όπως βιβλία και άρθρα που δημοσιεύονται στο Διαδίκτυο. Υπάρχουν άλλες γλώσσες σήμανσης που χρησιμοποιούνται για την περιγραφή συγκεκριμένων δεδομένων, όπως μαθηματικοί τύποι, εικόνες και γεωγραφικές πληροφορίες, αλλά αυτές είναι εκτός πεδίου αυτού του άρθρου. Ωστόσο, ορισμένες ιδέες που παρουσιάζονται σε αυτό το άρθρο ενδέχεται να εφαρμοστούν και σε άλλα είδη γλωσσών σήμανσης.
  • Αυτό το άρθρο επικεντρώνεται αποκλειστικά στη σύνταξη των γλωσσών σήμανσης. Δεν θα συζητήσουμε άλλες πτυχές που είναι επίσης σημαντικές στην επιλογή μιας κατάλληλης γλώσσας σήμανσης, όπως: υποστήριξη στο λειτουργικό σας σύστημα, ευκολία εγκατάστασης και εξαρτήσεις, αλυσίδα εργαλείων διαθέσιμη για τη δημιουργία τελικών εγγράφων, την ποιότητα της τεκμηρίωσης, την τιμή, τον πελάτη / υποστήριξη χρηστών κ.λπ.
  • Οι αναγνώστες αυτού του άρθρου θα πρέπει να έχουν κάποια βασική εμπειρία με μια γλώσσα σήμανσης όπως HTML, Markdown, Asciidoctor ή παρόμοια.
  • Οι αναγνώστες που δεν γνωρίζουν τα πολλά πλεονεκτήματα των γλωσσών σήμανσης εγγράφων μπορεί πρώτα να θέλουν να διαβάσουν:

    Πλεονεκτήματα των γλωσσών σήμανσης εγγράφων έναντι των επεξεργαστών WYSIWYG (επεξεργαστές κειμένου)

Αναστάτωση / Μέρος 1

Ας εξετάσουμε πρώτα μερικές γνωστές γλώσσες σήμανσης και ρίξτε μια ματιά σε ορισμένες ταλαιπωρίες.

HTML

Η HTML είναι η γλώσσα του ιστού. Λοιπόν, γιατί να μην γράφετε τα πάντα σε HTML; Οι λόγοι απόρριψης αυτής της επιλογής είναι γνωστοί. Ας τα ανακεφαλαιώσουμε γρήγορα.

Η HTML είναι δυσκίνητη για εγγραφή. Κανείς δεν θέλει να γράψει κώδικα XML με το χέρι, παρόλο που οι συντάκτες με υποστήριξη HTML / XML μπορεί να βοηθήσουν.

Ορισμένες συχνές εργασίες γραφής απαιτούν μη ασήμαντο κώδικα HTML.

Ας υποθέσουμε ότι θέλουμε να εμφανίσουμε μια οριζόντια κεντραρισμένη εικόνα με ένα απλό μαύρο περίγραμμα και έναν σύνδεσμο. Ο κώδικας HTML που ένας άπειρος χρήστης θα περίμενε να δουλέψει θα μπορούσε να έχει την εξής μορφή:

Αλλά ο κώδικας που πρέπει να γράψει είναι δυσκίνητος και υπάρχουν διαφορετικοί τρόποι για να το κάνει. Εδώ είναι ένας τρόπος:

 

Η HTML δεν διαθέτει "δυνατότητες παραγωγικότητας για συγγραφείς", όπως:

  • Αυτόματη δημιουργία πίνακα περιεχομένων, ευρετηρίου, γλωσσάρι κ.λπ.
  • Οι μεταβλητές χρησιμοποιούνται για να διατηρούν επαναλαμβανόμενες τιμές
  • Διαχωρισμός εγγράφου σε διαφορετικά αρχεία

Άλλες ταλαιπωρίες θα εμφανίζονται αργότερα.

Χαμήλωση τιμής

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

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

  • Το αρχικό Markdown που ορίστηκε από τον John Gruber δεν διαθέτει πολλές δυνατότητες που αναμένουν οι συγγραφείς, όπως πίνακες (υποστηρίζονται μόνο ενσωματωμένοι πίνακες HTML), αυτόματη δημιουργία πίνακα περιεχομένων, επισήμανση σύνταξης, διαχωρισμός αρχείων κ.λπ.
  • Δεν υπάρχει καμία μοναδική, ξεκάθαρη προδιαγραφή για το Markdown. Υπάρχουν πολλές γεύσεις του Markdown, με διαφορετικούς κανόνες και διαφορετικά χαρακτηριστικά. Αυτό οδηγεί σε προβλήματα ασυμβατότητας κατά την κοινή χρήση του κώδικα σήμανσης. Το CommonMark είναι μια προσπάθεια επίλυσης αυτού του προβλήματος. Ωστόσο, η προδιαγραφή είναι τεράστια και δεν έχει ολοκληρωθεί ακόμη (κατά τη στιγμή της σύνταξης, Απρίλιος 2019, η έκδοση 0.28, με ημερομηνία 2017-08–01, είναι η τελευταία)
  • Το Markdown έχει παρόμοια προβλήματα και περιορισμούς με αυτά που παρουσιάζονται αργότερα στο κεφάλαιο "Αναστάτωση / Μέρος 2". Αυτά τα ελαττώματα μπορούν γρήγορα να ενοχληθούν όταν χρησιμοποιείτε το Markdown για οτιδήποτε άλλο εκτός από σύντομα, απλά κείμενα.

Ακολουθεί μια λίστα άρθρων με περισσότερες πληροφορίες σχετικά με τις αδυναμίες του Markdown:

  • Γιατί δεν πρέπει να χρησιμοποιήσετε το "Markdown" για τεκμηρίωση
  • Ηλιοβασίλεμα στο Markdown;
  • Γιατί το Markdown δεν είναι η αγαπημένη μου γλώσσα

Βιβλίο

Το Docbook είναι μια γλώσσα σήμανσης που βασίζεται σε XML και χρησιμοποιεί σημασιολογικές ετικέτες για την περιγραφή εγγράφων.

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

Αλλά έχει τα ακόλουθα μειονεκτήματα:

Χρησιμοποιεί XML και σύνθετη λέξη Κοιτάξτε το παρακάτω παράδειγμα, δανεισμένο από τη Wikipedia:

 Very simple book  Chapter 1 Hello world! I hope that your day is proceeding splendidly!   Chapter 2 Hello again, world! 

Θα σας άρεσε να γράφετε και να διατηρείτε τέτοιο κώδικα;

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

= Very simple book== Chapter 1Hello world!I hope that your day is proceeding _splendidly_!== Chapter 2Hello again, world!

Το Docbook είναι επίσης περίπλοκο, και ως εκ τούτου είναι δύσκολο να μάθει και να χρησιμοποιήσει.

Η παραγωγή που παράγεται από το Docbook, ειδικά HTML, φαίνεται παλιομοδίτικη (δείτε παραδείγματα στον ιστότοπό της). Φυσικά, η παρουσίαση μπορεί να προσαρμοστεί, αλλά αυτό δεν είναι εύκολο έργο.

Κόμμι

Το LaTeX είναι ένα υψηλής ποιότητας σύστημα στοιχειοθεσίας. Χρησιμοποιείται ευρέως στον ακαδημαϊκό χώρο για τη δημιουργία επιστημονικών εγγράφων. Θεωρείται η καλύτερη επιλογή για τη σύνταξη εγγράφων PDF που περιέχουν πολλούς μαθηματικούς τύπους και εξισώσεις.

Ποτέ δεν χρησιμοποίησα τον εαυτό μου LaTeX, γιατί δεν γράφω επιστημονικά έγγραφα - μόνο άρθρα και βιβλία που δημοσιεύονται στον Ιστό. Επομένως, δεν θέλω να το σχολιάσω πάρα πολύ. Ωστόσο, είναι σημαντικό να το αναφέρουμε λόγω της δημοτικότητάς του στον ακαδημαϊκό χώρο.

Η μοναδική σύνταξη του LaTeX μου φαίνεται ρητή και λίγο περίπλοκη. Εδώ είναι ένα συντομευμένο παράδειγμα από τη Wikipedia:

\documentclass{article}\usepackage{amsmath}\title{\LaTeX}
\begin{document} \maketitle \LaTeX{} is a document preparation system ...
 % This is a comment \begin{align} E_0 &= mc^2 \\ E &= \frac{mc^2}{\sqrt{1-\frac{v^2}{c^2}}} \end{align} \end{document}

Το άρθρο Μετατροπή από (La) TeX σε HTML αναφέρει ότι η μετατροπή μαθηματικών LaTeX σε HTML είναι «μια πρόκληση».

Ορισμένες γλώσσες σήμανσης επιτρέπουν την ενσωμάτωση αποσπασμάτων LaTeX στον κώδικα σήμανσής τους, ο οποίος μπορεί να είναι πολύ χρήσιμος εάν χρειάζεστε τη δύναμη του LaTeX για μαθηματικά. Υπάρχουν άλλες επιλογές για την εμφάνιση μαθηματικών στον Ιστό, όπως το Mathjax ή το MathML (πρότυπο ISO και μέρος του HTML5).

Δημοφιλές για μεγάλα έγγραφα

Έχει εμφανιστεί ένας εντυπωσιακός αριθμός γλωσσών σήμανσης. Πολλοί από αυτούς χρησιμοποιούν μια σύνταξη παρόμοια με τη σήμανση, και επομένως είναι εύκολο να μάθουν και να χρησιμοποιήσουν. Ορισμένα έχουν περισσότερες δυνατότητες από το Markdown και είναι ακόμη επεκτάσιμα. Ωστόσο, μόλις αρχίσουμε να γράφουμε σύνθετα έγγραφα, γωνιακές θήκες και όρια μειώνουν την αρχική χαρά της χρήσης τους.

Δύο δημοφιλείς γλώσσες σήμανσης που χρησιμοποιούνται για μεγάλα έγγραφα είναι το Asciidoctor (μια βελτιωμένη έκδοση του Asciidoc) και το reStructuredText (μια βελτιωμένη έκδοση του StructuredText). Θα τα δούμε σύντομα.

Πρακτική γλώσσα σήμανσης (PML)

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

Η γλώσσα ονομάζεται Practical Markup Language (PML) .

«Να ανταποκρίνεται στις ανάγκες μιας συγκεκριμένης κατάστασης με χρήσιμο τρόπο. βοηθώντας στην επίλυση ενός προβλήματος ή δυσκολίας. αποτελεσματικό ή κατάλληλο » - ορισμός του« πρακτικού »στο Cambridge Dictionary

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

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

Ένα έγγραφο PML είναι ένα δέντρο κόμβων (παρόμοιο με ένα έγγραφο XML / XHTML). Κάθε κόμβος ξεκινά με ένα {, ακολουθούμενο από ένα όνομα ετικέτας. Κάθε κόμβος τελειώνει με α }. Ένας κόμβος μπορεί να περιέχει κείμενο ή θυγατρικούς κόμβους.

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

{i bright}

Αυτός ο κόμβος ξεκινά με {i και τελειώνει με }. iείναι το όνομα της ετικέτας. Σε αυτήν την περίπτωση iείναι μια συντομογραφία για italic, που σημαίνει ότι το περιεχόμενο του κόμβου θα αποδίδεται με πλάγια γράμματα . Το περιεχόμενο αυτού του κόμβου είναι το κείμενο bright. Ο παραπάνω κωδικός σήμανσης PML θα αποδίδεται ως:

ΛΑΜΠΡΌΣ

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

Για παράδειγμα, ο τίτλος ενός κεφαλαίου ορίζεται με το χαρακτηριστικό title, ως εξής:

{chapter title=A Nice Surprise Once upon a time ...}

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

Μπορείτε να κάνετε λήψη και να παίξετε με μια δωρεάν εφαρμογή του PML. Αλλά σημειώστε: Το PML είναι ένα έργο σε εξέλιξη . Λείπουν δυνατότητες, ενδέχεται να αντιμετωπίσετε σφάλματα και η συμβατότητα προς τα πίσω δεν είναι εγγυημένη προς το παρόν.

Χρησιμοποιώ τον PML για να γράψω όλα τα διαδικτυακά μου έγγραφα, όπως αυτό το άρθρο. Για συνδέσμους σε πιο πραγματικά παραδείγματα, επισκεφθείτε τις Συχνές ερωτήσεις.

Αναστάτωση / Μέρος 2

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

Για κάθε παράδειγμα, ο κωδικός σήμανσης θα εμφανίζεται σε HTML, Asciidoctor, reStructuredText και PML.

Εάν θέλετε να δοκιμάσετε κάποιον κώδικα, μπορείτε να χρησιμοποιήσετε τους ακόλουθους διαδικτυακούς ελεγκτές (δεν χρειάζεται να εγκαταστήσετε τίποτα στον υπολογιστή σας):

  • HTML
  • Ασιατιδικός
  • reStructuredText

Ένας διαδικτυακός ελεγκτής για PML δεν είναι ακόμη διαθέσιμος. Πρέπει να εγκαταστήσετε PML σε υπολογιστή με Windows εάν θέλετε να το δοκιμάσετε.

Στυλ γραμματοσειράς

Τα στυλ γραμματοσειράς ( πλάγια , έντονα , monospaceκ.λπ.) χρησιμοποιούνται συχνά σε όλα τα είδη εγγράφων, επομένως είναι απαραίτητη η καλή υποστήριξη.

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

Μέρος μιας φράσης με πλάγιους χαρακτήρες

Ας υποθέσουμε ότι θέλουμε να γράψουμε:

Το ονόμασαν Αρμονικά κράτη , ένα καλό όνομα.

Αυτή είναι μια ασήμαντη υπόθεση και όλες οι γλώσσες την υποστηρίζουν.

HTML :

They called it Harmonic States, a good name.

Ασιατιδολόγος :

They called it _Harmonic States_, a good name.

reStructuredText :

They called it *Harmonic States*, a good name.

PML :

They called it {i Harmonic States}, a good name.

Μέρος μιας λέξης με πλάγιους χαρακτήρες

Θέλουμε να γράψουμε:

Αυτή un τυλιγμένο πρώτα την πρόκληση.

HTML :

She unwrapped the challenge first.

Ασιατιδολόγος :

She __un__wrapped the challenge first.

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

Αρχικά, έγραψε την πρόκληση.

reStructuredText :

She *un*\wrapped the challenge first.

Σημειώστε ότι το γράμμα w πρέπει να ξεφύγει (πριν από κάθετο) για λόγους που εξηγούνται εδώ. Εάν το γράμμα δεν διαφύγει, εμφανίζεται μια προειδοποίηση και το αποτέλεσμα είναι:

Εκείνη την πρώτη πρόκληση ολοκλήρωσε.

PML :

She {i un}wrapped the challenge first.

Κείμενο με έντονη γραφή και πλάγια γραφή

Θέλουμε να γράψουμε:

Όλοι ήταν εντυπωσιακοί .

HTML :

They were all totally flabbergasted.

Ασιατιδολόγος :

They were all *_totally flabbergasted_*.

reStructuredText:

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

PML:

They were all {b {i totally flabbergasted}}.

Παράδειγμα πραγματικής ζωής

Here is an example inspired by an Asciidoctor user who asked how to display:

_idoptional.

Let’s make the exercise a little bit more interesting by also displaying:

_idoptional.

HTML:

_idoptional_idoptional

No surprise here. It just works as expected.

Asciidoctor:

Intuitive attempt:

*_id* _optional___id_ *optional*

The first line doesn’t work, it produces:

id _optional

However, the second line works, which is a bit counterintuitive.

If normal text includes a character that is also used for markup (in our case the _ preceding id), then the character must be escaped. This is a fundamental rule in pretty much all markup languages. For example in HTML a < must be escaped with <. Many languages (including Asciidoctor and PML) use a backslash prefix (e.g. \r) to escape. So let's rewrite the code:

*\_id* _optional__\_id_ *optional*

This doesn’t work in Asciidoctor. It produces

_id _optional_

and

\_id optional

Here is a correct version, as suggested in an answer to the user’s question:

*pass:[_]id* _optional__pass:[_]id_ *optional*

Another answer suggests this solution:

*_id* __optional_____id__ *optional*

More edge case are documented in chapters Unconstrained formatting edge cases and Escaping unconstrained quotes of the Asciidoctor User Manual.

reStructuredText:

**_id** *optional**_id* **optional**

There is no problem here, because the character _ is not used in reStructuredText to define markup.

However, suppose we wanted to write:

*id**optional*.

Here is the code:

*\*id\** ***optional***

Note that the *s in id must be escaped, but the *s in optional don't need to be escaped.

PML:

{b _id} {i optional}{i _id} {b optional}

Nested Font Styles

Nested font styles of the same kind (e.g. .........) occur rarely in text written by humans, but they could be more or less frequent in auto-generated markup code. If they are not supported then the tool that generates the markup code becomes more complicated to implement, because it must track the font styles that are active already, in order to avoid nesting them.

So, how is this supported in the different languages?

HTML:

This is excellent, isn't it?

No problem, it produces

This is excellent, isn’t it?

Asciidoctor:

_This is _excellent_, isn't it?_

The above code is obviously ambiguous: Are the italics nested or do we want to italicize “This is “ and “, isn’t it?”. When I tested it, the result was neither of it:

This is _excellent, isn’t it?_

As far as I now, Asciidoctor doesn’t support nested font styles of the same kind.

reStructuredText:

The reStructuredText specification states: “Inline markup cannot be nested.” However, no error is displayed if it is nested, and the result is unspecified.

PML:

{i This is {i excellent}, isn't it?}

Font styles of the same kind can be nested in PML. The above code results in:

This is excellent, isn’t it?

Nested Chapters

Suppose we are writing an article titled “New Awesome Product” that contains four chapters. The structure looks as follows:

New Awesome Product Introduction More features Faster Less resources

Later on we decide to insert chapter “Advantages” as a parent of the three last chapters. The structure now becomes:

New Awesome Product Introduction Advantages More features Faster Less resources

What are the changes required in the markup code to pass from version 1 to version 2? Can we simply insert the code for a new chapter? Let’s see.

HTML:

Note: Code changes are displayed in bold.

As shown above, besides inserting the new chapter, we have to change the markup for the three child chapters: h2 must be changed to h3.

Asciidoctor:

Again, we have to change the markup for the three child chapters: == must be changed to ===

Note: The blank lines between the chapters are required, otherwise the document is not rendered correctly.

reStructuredText:

The markup for the three child chapters must be changed: All occurrences of = must be changed to -

The non-trivial rules for reStructuredText’s sections can be looked up here.

PML:

In PML, there is no need to change the code of the three child chapters.

Bottom Line:

In all languages, except PML, the markup code of all child chapters must be adapted if a parent chapter is inserted.

This is not a deal-breaker in case of small articles with few chapters. But image you are writing your next big article or book with lots of chapters and frequent changes. Now, the necessity to manually update child chapters can quickly turn into a daunting, boring, and error-prone task.

Note: Asciidoctor provides a leveloffset variable that can be used to change the level of chapters. This might be useful in some cases, but it also creates additional unneeded complexity, as can be seen here and here.

A more serious kind of problem can arise in the following situation: Imagine a set of different documents that share some common chapters. To avoid code duplication, the common chapters are stored in different files, and an insert file directive is used in the main documents. This works fine as long as the levels of all common chapters are the same in all documents. But troubles emerge if this is not the case.

It is also worth to mention that HTML, Asciidoctor and reStructuredText don’t protect us against wrong chapter hierarchies. For example, you don’t get a warning or error if a chapter of level 2 contains a direct child chapter of level 4.

In a language like PML, the above problems simply don’t exist, because the level is not specified in the markup code. All chapters (of any level) are defined with the same, unique syntax. The chapters’ tree structure (i.e. the level of each chapter) is automatically defined by the parser. And wrong hierarchies in the markup code, such as a missing } to close a chapter, are flagged by an error message.

Lists

In Asciidoctor the kind of problems we have seen with chapter hierarchies can also arise with list hierarchies (e.g. lists that contain lists). The reason is the same as for chapters: Asciidoctor lists use different markup code to explicitly specify the level of list items (* for level 1, ** for level 2, etc.). Moreover, there are a number of complications you have to be aware of when working with complex list content.

In reStructuredText, nested lists are created using indentation and blank lines. This works fine for simple nested lists, but creates other problems in more complex cases (not discussed here). Using whitespace (e.g. blank lines and indentation) to define structure in markup code is a bad idea, as we’ll see soon.

Σε HTML και PML, τα παραπάνω προβλήματα δεν υπάρχουν με λίστες επειδή η σύνταξη για κόμβους γονέα και παιδιού είναι η ίδια.

Κενός χώρος και εσοχή

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

parent child 1 child 2

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

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

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

"Το κενό διάστημα δεν αλλάζει τη δομή ή τη σημασιολογία του εγγράφου." - κενό διάστημα - ασήμαντος κανόνας

Τι σημαίνει αυτό?

First, let us define whitespace: Whitespace is any set of one or more consecutive spaces, tabs, new lines, and other Unicode characters that represent space.

In our context, the above rule means that:

Within text, a set of several (i.e. more than one) whitespace characters is treated the same as a single space character.

For example, this code:

a beautiful flower

… is identical to this one:

a beautiful flower

Between structural elements, a set of whitespace characters is insignificant.

For example, this code:

… is identical to this one:

A special case of whitespace is indentation (leading whitespace at the beginning of a line). The above rule implies that indentation is insignificant too. Indentation doesn’t change the result of the final document.

Applying the whitespace-insignificant rule is important, because it leads to significant advantages:

  • There is no need to learn, apply and worry about complex whitespace rules (see examples below).

    Violating the whitespace-insignificant rule in a markup specification adds unneeded complexity, and can lead to markup code that is ugly, error-prone, and difficult to maintain, especially in the case of nested lists.

  • Whitespace can freely be used by authors to format the markup code in a more understandable, presentable and attractive way (pretty printing). For example, lists (and lists of lists) can be indented to display their structure in a visually clear and maintainable way, without the risk of changing the underlying structure.
  • Text blocks can be copy/pasted without the need to adapt whitespace.
  • If shared text blocks (stored in different files) are imported into several documents with different structures, there is no risk of changing or breaking the structure.
  • There is no unexpected or obscure behavior if the whitespace is not visible for human readers. Some examples:

    - a mixture of whitespace characters, such as spaces and tabs, especially when used to indent code

    - whitespace at the end of a line

    - whitespace in empty lines

    - visually impaired (blind) people who can’t read whitespace

    Note: To alleviate the pain, some editors provide a display-whitespace mode.

  • Tools that generate markup code, as well as markup parsers are generally easier to create.
  • In some situations it is useful to reduce whitespace to a minimum (e.g. no new lines), in order to save storage space and improve performance.

If you want a few examples demonstrating the kind of technical problems that arise if whitespace is significant, you can read:

  • What are the downsides to whitespace indentation rather than requiring curly braces?
  • F# syntax: indentation and verbosity
  • Issue in nodeca/js-yaml

So, how is whitespace handled in the languages we are discussing in this article?

HTML:

HTML applies the whitespace-insignificant rule.

For a thorough explanation, look at this excellent article written by Patrick Brosset: When does white space matter in HTML?.

Asciidoctor:

In Asciidoctor, whitespace is significant in some cases.

This can lead to surprising behavior and problems with no easy or no satisfying solution. Some examples can be seen here and here.

reStructuredText:

reStructuredText has whitespace rules that are ‘a bit surprising’.

For example, writing *very* results in very (text in italics, as expected). However, * very* results in * very* (no italics!), because of the whitespace preceding "very". To understand why, the answer might be found in chapter Whitespace of the specification.

PML:

Similar to HTML, PML applies the whitespace-insignificant rule.

There is one exception: For practical reasons, a blank line between two text blocks results in a paragraph break. This means that instead of writing:

{p text of paragraph 1}{p text of paragraph 2}

… we can simply write:

text of paragraph 1text of paragraph 2

Note: Sometimes, whitespace is significant in text. For example whitespace must be preserved in source code examples. Or, in verbatim text, several consecutive spaces or new lines must be preserved in the final document. All languages support this. However, in reStructuredText it’s not always obvious how to it, as shown here.

Other Inconveniences

As seen already, some markup languages systematically use opening and closing tags. An example would be <;i>; and in HTML. All XML-based languages, as well as PML belong to this class of languages.

Without digging into details, here are some drawbacks that can occur in languages that do not (or not always) use pairs of distinct opening/closing tags (e.g. Markdown, Asciidoctor, and reStructuredText):

Editor support

Creating good, reliable editor support is more difficult to develop. Examples of useful editor features are:

  • syntax highlighting for markup code
  • markup code completion
  • visualizing pairs of block start/end marks (e.g. { and its corresponding })
  • block collapsing/expanding

    In the case of languages that use distinct opening/closing tags, the two last features work out-of-the-box in some editors. For example, PML uses { and } for node boundaries. This is also used in many programming languages (C, Java, Javascript, etc.) and therefore block features implemented for programming languages will also work for PML.

Document validation

Fewer syntax and structure errors can be detected automatically. This can lead to more time spent on debugging documents. Or, even worse, there might be silently ignored errors that end up in wrong output (Did I really fail to spot the missing warning block on page 267 of my 310 pages book?).

Parsers

It is more difficult to create parsers (i.e. programs that read markup code) that work well in all cases. If different parsers read the same markup code, there is an increased risk of getting different results for corner-cases.

Auto-generated markup code

Tools that generate markup code programmatically are more difficult to create. For example, if whitespace is significant, or font styles cannot be nested, then additional state must be updated and tracked, in order to respect these rules.

My Own Experience

When I started writing technical documents a few years ago, I used Docbook. It took me some time to learn it, but after that I never stumbled on anything I couldn’t do. Docbook is powerful. However, I disliked typing verbose XML code. I tried some XML editors, but gave up. Finally I just wrote complete text blocks unformatted in Notepad++, and then adorned the text with the necessary markup code. It was frustrating and time-consuming. Moreover, I couldn’t find a stylesheet that produced good-looking web documents, and I didn’t have the patience, motivation, and experience to fiddle around with big, complex CSS files and adapt them.

Later on I discovered Asciidoctor. What a relief. Everything was so much simpler and the web documents were beautiful, out of the box. Asciidoctor’s documentation is great, and I think the community is helpful and active. However, when I started to write more complex and bigger documents, I had to deal with problems similar to those described in the previous sections. At one point, I had to develop a specific pre- and post-processor to solve a problem for which I couldn’t find a solution in Asciidoctor/Gitbook.

An intriguing question emerged: “Why do these problems not exist in Docbook?”.

To make a long story short, I concluded that we need a new markup syntax. The key points to success would be:

  • easy to learn: few, simple, consistent and predictable rules (no exceptions)
  • easy to write and read
  • well-structured documents with no ambiguities
  • powerful enough to create big, complex documents without the need for “special rules, tricks, or workarounds”

After a period of investigating, pondering, programming, testing and improving, the Practical Markup Language (PML) was born. Since then, I never looked back again. Today I write all my web documents in PML (including this article).

Of course, when I started to create PML, it was to cover my own needs. So, I am probably biased. Hopefully this article contains enough factual examples, but I encourage you to leave a comment if you see anything wrong, unfair, or missing. I appreciate constructive feedback of any kind, and I will update the article if needed.

Conclusion

As demonstrated in this article, a good number of problems encountered with existing document markup languages vanish with the PML syntax.

Now we should come together to improve PML and make it more powerful, so that it covers more use cases and more people can benefit from it.

Please help to spread the word. Or try out PML and send feedback, so that we know what needs to be refined. Your voice counts!

The vision is to create the best possible document markup language and all necessary tools, so that writers can focus on writing and enjoy creating beautiful documents in a minimum of time — without worrying about unneeded complexity.





#####