commit a64adbc6568a700e13e92d7374270d920394a1ad Author: Gerardo Marx Date: Mon Sep 13 12:13:57 2021 -0500 essay diff --git a/essay-basic.docx b/essay-basic.docx new file mode 100644 index 0000000..cb88447 Binary files /dev/null and b/essay-basic.docx differ diff --git a/essay-basic.html b/essay-basic.html new file mode 100644 index 0000000..ef1310e --- /dev/null +++ b/essay-basic.html @@ -0,0 +1,12 @@ +

Introduction

+

The preparation of documents always takes our minds to relate the usage of specialized software like Microsoft-Word, Word-Pad, Pages, Open-office, and so on. However, many years ago, the preparation of documents, used to be more relaxed and faster; the plain-text fashion. Plain-text documents are files with no format nor specialized information. Instead, plain documents are only text. But, why plain-text documents are so crucial for the academic area? Why these files remain useful? And how can we use them to create high-quality documents? Well, let’s start by explaining some special kinds of documents based in plain-text files; the Markdown files.

+

Formats for academic documents

+

The Markdown format was initially developed by John Gruber in collaboration with Aaron Swartz, to simplify the writing of HTML. Instead of coding a file in HTML syntax, the content of a document is written in plain text and denote with simple tags the final formatting. Subsequently, the MD (Markdown) files are parsed to generate the final HTML document. With this concept, the source file remains easily readable, and the author can focus on the contents rather than formatting.

+

Why MD files are important in academia?

+

Despite its original focus on the web, the MD format has been proven to be great for academic writing. In particular, pandoc-flavored MD adds several extensions that facilitate the authoring of academic documents and their conversion into multiple output formats. The only requirement is to learn the basics of MD-syntax and install the pandoc application to convert the files. Then, the output file can be defined by using some parameters in the input file to create a new different output document. Therefore, it is possible to create tables, bibliography citations, include figures, code sections, special symbols and characters, and the most important only using a plain-text file.

+

Why these files remain useful now?

+

A single word can answer this question: Reproducibility. An MD file can be compiled…, yes compiled; we are talking about programming, … compiled in a different computer, if the pandoc engine is installed on it. And guess what? We can add one more word: traceability. Yes, we can follow how a file is changing its content and support old and new versions. -Hey, check my paper please, this is only a simple plain text, and you will not have problems of compatibility-, right? In most of the cases, there should no be a problem

+

How can we use them to create high-quality documents?

+

By using pandoc there is possible to produce ‘.tex’ files and then produce a PDF-formated document. When the TeX file is generated, the document’s quality can be improved. Even more, the TeX file can be basically modified to create an entirely different document by selecting a new ‘document class’. Nevertheless, from my point of view, the MD files can be used for basic and short documents (proposal, drafts, guides, unformatted articles). In contrast, for more complex documents (thesis, books, formated-articles), it is better to use LaTeX.

+

Whats next?

+

Pandoc is useful for creating basic and short documents; also is a first approach to use more powerful engines like pdflatex and xelatex. Also, the MD files are just plain text files and can be used for controlling versions. Actually, the MD file’s process is commonly used by other IDE systems like r-studio to create complete environments for data science reproducibility.

