From 7d255ce7b57cd75276bd43375504a92e6b914a4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miquel=20Perell=C3=B3=20Nieto?= Date: Wed, 24 Jul 2024 10:32:21 +0100 Subject: [PATCH] Added introduction and ignore some files --- .gitignore | 2 + _quarto.yml | 1 + assets/introduction/.style.css.swp | Bin 0 -> 12288 bytes assets/introduction/style.css | 3 + introduction.qmd | 285 +++++++++++++++++++++++++++++ 5 files changed, 291 insertions(+) create mode 100644 .gitignore create mode 100644 assets/introduction/.style.css.swp create mode 100644 assets/introduction/style.css create mode 100644 introduction.qmd diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4d7fb32 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/.quarto/ +_site diff --git a/_quarto.yml b/_quarto.yml index 4a85b84..9f0fd37 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -19,6 +19,7 @@ website: url: https://github.com/IntelligentSystemsLaboratory - href: index.qmd text: Home + - introduction.qmd - about.qmd diff --git a/assets/introduction/.style.css.swp b/assets/introduction/.style.css.swp new file mode 100644 index 0000000000000000000000000000000000000000..bc26aaff9b38b98ec2ee1a669b67ae2052e39398 GIT binary patch literal 12288 zcmeI%J5Iwu5P;zc)CdF@SRSokpg0CfsuXlU2{L3&ES%VQH$;Gdf{RdcgIoh~2+n~m zISoZfo9JK38jWXmwexkBulc+XyC21+%{^luGwt3O^WTxw5kO!bfssv| zXiX0G1HW$H-Pu-Ko9FZFqz3^65I_I{1Q0*~0R)yrz!oiet7chg=2>lG>rZS_0s;si zfB*srAb +author: + - name: + given: Miquel + family: Perello Nieto + orcid: 0000-0001-8925-424X + email: miquel.perellonieto@bristol.ac.uk + affiliations: + - name: University of Bristol + city: Bristol + country: United Kingdom + postal-code: BS8 1QU + attributes: + equal-contributor: False +format: + html: default + revealjs: + output-file: slides-quarto.html + width: 960 + height: 700 + css: assets/introduction/style.css +--- + +# Gentle reminder of the publishing workflow + +::: {.content-hidden when-format="revealjs"} +The **publishing workflow** is the process in which external resources are +prepared and collated together with the help of an **authoring tool** and +subsequently rendered with a **formatting tool** to generate a publishable +output that can be delivered in various forms. This is visualised by the +following figure. +::: + +```{mermaid} +--- +Publishing workflow +--- +%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%% +flowchart LR + + E1("(1)\nExternal resources"):::external -.-> A1 + A1{{"(2)\nAuthoring tool"}} --> I1("(3)\nText + Figures +\nCode + Tables + ..."):::input + I1 --> P1{{"(4)\nFormatting tool"}} + P1 --> O1["(5)\nFormatted\nOutput"]:::output + O1 -.-> D1{{"(6)\nDelivery system"}}:::delivery + classDef external fill:#eee,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5; + classDef input fill:#ffa; + classDef output fill:#faa; + classDef delivery stroke:#666,stroke-width:2px,stroke-dasharray: 5 5; +``` + +::: {.content-hidden when-format="revealjs"} +An example of a publishing workflow is the following. A research group may +carry out an investigation which ends up with **(1)** data, figures, analyses, +and results, those resources are put together with an **(2)** authoring tool +like Overleaf which produces an **(3)** organised hierarchy of files and text +that includes formatting information, then using a **(4)** formatting tool like +pdfLaTeX all the artefacts are combined into a **(5)** pdf document that can be +**(6a)** printed as a stand-alone document, or **(6b)** included into the +proceedings of a conference. + +::: + +# Quarto is a formatting tool + +::: {.content-hidden when-format="revealjs"} +**Formatting tools** take input artefacts produced by authoring tools and +produce publishable formatted output. While many of the authoring tools +discussed in the previous section are well-known, there have been many recent +developments in formatting tools that deserve to be better known in the +academic community as they take opportunities for publishing training material +to the next level. In the previous section we described the two +paradigms [](sec:SISO) (SISO) and [](sec:SIMO) (SIMO). In +this section we describe some _formatting tools_ that can be used for the SIMO +paradigm. +::: + +```{mermaid} +%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%% + +flowchart LR + + E1("External resources"):::external -.-> A1 + A1{{"Authoring tool"}} --> I1("Text + Figures +\nCode + Tables + ..."):::input + subgraph "Quarto, pdflatex, xelatex, pandoc, ..." + direction LR + I1 --> P1{{"Formatting tool"}} + P1 --> O1["Formatted\nOutput"]:::output + end + classDef external fill:#eee; + classDef input fill:#ffa; + classDef output fill:#faa; +``` + + +# Quarto as a Single-In-Multi-Out + +The creation of research or academic material usually involves the production +of slides, documents, posters and other output formats from the same material. +There are different paradigms to create publishing material: + +- **Single-In-Single-Out tools**: Specialise in generating one type of output. + - E.g. text documents with [Microsoft + Word](https://www.microsoft.com/en-gb/microsoft-365/word), [Libre Office +Writer](https://www.libreoffice.org/discover/writer/), +[LaTeX](https://www.latex-project.org/); slide decks with [Microsoft +PowerPoint](https://www.microsoft.com/en-gb/microsoft-365/powerpoint), +[LibreOffice Impress](https://www.libreoffice.org/discover/impress/), [LaTeX +Beamer](https://ctan.org/pkg/beamer), [Reveal.js](https://revealjs.com/), or +[Google Slides](https://workspace.google.com/intl/en_uk/products/slides/); and +posters with [Microsoft +Publisher](https://www.microsoft.com/en-gb/microsoft-365/publisher), Google +Slides, LaTeX, etc. +- **Single-In-Multi-Out tools**: Can generate multiple types of publication + formats from a joint set of input artefacts. +- **Multi-In-Multi-Out tools**: Can generate multiple types of publication + formats by composing input artefacts from different locations. + + +::: {.content-hidden when-format="revealjs"} +More recent publishing systems allow the generation of multiple types of +publication formats from a joint set of input artefacts. We refer to this +paradigm as Single-In-Multi-Out (SIMO). This paradigm offers various +benefits, among them: +- keeping the artefacts in a single, well-defined location which facilitates consistency, management and findability; +- keeping a unique source of history changes and versions which is useful for auditing and +transparency; and +- not duplicating artefacts that are not changed between different publishing systems. +::: + +```{mermaid} +%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%% + +flowchart LR + I1("(3)\nText + Figures + \n Code + ..."):::input --- dummy2{{"(4) Quarto\nFormatting tool"}} + dummy2 --> O1["(5a) Published \n Paper \n (PDF)"] + dummy2 --> O2["(5b) Presentation \n Slides \n (PPTX/PDF)"] + dummy2 --> O3["(5c) Poster \n (PPTX/PDF)"] + dummy2 --> O4["(5d) Computational \n Notebook \n (Colab)"] + classDef input fill:#ffa; + style O1 fill:#fca + style O2 fill:#bff + style O3 fill:#f99 + style O4 fill:#bfb +``` + +::: {.content-hidden when-format="revealjs"} +Nowadays, the SIMO type of formatting tool is becoming more common, and we +focus on the state-of-the-art formatting tools that fall into this category in this roadmap. +The roadmap document itself is an example of one particular tool (`Jupyter Book`), while the +rest of the document and use cases also include examples built with `Quarto`. A description of these +and other publishing tools is provided with more detail in the next section +[](sec:formatting-tools). +::: + +# Installation and usage + +- Get started documentation: [quarto.org/docs/get-started/](https://quarto.org/docs/get-started/) +- Open-source repository in GitHub: [Quarto-cli](https://github.com/quarto-dev/quarto-cli) +- Create a project with `quarto create project` + - Type: default, website, blog, manuscript, book, confluence +- Build project with `quarto render` +- Preview with `quarto preview` (it autobuilds and updates when changes in the + source files are detected). + +# Authoring for Quarto + +::: {.content-hidden when-format="revealjs"} +**Authoring tools** facilitate the creation of input artefacts (e.g. plain +text, markup language, tables, figures, code, or equations) which will be +compiled and rendered by a _formatting tool_ to generate publishable outputs. +For example, a markup language editor to create LaTeX is an authoring tool, +while `pdflatex`, `XeLaTeX`, or `LuaTeX` are formatting tools that compile +input artefacts to pdf. These tools need to integrate metadata about the format +in which the artefacts need to be formatted in different output types. +For example, the font of the text and its position, the position of figures, +tables and other elements. In this roadmap we focus on authoring tools that +can be used for the purpose of multi-output publishing systems. We provide some +guidelines on the type of files that need to be considered during the authoring +process, which tools can directly help on the generation of those artefacts. We +consider the collaboration of teams in the authoring process as a desirable +feature. +::: + +```{mermaid} +%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%% +flowchart LR + + E1("External resources"):::external -.-> A1 + subgraph "Vim, NeoVim, Notepad" + direction LR + A1{{"Authoring tool"}} --> I1("Text + Code +\nTables + ..."):::input + end + I1 --> P1{{"Formatting tool"}} + P1 --> O1["Formatted\nOutput"]:::output + classDef external fill:#eee; + classDef input fill:#ffa; + classDef output fill:#faa; +``` + +::: {.content-hidden when-format="revealjs"} +Authoring tools that do not incorporate part of the formatting are rare, as it +is common to provide at least a preview of the formatted output. +Examples of authoring that can be separated from the formatting step are simple +text editors like vim, NeoVim, Notepad, and general-purpose Integrated +Development Environments (IDEs). +::: + +# Authoring with formatting + +::: {.content-hidden when-format="revealjs"} +There are **authoring tools** that incorporate a **formatting tool**. While in +some situations it is a good practice to separate the two aspects, some +computer programs integrate them in one tool that may (or may not) provide +access to the intermediate artefacts. For example, Overleaf +provides an online collaborative authoring platform that integrates with +_pdfLatex_ in the back-end. +::: + +```{mermaid} +%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%% +flowchart LR + + E1("External resources"):::external -.-> A1 + subgraph "IDE + Quarto, HackMD, Notion, Typst, Overleaf..." + direction LR + A1{{"Authoring tool"}} --> I1("Text + Figures +\nCode + Tables + ..."):::input + I1 --> P1{{"Formatting tool"}} + P1 --> O1["Formatted\nOutput"]:::output + end + classDef external fill:#eee; + classDef input fill:#ffa; + classDef output fill:#faa; +``` + +## Integrated Development Environments + +::: {.content-hidden when-format="revealjs"} +The separation of the source code and the publishable outputs is something that +all Integrated Development Environments (IDEs) provide. These are tools for +writing computer programs that commonly require a compilation phase which is +usually integrated in the same tool. The idea of authoring tools that can +create generic input artefacts that are later combined by a formatting tool +is very similar to the common process followed in programming compiled +programming languages. This has facilitate the adoption of IDEs as authoring +tools. Microsoft Visual Studio and [Posit +Workbench](https://posit.co/products/enterprise/workbench/) (formerly +[RStudio](https://posit.co/download/rstudio-desktop/)) have tools to work with +the `Quarto` environment. Both of them provide options for collaborative and +contemporaneous editing. +::: + +# Then, what is Quarto? + +::: {.content-hidden when-format="revealjs"} + +[Quarto](https://quarto.org) is an open-source publishing system with the +objective of facilitating the creation of scientific content. Quarto is +sponsored by [Posit](https://posit.co), and follows the development of the R +Markdown publishing system extending the focus from the programming language R +to Python, Julia and Observable. It supports Jupyter notebooks, markdown and +their own extension `Quarto` markdown. The conversion to different output +formats is done with [pandoc](https://pandoc.org/), which is able to produce +presentations (Reveal.js), dashboards, websites, blogs, books, PDFs, Microsoft +Word, ePub and more. Quarto is integrated into multiple authoring environments +like Microsoft Visual Studio, Jupyter Lab, +[Rstudio](https://posit.co/download/rstudio-desktop/), and [Atlassian +Confluence](https://www.atlassian.com/software/confluence) among others. + +## Key points +::: + +- [Quarto](https://quarto.org): +- `Quarto` supports dynamic content with Python, R, Julia and Observable +- programming languages. +- `Quarto` uses pandoc to convert the input artefacts to its output. +- `Quarto` supports plain text markdown, Jupyter notebooks and an augmented +- markdown, +- Integration with Posit Connect (former RMarkdown), Atlassian Confluence, Visual + Studio, +- Built with `quarto render` +- Has a preview mode `quarto preview` which autobuilds and updates when + changes in the source files are detected.