Помимо языков программирования по вашему выбору (и обязанностей), Markdown — это язык разметки (обратите внимание на каламбур), который вам необходимо знать. Фактически, большинство файлов readme на GitHub, представляющих инструкции вашего кода, написаны в Markdown. А Jupyter Notebooks или Google Colab текстовые поля записываются в уценке.

TL;DR: Если в программировании есть текст, это уценка.

Основы уценки

Markdown — это простой язык разметки (например, HTML). Мы печатаем что-то, чтобы получить некоторое форматирование. Основы суперпросты.

Если вы хотите добавить разделы, нумеруйте их с помощью ‘#’. Чем больше вы добавляете, тем глубже погружаетесь в разделы. Таким образом, «###» — это header3 в HTML или 1.1.1, если вам нужны нумерованные разделы. (Есть дополнительные параметры, чтобы установить это).

Курсив делается с использованием ‘*’ в качестве «тега». Жирным шрифтом выделены две звезды «**».

Списки создаются с добавлением новой строки, а затем перечислением элементов либо с -, либо с числами, за которыми следует точка (1., 2., ..). И в основном это все. Вот полный пиздец с уценкой (таблицы хороши!).

(О, да, ссылки html автоматически принимают ссылку. Если вы хотите добавить кликабельный текст к ссылке, используйте синтаксис «[текст для отображения](ссылка для ссылки)».)

Чтобы писать уценку, вам нужен только текстовый редактор, но если вам нужно создавать отчеты, писать статьи или другие формы более структурированного текста, стоит писать уценку, используя другую среду, например RStudio.

Уценка через RStudio: преимущества для ученых

Написание уценки через Rstudio дает ученым и людям, работающим с текстами и данными, большое преимущество: работу можно экспортировать в форматы .pdf, .html и .doc. Кроме того, вы можете контролировать форму вывода, будь то обычный текст или слайд-шоу.

Кроме того, RStudio предлагает вам дополнительные инструменты, такие как управление библиографией, которую вы можете печатать в разных стилях, изменяя параметр (например, LaTeX). Плюс вы получаете темы и макеты.

Установка RStudio

RStudio — это интегрированная среда разработки (сокращенно IDE) для R. R — это отдельный язык программирования, используемый в основном для статистики. Используя R, вы можете отображать данные и анализировать их, но нас это здесь не интересует. Конечно, вам предлагается изучить сильные стороны R.

Мы используем RStudio в качестве расширенного текстового редактора. С помощью RStudio мы можем легко набирать текст уценки, а затем форматировать его и управлять библиографией с помощью специальных команд. Если у вас есть опыт работы с LaTeX, визуальное воздействие RStudio вас не сильно удивит.

Прежде всего, перейдите в раздел загрузки RStudio: https://rstudio.com/products/rstudio/download/. Затем выберите соответствующую версию для вашей системы. Это бесплатно (есть и платные версии, предлагающие больше возможностей).

После того, как вы откроете свой первый сеанс RStudio, перейдите в «Файл» > «Новый файл» > «R Markdown». Введите название и автора и двигайтесь вперед. Теперь вы можете видеть свое окружение. Большая часть этого файла, который вы пишете.

Кратко пробежимся по основным направлениям.

1. RStudio Открыть вкладку "Документы"

Здесь вы перемещаетесь по своим файлам RStudio. У вас может быть открыто несколько файлов одновременно, как в браузере. Все рядом и визуально организовано. Подумайте о работе над разными главами на разных вкладках, а затем соберите оттуда всю книгу. Теперь о том, как сделать это в Word. И плакать.

2. Главное рабочее окно RStudio

Здесь вы пишете свои вещи. У вас есть номера строк, что хорошо, если возникнут проблемы с набором цифр, но в основном это ваша главная страница Word. Если вы посмотрите в своем документе, у вас будет преамбула вроде LaTeX.

