05-extensions.Rmd

---
output:
  #bookdown::html_document2: default
  #bookdown::word_document2: default
  bookdown::pdf_document2: 
    template: templates/brief_template.tex
    citation_package: biblatex
documentclass: book
#bibliography: [bibliography/references.bib, bibliography/additional-references.bib]
---

```{block type='savequote', include=knitr::is_latex_output(), quote_author='(ref:darwin-quote)'}
There is grandeur in this view of life, with its several powers, having been originally breathed into a few forms or into one; and that, whilst this planet has gone cycling on according to the fixed law of gravity, from so simple a beginning endless forms most beautiful and most wonderful have been, and are being, evolved.

```
(ref:darwin-quote) --- Charles Darwin [@Darwin1859]
  
# Customizzazioni ed estensioni
\minitoc <!-- this will include a mini table of contents-->

<!-- LaTeX normally does not indent the first line after a heading - however, it does so after the mini table of contents. You can manually tell it not to with \noindent -->

\noindent Questo capitolo descrive una serie di suggerimenti e trucchi aggiuntivi, nonché possibili personalizzazioni alla tesi scritta con `cattolicadown`.

## cache di chunk e la cartella **\_bookdown\_files**

Se si imposta `cache = true` in un blocco di codice si memorizzano i risultati dell'output del chunk. Quindi se il calcolo richiede tempo è utile. Consulta [la documentazione R Markdown](https://bookdown.org/yihui/rmarkdown-cookbook/cache. HTML). I files memorizzati così finiscono in una cache appunto nella cartella **_bookdown_files**.

Se non usi la cache e desideri semplicemente eliminare la cartella **_ bookdown_files **  dopo il completamento del processo di build, impostare `allow_cache = false` in **index.rmd **.

Cioè, a questo punto il tuo yaml dovrebbe assomigliare a questo:

```yaml
knit: (function(input, ...) {
    thesis_formats <- "pdf";
    
    source("scripts_and_filters/knit-functions.R");
    knit_thesis(input, thesis_formats, allow_cache = FALSE, ...)
  })
```

## Fronte Pagina
### Accorcia le didascalie mostrate nell'elenco delle figure (PDF)
Potresti voler che il tuo elenco di cifre (che segue il contenuto del contenuto) abbia descrizioni di figure più brevi (o semplicemente diverse) rispetto alle didascalie alla figura effettiva.

Fallo usando l'opzione chunk `fig.scap` ('didascalia breve'), ad esempio` {R Captain-Image, fig.cap = "Una didascalia molto lunga e descrittiva (e potenzialmente noiosa) che non si adatta alla Elenco delle figure, ma aiuta il lettore a capire cosa comunica la figura. ", fig.scap =" Una descrizione concisa per l'elenco delle figure "`

### abbrevia le didascalie visualizzate nell'elenco delle tabelle (PDF)
È possibile che l'elenco delle tabelle (che segue l'elenco delle figure nel frontespizio della tesi) abbia descrizioni delle tabelle più brevi (o semplicemente diverse) rispetto alle didascalie delle tabelle stesse.

Se stai usando `knitr::kable` per generare una tabella, puoi farlo con l'argomento `caption.short`, ad esempio:
```r
knitr::kable(mtcars,
              caption = "Una didascalia molto lunga e descrittiva (e potenzialmente
               noioso) che non si adatta all'elenco delle figure,
               ma aiuta il lettore a capire cosa la figura
               comunica.",
              caption.short = "Una descrizione concisa per l'elenco delle tabelle")
```

## Accorciare l'intestazione (PDF)
Potresti voler l'intestazione nel mezzo di un capitolo (ovvero l'intestazione che mostra il titolo all'interno dell'attuale capitolo nella parte superiore della pagina) è più breve (o semplicemente diversa) rispetto al titolo del capitolo effettivo.

Fallo aggiungendo il comando latex `\ capitolo {la mia versione più corta}` dopo il titolo del capitolo.

Ad esempio, il capitolo \ @ref (cittadini e refs) è semplicemente "cita e cross-refs", perché inizia così:

```markdown
# Citations, cross-references, and collaboration {#cites-and-refs} 
\chaptermark{Cites and cross-refs}
```