diff --git a/essay-basic.tex b/essay-basic.tex new file mode 100644 index 0000000..e2bf43e --- /dev/null +++ b/essay-basic.tex @@ -0,0 +1,78 @@ +\hypertarget{introduction}{% +\section{Introduction}\label{introduction}} + +The preparation of documents always takes our minds to relate the usage +of specialized software like Microsoft-Word, Word-Pad, Pages, +Open-office, and so on. However, many years ago, the preparation of +documents, used to be more relaxed and faster; the plain-text fashion. +Plain-text documents are files with no format nor specialized +information. Instead, plain documents are only text. But, why plain-text +documents are so crucial for the academic area? Why these files remain +useful? And how can we use them to create high-quality documents? Well, +let's start by explaining some special kinds of documents based in +plain-text files; the \emph{Markdown files}. + +\hypertarget{formats-for-academic-documents}{% +\section{Formats for academic +documents}\label{formats-for-academic-documents}} + +The Markdown format was initially developed by John Gruber in +collaboration with Aaron Swartz, to simplify the writing of HTML. +Instead of coding a file in HTML syntax, the content of a document is +written in \textbf{plain text} and denote with \emph{simple tags the +final formatting}. Subsequently, the MD (Markdown) files are parsed to +generate the final HTML document. With this concept, the source file +remains easily readable, and the \textbf{author can focus on the +contents rather than formatting}. + +\hypertarget{why-md-files-are-important-in-academia}{% +\subsection{Why MD files are important in +academia?}\label{why-md-files-are-important-in-academia}} + +Despite its original focus on the web, the MD format has been proven to +be great for academic writing. In particular, +\href{http://pandoc.org/}{pandoc-flavored MD} adds several extensions +that facilitate the authoring of academic documents and their conversion +into multiple output formats. The only requirement is to learn the +basics of MD-syntax and install the \emph{pandoc} application to convert +the files. Then, the output file can be defined by using some parameters +in the input file to create a new different output document. Therefore, +it is possible to create tables, bibliography citations, include +figures, code sections, special symbols and characters, and the most +important only using a plain-text file. + +\hypertarget{why-these-files-remain-useful-now}{% +\subsection{Why these files remain useful +now?}\label{why-these-files-remain-useful-now}} + +A single word can answer this question: Reproducibility. An MD file can +be compiled\ldots, yes compiled; we are talking about programming, +\ldots{} compiled in a different computer, if the pandoc engine is +installed on it. And guess what? We can add one more word: traceability. +Yes, we can follow how a file is changing its content and support old +and new versions. -Hey, check my paper please, this is only a simple +plain text, and you will not have problems of compatibility-, right? In +most of the cases, there should no be a problem + +\hypertarget{how-can-we-use-them-to-create-high-quality-documents}{% +\subsection{How can we use them to create high-quality +documents?}\label{how-can-we-use-them-to-create-high-quality-documents}} + +By using pandoc there is possible to produce `.tex' files and then +produce a PDF-formated document. When the TeX file is generated, the +document's quality can be improved. Even more, the TeX file can be +basically modified to create an entirely different document by selecting +a new `document class'. Nevertheless, from my point of view, the MD +files can be used for basic and short documents (proposal, drafts, +guides, unformatted articles). In contrast, for more complex documents +(thesis, books, formated-articles), it is better to use LaTeX. + +\hypertarget{whats-next}{% +\section{Whats next?}\label{whats-next}} + +Pandoc is useful for creating basic and short documents; also is a first +approach to use more powerful engines like pdflatex and xelatex. Also, +the MD files are just plain text files and can be used for controlling +versions. Actually, the MD file's process is commonly used by other IDE +systems like r-studio to create complete environments for data science +reproducibility. diff --git a/essay-basic.txt b/essay-basic.txt new file mode 100644 index 0000000..7a9d50f --- /dev/null +++ b/essay-basic.txt @@ -0,0 +1,29 @@ +--- +title: "How to prepare academic documents avoiding Word" +date: "February 2020" +author: Gerardo Marx Chávez-Campos +--- +# Introduction + +The preparation of documents always takes our minds to relate the usage of specialized software like Microsoft-Word, Word-Pad, Pages, Open-office, and so on. However, many years ago, the preparation of documents, used to be more relaxed and faster; the plain-text fashion. Plain-text documents are files with no format nor specialized information. Instead, plain documents are only text. But, why plain-text documents are so crucial for the academic area? Why these files remain useful? And how can we use them to create high-quality documents? Well, let's start by explaining some special kinds of documents based in plain-text files; the *Markdown files*. + +# Formats for academic documents + +The Markdown format was initially developed by John Gruber in collaboration with Aaron Swartz, to simplify the writing of HTML. Instead of coding a file in HTML syntax, the content of a document is written in **plain text** and denote with *simple tags the final formatting*. Subsequently, the MD (Markdown) files are parsed to generate the final HTML document. With this concept, the source file remains easily readable, and the **author can focus on the contents rather than formatting**. + +## Why MD files are important in academia? + +Despite its original focus on the web, the MD format has been proven to be great for academic writing. In particular, [pandoc-flavored MD](http://pandoc.org/) adds several extensions that facilitate the authoring of academic documents and their conversion into multiple output formats. The only requirement is to learn the basics of MD-syntax and install the *pandoc* application to convert the files. Then, the output file can be defined by using some parameters in the input file to create a new different output document. Therefore, it is possible to create tables, bibliography citations, include figures, code sections, special symbols and characters, and the most important only using a plain-text file. + +## Why these files remain useful now? + +A single word can answer this question: Reproducibility. An MD file can be compiled..., yes compiled; we are talking about programming, ... compiled in a different computer, if the pandoc engine is installed on it. And guess what? We can add one more word: traceability. Yes, we can follow how a file is changing its content and support old and new versions. -Hey, check my paper please, this is only a simple plain text, and you will not have problems of compatibility-, right? In most of the cases, there should no be a problem + +## How can we use them to create high-quality documents? + +By using pandoc there is possible to produce '.tex' files and then produce a PDF-formated document. When the TeX file is generated, the document's quality can be improved. Even more, the TeX file can be basically modified to create an entirely different document by selecting a new 'document class'. Nevertheless, from my point of view, the MD files can be used for basic and short documents (proposal, drafts, guides, unformatted articles). In contrast, for more complex documents (thesis, books, formated-articles), it is better to use LaTeX. + + +# Whats next? + +Pandoc is useful for creating basic and short documents; also is a first approach to use more powerful engines like pdflatex and xelatex. Also, the MD files are just plain text files and can be used for controlling versions. Actually, the MD file's process is commonly used by other IDE systems like r-studio to create complete environments for data science reproducibility. diff --git a/example.pdf b/example.pdf new file mode 100644 index 0000000..0a6ed41 Binary files /dev/null and b/example.pdf differ