Преамбула начинается после трех строк (например, «-») и снова заканчивается тремя строками. Преамбула этого документа выглядит так:

---
title: “Rijeka”
author: “Guglielmo Feis”
date: “10/2/2020”
output:
 html_document: default
 pdf_document: default
---

Вывод в формате HTML отлично подходит для создания электронных книг и быстрой компиляции. Если вам нужен PDF-файл, просто замените вывод на «pdf_document». Используйте «word_document».

(В следующем разделе мы рассмотрим добавление дополнительных элементов управления к нашему файлу, таких как добавление оглавления и добавление библиографии.)

3. Консоль RStudio

Здесь вы выбираете вывод, в который хотите экспортировать, выбираете шаблон, если хотите, настраиваете настройки оглавления, а также части библиографии.

Под этим главным окном у вас есть консоль, которую вы будете вызывать для установки дополнительных пакетов (как вы это делали в LaTeX).

Рабочий процесс RStudio и установка новых пакетов

Вы можете сделать небольшую паузу и, возможно, подумать о выборе другой темы или фона (есть темный фон). Перейдите в раздел "Инструменты" > "Общие параметры" > "Внешний вид".

Мы готовы пойти и начать писать немного Markdown. Тем не менее, чтобы раскрыть весь потенциал имеющихся инструментов, вам может потребоваться расширить возможности RStudio за счет дополнительных ресурсов. Здесь мы кратко коснемся того, как их установить, чтобы вы могли свободно добавлять столько, сколько вам нужно для максимально эффективной работы.

Консоль RStudio важна. Сюда вы идете, если хотите отредактировать свой пакет и улучшить его (что-то похожее на установку Python PIP).

Если вы хотите выяснить, какие пакеты установлены, вам нужно ввести «installed.package («ИМЯ ПАКЕТА»)». RConsole дружелюбен.

