quarto-formats.qmd

# Επιλογές μορφοποίησης στο Quarto {#sec-quarto-formats}

```{r}
#| echo: false

source("_common.R")
```

## Εισαγωγή

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

Υπάρχουν δύο τρόποι για να καθορίσετε τον τύπο του αρχείου εξόδου:

1.  Μόνιμα, τροποποιώντας την YAML επικεφαλίδα:

    ``` yaml
    title: "Diamond sizes"
    format: html
    ```

2.  Παροδικά, καλώντας την εντολή `quarto::quarto_render()`:

    ```{r}
    #| eval: false

    quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")
    ```

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

    ```{r}
    #| eval: false

    quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))
    ```

## Επιλογές αρχείων εξόδου

Το Quarto προσφέρει ένα ευρύ φάσμα μορφών εξόδου.
Μπορείτε να βρείτε την πλήρη λίστα στη διεύθυνση <https://quarto.org/docs/output-formats/all-formats.html>.
Πολλές μορφές μοιράζονται ορισμένες επιλογές εξόδου (για παράδειγμα, `toc: true` για τη συμπερίληψη πίνακα περιεχομένων), ενώ άλλες έχουν επιλογές που είναι συγκεκριμένες για τη μορφή αυτή (για παράδειγμα το `code-fold: true` συμπτύσσει κομμάτια κώδικα σε μία `<details>` ετικέτα για HTML αρχεία εξόδου, ώστε ο χρήστης να μπορεί να την εμφανίσει κατ' επιλογή, που δεν είναι διαθέσιμο για έγγραφα PDF ή Word).

Για να παρακάμψετε τις προεπιλεγμένες ρυθμίσεις, πρέπει να χρησιμοποιήσετε ένα επεκτεινόμενο πεδίο `format`.
Για παράδειγμα, εάν θέλατε να δημιουργήσετε ένα `html` αρχείο με έναν αιωρούμενο (floating) πίνακα περιεχομένων, θα χρησιμοποιούσατε:

``` yaml
format:
  html:
    toc: true
    toc_float: true
```

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

``` yaml
format:
  html:
    toc: true
    toc_float: true
  pdf: default
  docx: default
```

Παρατηρήστε το ιδιαίτερο συντακτικό (`pdf: default`) που θα πρέπει να χρησιμοποιήσετε εάν δεν θέλετε να παρακάμψετε τις προκαθορισμένες επιλογές.

Για να αποδώσετε (render) όλες τις επιλογές μορφοποίησης που καθορίζονται στην κεφαλίδα YAML ενός εγγράφου, μπορείτε να χρησιμοποιήσετε την επιλογή `output_format = "all"`.

```{r}
#| eval: false

quarto::quarto_render("diamond-sizes.qmd", output_format = "all")
```

## Έγγραφα

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

-   Το `pdf` δημιουργεί ένα PDF χρησιμοποιώντας LaTeX (ένα σύστημα ανοιχτού κώδικα για τη διάταξη εγγράφων), το οποίο θα πρέπει να εγκαταστήσετε.
    Το RStudio θα σας ζητήσει αν δεν το έχετε ήδη.

-   Το `docx` για έγγραφα του Microsoft Word (`.docx`).

-   Το `odt` για έγγραφα OpenDocument Text (`.odt`).

-   Το `rtf` για έγγραφα με μορφή εμπλουτισμένου κειμένου (`.rtf`).

-   Το `gfm` για ένα έγγραφο GitHub Flavored Markdown (`.md`).

-   Το `ipynb` για Jupyter Notebooks (`.ipynb`).

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

``` yaml
execute:
  echo: false
```

Μία εναλλακτική επιλογή για `html` έγγραφα είναι η τα κομμάτια του κώδικα να παραμένουν κρυμμένα από προεπιλογή, αλλά να γίνονται ορατά με ένα κλικ:

``` yaml
format:
  html:
    code: true
```

## Παρουσιάσεις

Μπορείτε επίσης να χρησιμοποιήσετε το Quarto για τη δημιουργία παρουσιάσεων.
Έχετε λιγότερο οπτικό έλεγχο από ό,τι με ένα εργαλείο όπως το Keynote ή το PowerPoint, αλλά η αυτόματη εισαγωγή των αποτελεσμάτων του κώδικα σας σε R σε μία παρουσίαση μπορεί να εξοικονομήσει σημαντικό χρόνο.
Οι παρουσιάσεις λειτουργούν διαιρώντας το περιεχόμενό σας σε διαφάνειες, με μία νέα διαφάνεια να ξεκινά σε κάθε κεφαλίδα δεύτερου επιπέδου (`##`).
Επιπλέον, οι κεφαλίδες πρώτου επιπέδου (`#`) υποδεικνύουν την αρχή μιας νέας ενότητας με μία διαφάνεια τίτλου ενότητας που είναι, από προεπιλογή, κεντραρισμένη στη μέση.

Το Quarto υποστηρίζει μία ποικιλία μορφών παρουσίασης, που περιλαμβάνουν:

1.  `revealjs` - HTML παρουσιάσεις με τη χρήση revealjs

2.  `pptx` - PowerPoint παρουσιάσεις

3.  `beamer` - PDF παρουσιάσεις με τη χρήση LaTeX Beamer.

Μπορείτε να διαβάσετε περισσότερα για τη δημιουργία παρουσιάσεων με το Quarto στο [https://quarto.org/docs/presentations](https://quarto.org/docs/presentations/).

## Διαδραστικότητα

Όπως και με κάθε άλλο HTML έγγραφο, τα HTML έγγραφα που δημιουργούνται με το Quarto μπορούν να περιέχουν και διαδραστικά στοιχεία.
Εδώ εισάγουμε δύο επιλογές για να συμπεριλάβουμε διαδραστικότητα στα Quarto έγγραφα μας: τα htmlwidgets και το Shiny.

### htmlwidgets

Το HTML είναι μία διαδραστική μορφή και μπορείτε να επωφεληθείτε από αυτή τη διαδραστικότητα με τη χρήση **htmlwidgets**, συναρτήσεων της R που παράγουν διαδραστικές HTML απεικονίσεις.
Για παράδειγμα, πάρτε τον **leaflet** χάρτη στην παρακάτω εικόνα.
Εάν προβάλλετε αυτήν τη σελίδα στο διαδίκτυο, μπορείτε να σύρετε τον χάρτη, να τον μεγεθύνετε και μικρύνετε κλπ.
Προφανώς δεν μπορείτε να το κάνετε αυτό σε ένα βιβλίο, οπότε το Quarto εισάγει αυτόματα ένα στατικό στιγμιότυπο για εσάς.

```{r}
#| fig-alt: Leaflet map of Maungawhau / Mount Eden.

library(leaflet)
leaflet() |>
  setView(174.764, -36.877, zoom = 16) |> 
  addTiles() |>
  addMarkers(174.764, -36.877, popup = "Maungawhau") 
```

Το υπέροχο με τα htmlwidget είναι ότι δεν χρειάζεται να γνωρίζετε τίποτα για HTML ή JavaScript για να τη χρησιμοποιήσετε.
Όλες οι λεπτομέρειες περιέχονται στο πακέτο, οπότε δεν χρειάζεται να ανησυχείτε για αυτό.

Υπάρχουν πολλά πακέτα που παρέχουν htmlwidgets, συμπεριλαμβανομένων των:

-   [**dygraphs**](https://rstudio.github.io/dygraphs) για διαδραστικές απεικονίσεις χρονοσειρών.

-   [**DT**](https://rstudio.github.io/DT/) για διαδραστικούς πίνακες.

-   [**threejs**](https://bwlewis.github.io/rthreejs) για διαδραστικά τρισδιάστατα διαγράμματα.

-   [**DiagrammeR**](https://rich-iannone.github.io/DiagrammeR) για διαγράμματα (όπως διαγράμματα ροής και απλά διαγράμματα κόμβων-συνδέσμων).

Για να μάθετε περισσότερα σχετικά με τα htmlwidgets και για μία πλήρη λίστα των πακέτων που τα παρέχουν, επισκεφθείτε τη διεύθυνση <https://www.htmlwidgets.org>.

### Shiny

Τα htmlwidgets παρέχουν διαδραστικότητα **από την πλευρά του χρήστη** (**client-side**) --- όλη η αλληλεπίδραση συμβαίνει στο πρόγραμμα περιήγησης, ανεξάρτητα από την R.
Από τη μία, αυτό είναι υπέροχο γιατί μπορείτε να διανείμετε το HTML αρχείο σας χωρίς καμία σύνδεση με την R.
Ωστόσο, αυτό περιορίζει θεμελιωδώς το τι μπορείτε να κάνετε σε στοιχεία που έχουν δημιουργηθεί με HTML και JavaScript.
Μία εναλλακτική προσέγγιση είναι να χρησιμοποιήσετε το **shiny**, ένα πακέτο που σας επιτρέπει να δημιουργήσετε διαδραστικότητα χρησιμοποιώντας τον κώδικα R, κι όχι τη JavaScript.

Για να εκτελέσετε τον κώδικα σας σε Shiny από ένα έγγραφο Quarto, προσθέστε την επιλογή `server: shiny` στην κεφαλίδα YAML:

``` yaml
title: "Shiny Web App"
format: html
server: shiny
```

Τώρα μπορείτε να χρησιμοποιήσετε τις συναρτήσεις εισαγωγής ("input") για να προσθέσετε διαδραστικά στοιχεία σε ένα έγγραφο:

```{r}
#| eval: false

library(shiny)

textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)
```

```{r}
#| echo: false
#| out-width: null
#| fig-alt: |
#|   Δύο κουτιά εισόδου το ένα πάνω στο άλλο. Το πάνω λέει "What is your 
#|   name?", και το κάτω, "How old are you?".

knitr::include_graphics("quarto/quarto-shiny.png")
```

Χρειάζεστε επίσης ένα κομμάτι κώδικα με την επιλογή `context: server` που περιέχει τον κώδικα που πρέπει να εκτελεστεί σε έναν Shiny διακομιστή.

Στη συνέχεια, μπορείτε να ανατρέξετε στις τιμές με χρησιμοποιώντας τα `input$name` και `input$age` και ο κώδικας που τις χρησιμοποιεί θα εκτελείται ξανά αυτόματα κάθε φορά που αυτά αλλάζουν.

Δεν μπορούμε να σας δείξουμε μία ζωντανή shiny εφαρμογή εδώ επειδή οι shiny αλληλεπιδράσεις πραγματοποιούνται από την **πλευρά του διακομιστή** (**server-side**).
Αυτό σημαίνει ότι μπορείτε να γράψετε διαδραστικές εφαρμογές χωρίς να γνωρίζετε JavaScript, αλλά χρειάζεστε έναν διακομιστή για να τις εκτελέσετε.
Αυτό εισάγει ένα τεχνικό ζήτημα: Οι εφαρμογές Shiny χρειάζονται έναν διακομιστή Shiny για να εκτελούνται στο διαδίκτυο.
Όταν εκτελείτε τις εφαρμογές Shiny στον δικό σας υπολογιστή, το Shiny ρυθμίζει αυτόματα έναν διακομιστή Shiny για εσάς, αλλά χρειάζεστε έναν δημοσίως ορατό διακομιστή Shiny, εάν θέλετε να δημοσιεύσετε αυτού του είδους τη διαδραστικότητα στο διαδίκτυο.
Αυτός είναι ο θεμελιώδης συμβιβασμός του shiny: σε ένα shiny έγγραφο μπορείτε να κάνετε ότι θα κάνατε και στην R, αλλά απαιτείται κάποιος να τρέχει την R.

Για να μάθετε περισσότερα σχετικά με το Shiny, συνιστούμε να διαβάσετε το Mastering Shiny από τον Hadley Wickham, [https://mastering-shiny.org](https://mastering-shiny.org/).

## Ιστοσελίδες και βιβλία

Με λίγες επιπλέον υποδομές, μπορείτε να χρησιμοποιήσετε το Quarto για να δημιουργήσετε μία πλήρη ιστοσελίδα ή ένα βιβλίο:

-   Εισάγετε τα αρχεία σας με κατάληξη `.qmd` σε ένα κοινό μονοπάτι εργασίας.
    Το `index.qmd` θα γίνει η αρχική σελίδα σας.

-   Προσθέστε ένα YAML αρχείο που ονομάζετε ως `_quarto.yml` και το οποίο παρέχει την πλοήγηση στον ιστότοπο.
    Σε αυτό το αρχείο, ορίστε το `project` είτε ως `book` είτε ως `website`, για παράδειγμα:

    ``` yaml
    project:
      type: book
    ```

Για παράδειγμα, το ακόλουθο `_quarto.yml` αρχείο δημιουργεί μία ιστοσελίδα από τρία αρχεία πηγαίου κώδικα: το `index.qmd` (αρχική σελίδα), το `viridis-colors.qmd`, και το `terrain-colors.qmd`.

```{r}
#| echo: false
#| comment: ""

cat(readr::read_file("quarto/example-site.yml"))
```

Το αρχείο `_quarto.yml` που χρειάζεστε για ένα βιβλίο ακολουθεί παρόμοια δομή.
Το παρακάτω παράδειγμα δείχνει πως μπορείτε να δημιουργήσετε ένα βιβλίο με τέσσερα κεφάλαια, το οποίο παράγει τρία διαφορετικού τύπου αρχεία εξόδου (`html`, `pdf`, και `epub`).
Και πάλι, τα αρχεία του πηγαίου κώδικα είναι αρχεία με κατάληξη `.qmd`.

```{r}
#| echo: false
#| comment: ""

cat(readr::read_file("quarto/example-book.yml"))
```

Σας συνιστούμε να χρησιμοποιήσετε ένα RStudio project για τους ιστοτόπους και τα βιβλία σας.
Με βάση το αρχείο `_quarto.yml`, το RStudio θα αναγνωρίσει τον τύπο του project στο οποίο εργάζεστε και θα προσθέσει μία καρτέλα Build στο IDE, την οποία μπορείτε να χρησιμοποιήσετε για την απόδοση και προεπισκόπηση των ιστοτόπων και των βιβλίων σας.
Τόσο οι ιστότοποι όσο και τα βιβλία μπορούν επίσης να αποδοθούν χρησιμοποιώντας την εντολή `quarto::quarto_render()`.

Διαβάστε περισσότερα σχετικά με ιστοσελίδες Quarto στο <https://quarto.org/docs/websites> και στο <https://quarto.org/docs/books> για βιβλία.

## Άλλες επιλογές μορφοποίησης

Το Quarto προσφέρει ακόμη περισσότερες επιλογές αρχείων εξόδου:

-   Μπορείτε να γράψετε άρθρα σε περιοδικά χρησιμοποιώντας τα Quarto Journal Templates: <https://quarto.org/docs/journals/templates.html>.

-   Μπορείτε να εξάγετε έγγραφα Quarto σε Jupyter Notebooks με την επιλογή `format: ipynb`: <https://quarto.org/docs/reference/formats/ipynb.html>.

Δείτε στο <https://quarto.org/docs/output-formats/all-formats.html> για μία λίστα με ακόμη περισσότερες επιλογές μορφοποίησης.

## Σύνοψη

Σε αυτό το κεφάλαιο σας παρουσιάσαμε μία ποικιλία επιλογών για την επικοινωνία των αποτελεσμάτων σας με το Quarto, από στατικά και διαδραστικά έγγραφα έως παρουσιάσεις, ιστοτόπους και βιβλία.

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

-   Για να βελτιώσετε τις δεξιότητες παρουσίασης σας, δοκιμάστε το [*Presentation Patterns*](https://presentationpatterns.com/) των Neal Ford, Matthew McCollough, και Nathaniel Schutta.
    Παρέχει ένα σύνολο αποτελεσματικών μοτίβων (χαμηλού και υψηλού επιπέδου) που μπορείτε να εφαρμόσετε για να βελτιώσετε τις παρουσιάσεις σας.

-   Εάν δίνετε ακαδημαϊκές ομιλίες μπορεί να σας αρέσει το [*Leek group guide to giving talks*](https://github.com/jtleek/talkguide).

-   Αν και δεν το έχουμε οι ίδιο, έχουμε ακούσει καλά λόγια για το διαδικτυακό μάθημα του Matt McGarrity για τη δημόσια ομιλία σε κοινό: <https://www.coursera.org/learn/public-speaking>.

-   Εάν δημιουργείτε πολλά dashboards, φροντίστε να διαβάσετε το [*Information Dashboard Design: The Effective Visual Communication of Data*](https://www.amazon.com/Information-Dashboard-Design-Effective-Communication/dp/0596100167) του Stephen Few.
    Θα σας βοηθήσει να δημιουργείτε dashboards που είναι πραγματικά χρήσιμα, κι όχι απλά όμορφα στην όψη.

-   Η αποτελεσματική επικοινωνία των ιδεών σας συχνά επωφελείται από κάποιες γνώσεις γραφιστικής.
    Το [*The Non-Designer's Design Book*](https://www.amazon.com/Non-Designers-Design-Book-4th/dp/0133966151) της Robin Williams είναι ένα καλό σημείο για να ξεκινήσετε.