## Capitoli non numerati
Per rendere i capitoli non numerati (normalmente lo fai per l'introduzione e/o la conclusione), far seguire l'intestazione del capitolo a `{-}`, ad es. così: `# Introduzione {-}`.

Quando lo fai, ricordati che devi anche mettere questi due comandi in LaTeX:
```latex
\adjustmtc
\markboth{The Name of Your Unnumbered Chapter}{}
```

Altrimenti il mini-sommario del capitolo e l'intestazione mostreranno il capitolo precedente.


## Capitoli iniziali con citazioni (PDF)
Il modello di LaTeX di Oxthesis ti consente di includere anche un blocco di tipo `savequote` all'inizio dei capitoli.
Per farlo, usa la sintassi `` `` `` {block type = 'savequote'} `` ``.^[Per ulteriori informazioni sui tipi di blocchi personalizzati, consultare la sezione in [_authoring libri con r markdown _] (https (https : //bookdown.org/yihui/bookdown/custom-blocks.html).]

Aggiungi la referenza della citazione con l'opzione chunk `quote_author =" il mio nome autore "`.
Ti consiglio anche di aggiungere l'opzione chunk `include = knitr::is_latex_output()` in modo che le citazioni siano incluse solo nell'output PDF.

Non è possibile utilizzare la sintassi di Markdown all'interno delle opzioni di chunk, quindi se si desidera ad es. in corsivo un nome del libro usa  ['Testo Reference'](https://bookdown.org/yihui/Bookdown/markdown-extensions-by-Bookdown.html#text-references): crea un pezzo di testo chiamato con '(rif: etichetta) il mio testo', quindi indica questo nell'opzione chunk con `quote_author = '(rif: etichetta)'`.


## Evidenziazione delle correzioni (HTML e PDF)
Quando arriva il momento di fare correzioni, potresti voler evidenziare le modifiche apportate corretta agli esaminatori in modo che possano verificare rapidamente di le cose cambiate
Puoi farlo così:

### correzioni in linea brevi
Evidenzia **correzioni brevi e inline ** facendo `[come questo] {.correction}` --- Il testo tra le parentesi quadrate verrà quindi [evidenziato in blu]{.correction} nell'output.

Si noti che Pandoc potrebbe essere confuso da citazioni e riferimenti incrociati all'interno delle correzioni in linea.
In particolare, potrebbe essere confuso da `" [cosa ha detto @shea2014] {.correction} "` che diventa [cosa ha detto @shea2014] {. Correzione}
In tali casi, è possibile utilizzare direttamente la sintassi in lattice.
L'evidenziazione della correzione usa il pacchetto [Soul] (https://ctan.org/pkg/soul), quindi puoi fare così:

- Se si utilizza BiBLATEX per i riferimenti, usa `\ hl {What \ textCite {Shea2014} detto}}
- Se si utilizza Natbib per riferimenti, usa `\ hl {cosa \ cite {shea2014} detto}}

L'uso di LaTeX grezzo ha lo svantaggio delle correzioni, quindi non viene visualizzata nell'output HTML, ma potresti comunque preoccuparti dell'evidenziazione della correzione nel PDF per gli esaminatori!


### blocchi di materiale aggiunto o modificato
Evidenzia interi ** blocchi di materiale aggiunto o modificato ** mettendoli in un blocco di tipo `correzione`, usando la sintassi` `` `` `{Block type = 'correction'}` ``.^[In Il file **. tex ** per output PDF, questo metterà il contenuto tra `\ inizio {correzione}` e `\ end {correzione}`; Nell'output di GitBook sarà messo tra `<Div class =" Correction ">` e `</div>`.]
Così:

```{block type='correction', include=knitr::is_latex_output() | knitr::is_html_output()}
Per blocchi più grandi, come questo paragrafo o addirittura intere figure, è possibile utilizzare il tipo di blocco "Correction". Questo ambiente **mette in evidenza blocchi di dimensioni del paragrafo e più grandi** con lo stesso colore blu.
```

*Si noti che i blocchi di correzione non possono essere inclusi nell'output delle parole.*

### che interrompe le correzioni da essere evidenziate
Per disattivare l'evidenziazione della correzione, vai all'intestazione YAML di **index.Rmd **, quindi:

- Output PDF: Imposta `corrections: false` \
- output HTML: rimuovi o commenta `- modelli/corrections.css`


## Applicare il colore del carattere personalizzato ed evidenziazione a testo (HTML e PDF)
Il filtro LUA che aggiunge la funzionalità di evidenziare le correzioni aggiunge altri due trucchi:
Puoi applicare la tua scelta di colore per evidenziare il testo o cambiare il colore del carattere.
La sintassi è la seguente:

> Ecco `[qualche testo da evidenziare] {highlight = "pink" }` \
> Diventa: ecco [alcuni testi in evidenza rosa] {highlight = "pink"}.

> `[Ecco un po 'di testo con font blu] {color = "blue" }` \
> Diventa: [Ecco un po 'di testo con font blu] {color = "blue"}

> Finalmente --- Mai e poi mai in realtà questo-`[Ecco un po 'di testo con evidenziazione nera e carattere giallo] {highlight = "black", color = "yellow"}` \
> Diventa: [Ecco un po 'di testo da evidenziaziare in nero e con colore del carattere giallo] {highlight = "black" color = "yellow"}

Il file **Scripts_and_filters/Colour_and_highlight.lua ** serve proprio a questo. Funziona sia con output PDF che HTML. Divertiti a modificarlo o ad aggiungerne altri!

## Aggiunta di un secondo estratto (PDF)
Potresti aver bisogno di due abstract nella tua tesi, se ad es. hai bisogno sia di un astratto in inglese che in un'altra lingua.


Puoi aggiungere un secondo abstract in **index.rmd ** come: così:

``` yaml
abstract-second-heading: "Resumé"
abstract-second: "This is the second abstract, for example in beautiful French." 
```
## incluso un altro documento nella tesi - Incorporare un documento PDF {#embed-pdf}

Potresti voler incorporare documenti PDF esistenti nella tesi, ad esempio se il tuo dipartimento consente una tesi in stile "portfolio" (cioè una raccolta di articoli) e devi includere una o più pubblicazioni.

Nell'output di GitBook, puoi semplicemente usare `knitr::include_graphics` e dovrebbe includere un PDF scorrevole (e scaricabile).
Probabilmente vorrai impostare le opzioni di chunk `out.width = '100%'` e `out.height = '1000px'`:

```{r, eval=knitr::is_html_output(), out.width='100%', out.height='1000px'}
knitr::include_graphics("figures/sample-content/pdf_embed_example/Lyngs2020_FB.pdf")
```
<br>

Nell'output in LaTeX, tuttavia, questo approccio può causare comportamenti strani.
Pertanto, quando si crea la tesi su PDF, dividere il PDF in una sequenza alfanumericamente ordinata di **file pdf ** a pagina singola, puoi farlo automaticamente con il pacchetto `pdftools`). È quindi possibile utilizzare il comando in LaTeX appropriato per inserirli, come mostrato di seguito (per brevità, nel contenuto di esempio di `cattolicadown` PDF stiamo includendo solo due pagine).
*Si noti che l'opzione chunk `risultati = 'asis'` deve essere impostata.*
È inoltre possibile rimuovere i margini dai file PDF, che puoi fare con Adobe Acrobat (versione a pagamento) e probabilmente altri software open source online.

```{r, echo=TRUE, results='asis', eval=knitr::is_latex_output(), linewidth = 70}
# install.packages(pdftools)
# split PDF into pages stored in figures/sample-content/pdf_embed_example/split/
# pdftools::pdf_split("figures/sample-content/pdf_embed_example/Lyngs2020_FB.pdf",
#        output = "figures/sample-content/pdf_embed_example/split/")

# grab the pages
pages <- list.files("figures/sample-content/pdf_embed_example/split", full.names = TRUE)

# set how wide you want the inserted PDFs to be: 
# 1.0 is 100 per cent of the oxforddown PDF page width;
# you may want to make it a bit bigger
pdf_width <- 1.2

# for each PDF page, insert it nicely and
# end with a page break
cat(stringr::str_c("\\newpage \\begin{center} \\makebox[\\linewidth][c]{\\includegraphics[width=", pdf_width, "\\linewidth]{", pages, "}} \\end{center}"))

```

## includere un altro documento nella tesi - documento Rmd dentro Rmd (child markdown) {#embed-rmd}

A volte vuoi poter includere un altro documento che stai attualmente scrivendo come capitolo della tua tesi.
Sopra \@ref(embed-pdf), abbiamo descritto il modo più semplice per farlo: includere l'altro documento come PDF nel PDF.
Tuttavia, in alcuni casi invece si desidera includere la sorgente R markdown, quindi ancora un altro ducumento .Rmd in questo documento e farlo compilare all'interno della tesi.
Questo è un po 'più complicato, perché è necessario tenere traccia attenta dei percorsi dei file, ma è possibile tramite [l'inclusiome del child document ](https://bookdown.org/yihui/rmarkdown-cookbook/child -Document.html).
Sono quattro i passaggi principali:

1. Includi il documento Markdown come child
1. Rendi i percorsi di file compatibili col knit
1. Rendi corretti i livelli di intestazione (armonizza le impostazioni di formattazione per scrittura)
1. Rendi corretti le larghezze della figura (armonizza le impostazioni di formattazione per figure)

### Un documento di esempio in un'altra cartella
Prendi questo esempio (i file per questo sono in [questo repository github](https://github.com/ulyngs/oxforddown-external-article)):


```markdown 
|--paper_to_include
|  |--my_paper.Rmd
|  |--data
|  |  |--cat_salt.csv
|  |--figures
|  |  |--cat.jpg
|
|--thesis
```

Come suggerisce il grafico, hai un'altra cartella, **paper_to_include/** che sta nella stessa cartella contenente la tesi.
Nella cartella **paper_to_include **, il file **my_paper.Rmd ** è quello da includere.
In **my_paper.Rmd **, hai letto un file CSV che si trova nella sottocartella **data/cats.csv ** e anche un'immagine della sottocartella **figures/cat.jpg **.

### PASSAGGIO 1: includere il documento come child
Nella cartella di tesi, crea un file .Rmd per il capitolo in cui si desidera includere un altro documento.
Aggiungi uno o più blocchi di codice che includono i file di .Rmd da quel documento come documenti figlio:

````markdown
# Including an external chapter 

`r ''````{r child = "../paper_to_include/my_paper.Rmd"}
```
````

### Passaggio 2: Rendi compatibili i percorsi dei files
Utilizzare [Parametri](https://rmarkdown.studio.com/lesson-6.html) per regolare il percorso del file delle immagini in base ai valori impostati nell'intestazione YAML di un file di markdown R.
In **my_paper.rmd **, crea un parametro chiamato `other_path` e impostalo su una stringa vuota:

```yaml
---
title: "A fabulous article in a different folder"
params:
  other_path: ""
---
```

In **my_paper.rmd **, mettilo all'inizio di FilePath quando leggi i dati o includi immagini:

```r
library(tidyverse)
library(knitr)

cat_data <- read_csv(str_c(params$other_path, "data/cats.csv"))
include_graphics(str_c(params$other_path, "figures/cat.jpg"))
```
Infine, nel file **index.rmd ** della cartella tesi, crea anche il parametro `other_path`.
Ma qui, impostalo su dove la cartella **paper_to_include/** è relativa alla cartella di tesi:

```yaml
params:
  other_path: "../paper_to_include/"
```

### NOTA sull'output HTML
Nota che se si desidera ospitare una versione HTML della tesi online, dovrai mettere i contenuti figli offline (cioè in una cartella in lcoale) pubblicati online (tipo in un Drive) - Internet ovviamente non sarà in grado di vedere i filepath che si riferiscono a cose in un'altra cartella il tuo computer!


### Passaggio 3: assicurarsi che i livelli di intestazione siano corretti
A meno che il documento che desideri includere non sia scritto come un libro, probabilmente i livelli di intestazione saranno fuori dalle righe.
Cioè, le intestazioni di livello 1 (\# alcune intestazioni) che usi per le sezioni principali nell'altra carta si trasformano in titoli di accompagnatore se incluse nella tesi.

Per evitare questo, prima _increment tutti i livelli di intestazione di uno in **paper_to_include/my_paper.rmd ** _ (\# qualche intestazione -> \# \# Qualche intestazione).
Quindi in **paper_to_include/** Crea un [filtro Lua] (https://bookdown.org/yihui/rmarkdown-cookbook/lua-fiterters.html#lua-filters) che riduce i livelli di intestazione di uno: creare un file di testo , salvalo come ** ridotto_header_level.lua ** e dargli il contenuto di seguito.

```lua
function Header(el)
  if (el.level <= 1) then
    error("I don't know how to decrease the level of h1")
  end
  el.level = el.level - 1
  return el
end
```

Nell'intestazione Yaml di **paper_to_include/my_paper.rmd **, usa questo filtro:

```yaml
---
title: "A fabulous article in a different folder"
params:
  other_path: ""
output:
  pdf_document: 
    pandoc_args: ["--lua-filter=reduce_header_level.lua"]
---
```
Ora, i livelli di intestazione saranno corretti sia quando si lavora da sola e quando è incluso nella tesi.

Nota: potrebbe non essere necessario utilizzare un filtro LUA per spostare l'intestazione-Sembra che potresti semplicemente usare `Pandoc_args: ["-Shift-Heading-level-by = -1 "]` (vedi https: // pandoc. org/manual.html#lettore-opzioni)

### Passaggio 4. Assicurarsi che le larghezze della figura siano corrette
Potrebbe essere che le larghezze della tua figura quando si lavorano a maglia da sola e, quando lo includi nella tesi, debbano essere diversi.
È possibile utilizzare nuovamente i parametri per impostare le larghezze delle figure.

Immagina di volere che la larghezza della figura sia l'80% della larghezza della pagina quando si lavora da sola, ma al 100% nella tesi.
In **paper_to_include/my_paper.rmd **, prima aggiungi un parametro che potremmo chiamare `out_width` e impostarlo sulla stringa" 80%":

```yaml
---
title: "A fabulous article in a different folder"
params:
  other_path: ""
  out_width: "80%"
output:
  pdf_document: 
    pandoc_args: ["--lua-filter=reduce_header_level.lua"]
---
```

Quindi, assicurati di utilizzare quel parametro per impostare la larghezza dell'uscita quando si includono le figure in **paper_to_include/my_paper.rmd **:

````markdown
`r ''````{r, out.width=params$out_width, fig.cap="A very funny cat"}
include_graphics(str_c(params$other_path, "figures/cat.jpg"))
```
````

Infine, stabilisci il parametro `out_width` per tua tesi '**index.rmd ** File:

```yaml
params:
  other_path: "../paper_to_include/"
  out_width: "80%"
```

Ora, la larghezza di output della tuo documento child sarà dell'80%.

## Personalizzazione di citazioni e riferimenti {#customising-citations}

### Utilizzo di un file .csl con pandoc
Vedere la sezione \@ref(citation-appearance).

L'unico svantaggio di lasciare che pandoc gestisca le citazioni è che (i) non supporta le bibliografie dei capitoli, (ii) se sei un veterano di LaTeX, potresti essere più a tuo agio con `bilatex` o `natbib`.

### Utilizzo di `bilatex` {#bilatex-custom}
Per utilizzare [biblatex](https://www.overleaf.com/learn/latex/Bibliography_management_with_biblatex) per gestire le citazioni, prima decommenta questo in **index.Rmd**, YAML header:

```markdown
use-biblatex: true
bib-latex-options: "style=authoryear, sorting=nyt, backend=biber, maxcitenames=2, useprefix, doi=true, isbn=false, uniquename=false"
```

Quindi dì a R Markdown di usare `biblatex` quando inserisci le citazioni, impostando `citation_package: biblatex`:

```markdown
output:
  bookdown::pdf_book:
    citation_package: biblatex
```

Per personalizzare l'aspetto delle citazioni, cambia `bib-latex-options`. Ad esempio, per ottenere **citazioni numeriche**, con riferimenti in ordine di apparizione nel testo, impostarlo su

```markdown
bib-latex-options: "style=numeric-comp, sorting=none, backend=biber, maxcitenames=2, useprefix, doi=true, isbn=false, uniquename=false"
```

#### Aggiunta di bibliografie di capitoli
Se desideri bibliografie di capitoli, prima aggiungi "refsection=chapter" alle opzioni biblatex, ad esempio in questo modo:

```markdown
bib-latex-options: "refsection=chapter, style=authoryear, sorting=nyt, backend=biber, maxcitenames=2, useprefix, doi=true, isbn=false, uniquename=false"
```

In secondo luogo, imposta il parametro `insertHeadingInPDF: false` in **index.Rmd**, per eliminare l'inclusione di un'intestazione 'Riferimenti' alla fine della tesi.

```markdown
params:
  insertHeadingInPDF: false
```

Infine inserisci questa riga alla fine di ogni capitolo, per stamparvi le bibliografie:

```latex
\printbibliography[segment=\therefsection,heading=subbibliography]
```


### Utilizzo di `natbib` {#natbib-custom}
Per utilizzare [natbib](https://www.overleaf.com/learn/latex/Bibliography_management_with_natbib) per gestire le citazioni, prima decommenta questo in **index.Rmd**, YAML header:

```markdown
use-natbib: true
natbib-citation-style: authoryear #for science, you might want numbers,square
natbib-bibliography-style: templates/ACM-Reference-Format.bst #e.g. "plainnat", unsrtnat, or path to a .bst file
```

Quindi dì a R Markdown di usare `natbib` quando inserisci le citazioni, impostando `citation_package: natbib`:

```markdown
output:
  bookdown::pdf_book:
    citation_package: natbib
```

Per personalizzare l'aspetto delle citazioni, cambia il file **.bst** a cui punti in `natbib-bibliography-style`.

## Customizing the page headers and footers (PDF)
## Personalizzazione delle intestazioni e dei piè di pagina di pagina (PDF)

Questo può ora essere fatto direttamente nell'intestazione YAML di **index.rmd **.
Se sei un esperto di lattice e hai bisogno di ulteriore personalizzazione che ciò che è attualmente fornito, è possibile modificare le sezioni pertinenti di **models/template.tex ** - Il codice pertinente è sotto la linea che inizia `\usepackage{FancyHdr}`.

## immergersi nel modello di lattice di Oxthesis (PDF)
Per le persone di mentalità in lattice, puoi leggere **models/template.tex ** Per vedere quali opzioni di personalizzazione aggiuntive sono disponibili e **models/ociamthesis.cls ** che fornisce la classe base.
Ad esempio, **template.tex ** fornisce un'opzione per le comunicazioni di laurea Master, che modifica le informazioni identificative al numero del candidato e include un conteggio delle parole.
Al momento della stesura, è necessario impostarlo direttamente in **template.tex ** anziché dall'intestazione Yaml in **index.rmd **.


## personalizzazione in un'altra università
### il percorso minimo
Se la questione anteriore nel modello di LaTeX di Oxthesis è adatta alla tua università, personalizzare `cattolicadown` alle tue esigenze potrebbe essere semplice come mettere il nome della tua istituzione e il percorso per il logo della tua università in **index.rmd **:

```yaml
university: University of the street
university-logo: figures/your-logo-here.pdf
```

### Sostituzione dell'intera pagina del titolo con il contenuto richiesto
Se hai un file **.tex ** con una questione frontale richiesta dalla tua università che si desidera sostituire del tutto la pagina del titolo del modello di oxthesis, puoi fornire un filepath a questo file in **index.rmd **.
Il contenuto di esempio di `cattolicadown include ed esempio di questo --- Se usi lo yaml di seguito, la questione anteriore sarà così:

```yaml
alternative-title-page: front-and-back-matter/alt-title-page-example.tex
````

```{r, echo=FALSE, eval=knitr::is_html_output(), out.width='100%', out.height='1000px'}
knitr::include_graphics("figures/sample-content/alt_frontmatter_example/alt-frontmatter-example.pdf")
```

\noindent
```{r, echo=FALSE, out.width='100%', out.height='1000px', results='asis', eval=knitr::is_latex_output}
# grab the pages
pages <- list.files("figures/sample-content/alt_frontmatter_example/split", full.names = TRUE)

pdf_width <- 0.32

cat(stringr::str_c("\\fbox{\\includegraphics[width=", pdf_width, "\\linewidth]{", pages, "}}"))
```