Изменение структуры репозитория методического пособия

[maxim-uvarov]

Сейчас методическое пособие состоит из одного документа в формате Markdown, разделенного на главы. Есть опасения, что если у пособия появится несколько авторов и они будут часто вносить изменения в различные главы, то контролировать такие изменения в одном документе будет тяжело.

Предполагается, что лучше сделать, чтобы каждая отдельная тема в документе находилась в отдельном .md файле. Желающий внести правки сможет отредактировать конкретный .md файлик и оформить commit в общий репозиторий и сделать pull request. Далее, эти правки будут проверены редколлегией и, в случае если все ок, они будут добавлены в основное пособие.

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

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

================
Авторы:

• Максим Уваров (30%)
• Максим Зеленский (70%)

Дата обновления:

• 04.07.2018
  ================

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

[sio]

Возможно, в контексте этой идеи интересным покажется Pandoc (а для метаданных - YAML header).

Во-первых, это позволит автоматизировать сбор книги из отдельных глав (и даже автоматически строить оглавление по собранной книге), а во-вторых, можно будет собирать не только markdown версию книги, но и PDF, HTML, FB2.. да уйму всего :)

Ссылки по теме:

• https://pandoc.org/
• https://pandoc.org/MANUAL.html#extension-yaml_metadata_block
• https://github.com/jgm/pandoc/wiki/Pandoc-Tricks

[maxim-uvarov]

Виталий, да! В сторону pandoc думаем! Вы пользовались? Умеете настраивать?

On Tue, 5 Jun 2018 at 12:29, Vitaly Potyarkin ***@***.***> wrote: Возможно, в контексте этой идеи интересным покажется Pandoc (а для метаданных - YAML header). Во-первых, это позволит автоматизировать сбор книги из отдельных глав (и даже автоматически строить оглавление по собранной книге), а во-вторых, можно будет собирать не только markdown версию книги, но и PDF, HTML, FB2.. да уйму всего :) Ссылки по теме: - https://pandoc.org/ - https://pandoc.org/MANUAL.html#extension-yaml_metadata_block - https://github.com/jgm/pandoc/wiki/Pandoc-Tricks — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#3 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEq38s6XUdzyB4hh_Z34kBliBktZPPtLks5t5hdTgaJpZM4UYg7h> .

-- -- Sent from microwave oven. Supposed to contain typos. o_O

[sio]

Немного пользовался, но на более простых задачах. Сам pandoc настройки не требует, нетривиальной может оказаться только установка LaTeX для генерации PDF. А дальше методом проб и ошибок подбирается набор параметров командной строки, при котором он будет давать желаемый результат. Когда эти параметры найдены, чтобы не держать их постоянно в голове, лучше сразу их оформить в Makefile :)

[hohlick]

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

Максим, а нужно ли? Читать "простыню" не легче, чем редактировать. Ты не думал о более ветвистой иерархии документа, где отдельные разделы выделены в отдельные документы?

[maxim-uvarov]

Типа вместо 1 документа сделать 4 документа:

• Power Query
• DAX
• Визуализации
• Прочее

Или как?