Собираем документацию 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!progitru
Если посмотреть, то синтаксис при конвертации простой

pandoc -S  01-introduction1-chapter1.markdown -o gitbook.docx

Из нюансов:

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

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

   , а надо

   ![ Рисунок 1-1. Схема локальной СУВ.](..figures18333fig0101-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 (.*).pngn*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!progitru, получаем gitbook.docx.

Заключение

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

Автор: den_labs

Источник