Это инструмент с интерфейсом командной строки, поэтому для взаимодействия с ним может потребоваться около 15–20 минут, но он дружелюбно сообщает, что пошло не так, а иногда даже предлагает вам следующий шаг (например: «Вы хотите, чтобы я сделал X, но для этого мне нужно Y. Пожалуйста, установите Y, выполнив Z'. — Если ваши коллеги так же полезны, как консоль RStudio, то вам повезло.)

Вот некоторые дополнительные ресурсы по пакетам R и их установке.

RStudio for Humanities (дополнительные параметры преамбулы)

Как мы уже знаем, в преабле вы определяете все настройки вашего документа. Например, следует ли печатать оглавление и как обращаться с заголовками разделов и нумерацией. Какой стиль библиографии вы предпочитаете, а также общие макеты.

Вот список некоторых мощных опций, которые вы должны добавить под выбором вывода:

  1. toc: TRUE (или yes) — показывает содержание;
  2. toc_depth: значение — решить, насколько глубоким будет содержание;
  3. numbered_sections: TRUE — показывать номера разделов в оглавлении.

Угадайте, что нужно сделать, чтобы не показывать оглавление или цифры.

В качестве упражнения напишите преамбулу к документу под названием «RStudio великолепна, и я знаю, почему», где вы — автор, а дата — текущий день. Вы хотите напечатать оглавление без номеров и хотите показать разделы, подразделы и подразделы.

Хорошо, ниже код.

Готовый?

---
title: "RStudio is amazing and I know why"
author: "Enter your name"
date: "enter today's date"
output:
  html_document:
    toc: TRUE 
    toc_depth: 3
    numbered_sections: FALSE
---

(Да, если вам что-то не нужно, вы используете либо FALSE, либо нет.)

Осторожно с форматированием. Лучше вложить все опции и параметры. Если у вас есть ошибки при вязании

Настройка библиографии

В гуманитарных науках огромное количество времени тратится (впустую?) на цикл «отправить-подождать-обвинить рецензента 2-изменить форматирование-отправить в другом месте».

Нынешняя настройка не может обеспечить более быстрые ответы или более качественные обзоры, но может избавить вас от проверки типа и изменения управления запятыми и скобками, когда журнал хочет, чтобы вы проверили, что «Статья следует указаниям автора для библиографий» поставить галочку. (Предполагая, что журнал может перевести свои предпочтения в какой-то стандартный или известный стиль нагрудника).

Чтобы добавить библиографию, все, что нам нужно сделать, это добавить:

Параметр bibliography в преамбуле.

Затем нам нужно указать стиль форматирования (конечно вы поняли, что информация через разные апы, дата автора, полная цитата, чикаго и т.д., ссылки всегда одинаковые, все равно отображаются по разному).

Это хорошо и просто, но нам нужен файл с записями стартовых номеров, сохраненный таким образом, чтобы можно было автоматически управлять различными форматами. Формат файла «.bib». Вы можете легко написать его с помощью текстового редактора, но это требует времени.

Стоит знать, как записываются файлы .bib и как они выглядят, чтобы при необходимости можно было эффективно их настроить. Вот объяснение файлов .bib.

Хорошо, теперь у нас есть общее представление о файлах .bib. Наша цель — получить файл .bib для нашей преамбулы. Затем, через преамбулу, мы будем управлять нашими библиографическими деталями, и мы будем цитировать ссылки в нашем основном документе.

Для создания файла .bib мы можем использовать такие инструменты, как Mendeley или JabRef.

Инструменты позволяют управлять библиографией. Вы можете импортировать данные, которые вы загрузили из различных интернет-баз данных, вы можете просматривать статьи и вставлять их, вы можете изменять свои записи и т. д. Оба программного обеспечения имеют плагины для браузера, позволяющие вам вставлять библиоданные с посещаемых вами страниц.

Вы можете провести сравнение самостоятельно. Компания Mendeley привлекла к этому Springer. JabRef является открытым исходным кодом, вы можете увидеть код и решить проблемы на GitHub (он основан на Java).

(Я решил проблему с огромным файлом .bib с помощью JabRef. Затем я создал новую базу нагрудников с Mendeley, в основном полагаясь на плагин, который работал достаточно прилично. Интеграция Mendeley-Word работала, но не так гладко.)

Пример шаблона библиографии

Хорошо, давайте напишем рабочую преамбулу. Мы добавляем поле библиографии и определяем стиль с помощью «csl» (что означает язык стиля цитирования, совершенно верно, не так ли?).

---
title: "RStudio Bib Demo Cas"
author: "Guglielmo"
date: "9/10/2019"
output:
  pdf_document: default
  bibliography: demobib.bib
  csl: europeanjournal.csl
abstract: Demo showing RStudio bib management
---

В дополнение к нашим обычным параметрам мы добавляем поле «библиография». Далее следует имя файла, содержащего библиографию (угадайте, что? Вам лучше поместить этот файл в ту же папку, что и ваш основной файл Markdown).

Вы также можете указать определенный csl, то есть язык стиля цитирования, не стесняйтесь читать здесь больше о том, как это работает. Просто погуглите нужный csl. Другой csl означает другой вид ссылок в документе. Вам просто нужно найти и ввести правильный csl, а не менять каждую точку.

Цитирующие записи

Для цитирования записей в библиографии необходимо использовать @syntax. Предположим, в вашем .bib-файле есть файл с именем myamazing2020paper. Чтобы процитировать его, просто введите @myamazing2020paper, и ссылка будет отображаться по мере необходимости. Это может быть сноска, отображающая (Ваше имя, 2020) или «Ваше имя (2020)» или «(Ваше имя, 2020)». Все зависит от csl.

В конце у вас будет список файлов в библиографии (не забудьте добавить какой-нибудь раздел «# References» в конце).

Вот несколько ссылок на другие материалы, связанные с нагрудниками:

— Дополнительная информация о стилях цитирования

- Подробнее о стилях нагрудников

Новые строки, разрывы страниц, перекрестные ссылки и другие разделы текста

Вы можете добавить горизонтальные линии в свой документ, используя шесть последовательных символов «-» или шесть последовательных ***** (подождите, их было пять перед скобками).

Если вы хотите вставить разрыв страницы, вы должны учитывать вывод, который вы используете. Если вы вяжете в pdf (используя текс), вы можете использовать латексную команду \newpage или \pagebreak.

Если вам нужно добавить ссылки на разделы или что-то подобное, вам нужно увеличить уценку. Самый простой вариант — установить пакет bookdown. Как только вы это сделаете, вы можете легко ссылаться на разделы своей работы, помещая название раздела в квадратные скобки. Подробнее см. здесь. Bookdown также полезен, чтобы иметь части и главы.

Создание таблиц

Таблицы уценки легко написать. Вы просто строите таблицу из | и -. Для определения ячейки разделяются символом «|». Чтобы определить структуру таблицы, вам нужно иметь набор — под вызовом основной таблицы.

Нравится:

| Column heading|
| ------------- | # use :---: for centered text, ---: for right text
| col value     |
| another value | 
| etc           |

Обратите внимание, что вам нужно как минимум 3 дефиса, разделяющих каждую ячейку заголовка. Внешние трубы (|) необязательны, но выглядят неплохо. Также таблица будет составлена, даже если трубы не все выровнены по вертикали. сырой Markdown выстраивается красиво. Вы также можете использовать встроенный Markdown.

Добавление изображений

Если вам нужно добавить изображения, синтаксис Markdown близок к синтаксису ссылок. На самом деле синтаксис

‘![текст изображения, если вы наведете на него мышь, он же ‘альтернативный текст’](путь к изображению)’

Обратите внимание, что изображение может быть адресом сайта или файлом на вашем компьютере. В последнем случае убедитесь, что вы правильно вводите имена путей. Практически: если вы получите сообщение об ошибке, попробуйте заменить косые черты: «\» на «/».

Однако обратите внимание, что если вы используете RStudio для вязания своего документа (а не, скажем, для отображения какого-либо текста в Интернете), RStudio требует, чтобы вы поместили изображения в ту же папку, что и ваш основной документ Markdown.

Перекрестные ссылки

Если вам нужно добавить ссылки на разделы или что-то подобное, вам нужно увеличить уценку. Самый простой вариант — установить пакет bookdown.

После этого вы можете легко ссылаться на разделы своей работы, помещая название раздела в квадратные скобки (подробнее здесь).

Добавление блоков кода

Еще одно преимущество Markdown, которое у вас есть, заключается в том, что вы можете вставлять блоки кода. Код может быть кодом Python, кодом R (в конце концов, мы используем RStudio) и многим другим. На самом деле RStudio поддерживает SQL, Java, C++. Что еще лучше, так это то, что вы можете решить, что делать с этим кодом. Вы можете отобразить его или даже запустить.

Таким образом, если вы хотите включить в отчет какую-нибудь причудливую графику, основанную на коде, вы можете это сделать. Далее, предположим, вы пишете статью с некоторыми данными. Вы изменяете данные, и все, что вам нужно сделать, это обновить свой код, чтобы получить обновленный график. Забудьте дни открытого Word, откройте Excel, обновите диаграмму, экспортируйте ее, удалите старую и добавьте новую.

Чтобы создать блок кода, вам нужно ввести три обратных кавычки (```) или «CTRL + ALT + I».

Сравнение этой установки с более традиционными

После этого тщательного исследования вы можете задаться вопросом, почему вам нужно переключиться на эту настройку, а не на стандартную, основанную на Word. Там много чего происходит, я ограничусь несколькими пулями.

  • Вы можете ускорить процесс повторной отправки. Измените csl, и все готово. Больше не нужно тратить годы на исправление деталей в Word (было здесь, сделано). Вы можете сделать это с помощью инструментов управления нагрудниками в Word, но мой опыт работы с ними на 10-страничном проекте превращается в кошмар. И будет еще хуже, если ваша работа будет разделена.
  • (Вышеизложенное поможет лучше спланировать траекторию вашего журнала. Вы оцените редакторов, которые знают свои предпочтения и могут указать вам правильный стиль нагрудника или csl. Если они не знают, что они вероятно, остров и не стоит вашего времени.)
  • Вы можете экспортировать во все выходные файлы. Вам понадобится HTML, если вы хотите использовать Amazon Kindlegen и получить плавный переход к формату mobi. Вы хотели бы перейти от pdf к документу, если вам не повезло, и ваша хорошая докторская степень на основе латекса. диссертация падает из-за странных академических издательских стандартов (был здесь, ненавидел это). Latex to Word сложно, здесь у вас есть слой Markdown, который имеет все необходимые вам функции и может выводить по-разному.
  • Учитывая успех GitHub и проблемы с рецензированием и академическими публикациями (укажите, что вам больше нравится), мы можем предвидеть день, когда GitHub войдет в гуманитарные науки. Угадайте, на каком языке текст на GitHub.
  • Все это бесплатно. Спросите у заведующей кафедрой (если она знает), сколько ваш университет тратит на лицензии. Переведите это на полуприличных научных сотрудников или представьте, как часть этого может повлиять на результаты вашего университета. Тогда, пожалуйста, примите меры и сообщите мне об этом.
  • Бонус: Markdown выглядит более удобным для использования, чем LaTeX, если вы раньше использовали форум. Это легко сделать с \ и {}.

Список ярлыков RStudio

Ярлыки могут сэкономить много времени. С RStudio вы, вероятно, будете выполнять некоторые операции довольно много, поэтому вот соответствующие ярлыки:

  • открыть новый файл: «ALT + F» (затем перейдите к новому файлу и выберите то, что вам нужно);
  • перемещаться по файлам уценки: «CTRL + ALT + стрелка влево/вправо»;
  • вяжем документ: ‘CTRL+ALT+K’;
  • вставьте фрагмент кода ‘CTRL + ALT + I’.

Обычные сочетания клавиш SHIFT, CTRL и ALT для перемещения по тексту по-прежнему действительны.

Что еще в RStudio

Мы используем RStudio в качестве универсальной печатной машины, но она предлагает еще больше. Как мы уже знаем, RStudio — это больше, чем классный текстовый редактор уценки. Помимо возможностей уценки и функций на основе R, RStudio также предлагает следующие функции, которые вы, возможно, захотите проверить:

  • блестящее приложение: хороший инструмент для разработки приложения, отображающего данные в Интернете. Цитата с их веб-сайта: «Shiny — это пакет R, который позволяет легко создавать интерактивные веб-приложения прямо из R. Вы можете размещать автономные приложения на веб-странице или встраивать их в документы R Markdown или создавать информационные панели. Вы также можете расширить свои приложения Shiny с помощью тем CSS, htmlwidgets и действий JavaScript».
  • изучайте R и развивайтесь в R: R — это отдельный язык программирования, который был (и, возможно, является) очень мощным и подходящим для статистики. (У R также есть целый документ, документирующий некоторые его проблемы как языка программирования, см. документ The R Inferno.)
  • использовать RStudio в качестве текстового редактора для другого языка: RStudio позволяет включать поля кода из других языков (Python, SQL, JS, C++). Это здорово, если вы хотите показать свой код и обсудить его. Вы также можете запускать свой код на другом языке, но вам нужно подумать, использовать ли разные инструменты для разных языков программирования.

Было ли это интересно? Не стесняйтесь подключаться к Linkedin или присоединяться к более широкому обсуждению через Twitter (ожидайте некоторых фантазийных сражений).

Эта работа проводится в рамках стипендии CAS в CAS-SEE Rijeka. Узнайте больше о Товариществе здесь.