Собираем документацию ProGit, под Windows

Предисловие

Добрый день.

Вот уж, около полгода, наша компания перешла с системы контроля версий SVN на Git. О преимуществах или недостатках я писать не буду, их обсудили не раз. Ребята, которые этим занимались в нашей команде, написали несколько внутренних статей с основными сценариями: создание бранчей, мерджи и т.п.
Но жизнь преподносит свои сюрпризы и выход за основные сценарии всегда обозначался фразой WTF или говоря по русски «я думал Git сделает так, почему он сделал по другому?»

И всё сводилось к тому, что нужно читать документацию по Гиту. (А на чтение документации, всегда нет времени.)
По этому поводу была статья Завершён перевод книги «Pro Git» на хабре.
Но как оказалось, в документацию ещё вносятся изменения. Не часто, но всё же, тут хорошо видно, когда вносились последние.

И возникла идея слепить последний вариант доки…

Git + Pandoc + Windows

Для этого нам необходимо установить Git Extensions, в меню Commands выбираем Clone Repository., указывая ссылку на репозиторий ‘https://github.com/progit/progit.git’

И жмём Clone.
P.S. Для скачивания доки, используется анонимный доступ, поэтому никаких ключей не потребуется.

Но далее меня ожидал сюрприз, документация оказалась в неизвестном формате markdown, а для того, чтобы создать вариант для EBook, предлагалось сделать так:

Making Ebooks
On Fedora you can run something like this:

$ yum install ruby calibre rubygems ruby-devel rubygem-ruby-debug $ gem install rdiscount $ makeebooks en  # will produce a mobi 

Перспектива настраивать Линуксовую виртуалку, только лишь для того, чтобы собрать документацию — не радовала. Возможно есть и другие решения, дальше лишь мой велосипед.
О великий интернет! Там на просторах, мне удалось найти утилиту Pandoc, которая может превратить файлы markdown формата, в docx, pdf, txt и т.д.
Возможности и синтаксис можно посмотреть тут.
Скачиваем, устанавливаем, заходим в папку E:\sources.git\!\progit\ru
Если посмотреть, то синтаксис при конвертации простой

pandoc -S  01-introduction\01-chapter1.markdown -o gitbook.docx 

Из нюансов:

1. Нужно было, подхватить при генерации несколько файлов.
2. Линки на картинки, были указаны в формате

    Insert 18333fig0101.png  Рисунок 1-1. Схема локальной СУВ. 

   , а надо

   ![ Рисунок 1-1. Схема локальной СУВ.](..\figures\18333fig0101-tn.png) 

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

1. Решается поиском всех файлов в папке с расширением markdown.
2. Решается с помощью RegExp.
Получится такой скрипт:

Const ForReading = 1 Const ForWriting = 2 Const ForAppending = 8  Set objFSO = CreateObject("Scripting.FileSystemObject") Set objRegEx = CreateObject("VBScript.RegExp")  Dim sCurPath, tempFolder, files sCurPath = objFSO.GetAbsolutePathName(".") tempFolder = sCurPath + "\!"  if objFSO.FolderExists(tempFolder) then     objFSO.DeleteFolder(tempFolder) end if objFSO.CreateFolder(tempFolder)  CopyFiles sCurPath, tempFolder  Dim cmd cmd = "pandoc -S " + files + " -o gitbook.docx" with createobject("wscript.shell")   .Run(cmd), 0, True end with  WScript.Echo("Completed")   Function CopyFiles(CurrentFolderName, TempFolderName)     On Error Resume Next           Dim ObjFolder     Dim ObjSubFolders     Dim ObjSubFolder     Dim ObjFiles     Dim ObjFile	       Set ObjFolder = objFSO.GetFolder(CurrentFolderName)     Set ObjFiles = ObjFolder.Files           For Each ObjFile In ObjFiles     IF objFSO.GetExtensionName(ObjFile.name) = "markdown" Then          Set openedFile = objFSO.OpenTextFile(ObjFile.Path, ForReading)         Set outputfile = objFSO.CreateTextFile(TempFolderName + "\" + ObjFile.name, True)          files = files + "!\" + ObjFile.name + " "         objRegEx.IgnoreCase = True         objRegEx.MultiLine = True         objRegEx.Global = True         objRegEx.Pattern = "Insert (.*).png\n*\s*(.*)$"          text = openedFile.ReadAll         openedFile.Close         result = objRegEx.Replace(text, "![$2](../figures/$1-tn.png)")         outputfile.Write result         outputfile.Close      End If     Next           'Getting all subfolders     Set ObjSubFolders = ObjFolder.SubFolders           For Each ObjFolder In ObjSubFolders         'Getting all Files from subfolder         CopyFiles ObjFolder.Path, TempFolderName     Next       End Function

Запускаем скрипт из папки E:\sources.git\!\progit\ru, получаем gitbook.docx.

Заключение

1. Место откуда запускать скрипт важно, поскольку учитывается путь к картинкам.
2. Чтобы собрать pdf нужен latex, поэтому не пробовал.
3. Если файл нужен в другом формате, можно уже использовать другие утилиты, чтобы конвертировать docx в pdf, fb2 и т.д…
4. Документацию я так читать и не начал, но уже на шаг ближе :).