My experience using Asciidoctor with a windows documentation toolchain

Please find here some information about the gcbasic documentation that was published in different formats starting from a set of asciidoctor files.
The adoc source files are here
On my windows 7 machine the directory structure is organized as follows

\source
\output
\prog
\utils

prog contains ruby, docbook-xls-ns, ant and saxon
utils contains hhc
java needs to be installed.
The windows command file gcbdoc.bat is here. Needs to be adapted to your specific case but it shoes the idea.

gcbdoc gcbasic all

generates all the format in output subdir at once. The result is here.
Hope it will help someone.
And thanks to Dan for his great program & support !
Jacques

Hi Jacques,
thanks for sharing! I did not yet take a look at your cmd-file, but I will do so within the next days.

As promised, here is my Windows cmd-job. The idea of my job was to evaluate different output formats and to see what comes out of the box and what the result look like without (layout-)customization. I also wanted to check the different calls of all the tools. In this job I do the following:
* Use Pandoc to convert from a Word document to Asciidoc (adoc) file (I doubt that this is interesting to most of you, but hey, Pandoc is cool, so take a look if you may need it for other purposes).
* Convert adoc file to html with Asciidoc (not Asciidoctor)
* Convert adoc file to chm-file (Microsoft Help, you have to download the Micosoft Help Compiler)
* Convert adoc to PDF with Asciidoc and FOP
* Convert adoc to PDF with Asciidoctor

Inside the job I also added a lot of comments, also about the Windows tools that need to be installed. Note that I am not a Batch Job expert and I really hate them, so I bet that everything could be done in a better way. Nevertheless I hope this is a help for someone, because this shall be small contribution for the help I got here.

Go!

SET manualDir=d:\myManualDir
SET asciidocDir=d:\asciidoc-8.6.9

@rem INPUTNAME is without extension. Assume that this name is used for all generated outputs, just the extension (and sometimes a suffix) changes.
SET INPUTNAME=MyVeryOwnDocument

@rem Batch hint: I use
@rem > %LOGFILE% 2>&1
@rem to start logging and to append I will use
@rem >> %LOGFILE% 2>&1
@rem to log all output. '2>&1' will log standard(1) and error(2) out!
SET LOGFILE=%INPUTNAME%.log

@echo Go! > %LOGFILE% 2>&1
@echo %time% >> %LOGFILE%

@rem ******************************************************************************************
@rem ****** Begin Pandoc to convert DocX to Asciidoc ******************************************
@rem ****** This is useless if you don't have to convert from Word. Just skip it, then.  ******
@rem ****** (assume that Pandoc.exe is in Path)      ******************************************
@rem ******************************************************************************************

@rem Actually only the conversion 1 is important, conversions 2,3 and 4 were made for testing purposes to see which result was the best.
@rem A nice sideeffect

@rem 1 This was the straight-forward way and the best! Simple conversion from Docx to Adoc:
@rem    The only drawback: In the Adoc file all images are referenced as media/image1.png etc, although inside the docx-file the references were like this: ./someFolder/someMeaningfulName.png
@rem    Because Pandoc does not create images in the media folder, this means you have to manually move/copy the images from /someFolder/ to /media/ and give them the names image1.png etc. However, this need to be done only once.
@rem    (a bit tricky, but handy in case of many images: save the docx as html first. In the generated html-folder you will find .png files like image001.png etc. which is almost what you need)
@rem Word Docx -> Pandoc Adoc
call pandoc -o %manualDir%\%INPUTNAME%.adoc --read=docx %manualDir%\%INPUTNAME%.docx >> %LOGFILE% 2>&1
@echo Word Docx ---> Pandoc Adoc >> %LOGFILE%

@rem 2  Here I converted with Pandoc from Docx to Html. Then again with Pandoc from Html to Adoc.
@rem    The Adoc result missed some tables and some emf-files of embedded Visio images if you compared it with conversion 1.
@rem Word Docx -> Pandoc html -> Pandoc Adoc
call pandoc -o %manualDir%\%INPUTNAME%_Pandoc_FromDocx.html %manualDir%\%INPUTNAME%.docx >> %LOGFILE% 2>&1
@echo Word DocX ---> Pandoc Html ready >> %LOGFILE%
call pandoc -o %manualDir%\%INPUTNAME%DocxToHtmlToAdoc.adoc %manualDir%\%INPUTNAME%_Pandoc_FromDocx.html >> %LOGFILE% 2>&1
@echo _Pandoc_FromDocx.html ---> Pandoc Adoc ready >> %LOGFILE%

@rem 3  Here I used "Save As html" in Word 2010, which produced a .htm file. This had to be opened in Notepad++ and be saved as UTF8 encoded, so that pandoc could convert it from html to ADoc
@rem Word Htm  -> Pandoc Adoc
call pandoc -o %manualDir%\%INPUTNAME%FromWordHtm.adoc --read=html %manualDir%\%INPUTNAME%.htm >> %LOGFILE% 2>&1
@echo Word Htm ---> Pandoc Adoc >> %LOGFILE%

@rem 4  Here I used "Save As html" in Word 2010, which produced a .htm file. This had to be opened in Notepad++ and be saved as UTF8 encoded, so that pandoc could read it. Then I converted it with Pandoc to html again and then to Adoc.
@rem    However the Adoc result was not correct if you looked a the tables: some had a width of 99% instead of 100%, sometimes only 10% (ten!) instead of 1000%
@rem Word Htm  -> Pandoc html -> Pandoc Adoc
call pandoc -o %manualDir%\%INPUTNAME%_Pandoc_FromHtm.html --read=html %manualDir%\%INPUTNAME%.htm >> %LOGFILE% 2>&1
@echo Word Htm ---> Pandoc Html >> %LOGFILE%
call pandoc -o %manualDir%\%INPUTNAME%WordHtmToPandocHtmlToAdoc.adoc %manualDir%\%INPUTNAME%_Pandoc_FromHtm.html >> %LOGFILE% 2>&1
@echo _Pandoc_FromHtm.html ---> Pandoc Adoc ready >> %LOGFILE%

@rem **************************
@rem ****** End Pandoc ********
@rem **************************



SET ADOCFILE=%manualDir%\%INPUTNAME%.adoc


@rem ***************************************************************************************************************
@rem ****** Start chm, i.e. use of Microsoft's Html Help Compiler **************************************************
@rem ****** You have to have "libxml2-2.7.8.win32" and "libxslt-1.1.26.win32" **************************************
@rem ****** see ftp://ftp.zlatkovic.com/libxml/ or ftp://xmlsoft.org/libxml2/win32/ ********************************
@rem ****** (assume that hhc.exe is in path)                      **************************************************
@rem ***************************************************************************************************************

@rem Put it all into a subdirectory
SET htmlhelpDir=%manualDir%\htmlhelp_gen
SET htmlhelpFile=%htmlhelpDir%\%INPUTNAME%.hhp

IF NOT EXIST %htmlhelpDir% MD %htmlhelpDir% >> %LOGFILE% 2>&1

call python %asciidocDir%\a2x.py --no-xmllint --verbose -f htmlhelp --destination-dir=%htmlhelpDir% %ADOCFILE% >> %LOGFILE% 2>&1
@echo Adoc ---> htmlHelp >> %LOGFILE%

call hhc %htmlhelpFile%
@echo Html Help Compiler finished. >> %LOGFILE%

@rem *****************************************************************
@rem ****** End chm, use of Microsoft's Html Help Compiler ***********
@rem *****************************************************************






@rem ******************************************************************************
@rem ****** Start Html Generation with out-of-the-box styles  *********************
@rem ******************************************************************************

@rem Start the 'normal' html5 generation, it's really slow! You can use 'start' instead of 'call' to let is run in parallel to this batch job, however this can cause file-access troubles
@echo Pandoc Adoc ---> Asciidoc Html start... >> %LOGFILE%
call python %asciidocDir%\asciidoc.py -b html5 -a toc2                     --out-file=%manualDir%\%INPUTNAME%_html5gen.html %ADOCFILE% >> %LOGFILE% 2>&1
call python %asciidocDir%\asciidoc.py -b html5 -a toc2 -a theme=volnitsky  --out-file=%manualDir%\%INPUTNAME%_html5gen_volnitsky.html %ADOCFILE% >> %LOGFILE% 2>&1
call python %asciidocDir%\asciidoc.py -b html5 -a toc2 -a theme=flask      --out-file=%manualDir%\%INPUTNAME%_html5gen_flask.html %ADOCFILE% >> %LOGFILE% 2>&1
@echo Pandoc Adoc ---> Asciidoc Html finished >> %LOGFILE%

@rem ******************************************************************************
@rem ****** End Html Generation with out-of-the-box styles  ***********************
@rem ******************************************************************************



@rem ******************************************************************************
@rem ****** Start PDF Generation, DBLATEX or FOP or Asciidoctor needed ************
@rem ******************************************************************************

@rem Use of DBLATEX (not tested, because I did not install DBLATEX, therefore out-commented)
rem call python %asciidocDir%\a2x.py --no-xmllint --verbose --keep-artifacts                     --format=pdf %ADOCFILE% >> %LOGFILE% 2>&1

@rem Use of FOP, I pass  -r  as option to FOP, because otherwise tables with only a header row (but no normal rows) caused errors.
@rem (do not forget to put the FOP directory, e.g. "d:\fop-2.1" into your Path)
@rem Proxy  hint: do not forget to set environment variable like "HTTP_PROXY=http://proxy.company.com" or similar, because xsltproc will most likely try to access http://docbook.sourceforge.net/...
call python %asciidocDir%\a2x.py --no-xmllint --verbose --keep-artifacts --fop --fop-opts=-r --format=pdf %ADOCFILE%  >> %LOGFILE% 2>&1
@rem I tried to change the output PDF name, by passing    --fop-opts="-pdf myFOPgeneratedPDF.pdf"   as an additional parameter, but this resulted in a FOP error saying that I can not set two output names.
@rem    a2x.py seems not to recognize that I want to override the default output name. Rename the generated output instead:
ren %manualDir%\%INPUTNAME%.pdf %INPUTNAME%FOP.pdf >> %LOGFILE% 2>&1

@rem Use of Asciidoctor (Ruby), this is really quick!
SET RUBY_DIR=C:\Ruby22
SET GEM_DIR=%RUBY_DIR%\lib\ruby\gems\2.2.0\gems
SET ASCIIDOCTOR_PDF_DIR=%GEM_DIR%\asciidoctor-pdf-1.5.0.alpha.11\bin
call ruby %ASCIIDOCTOR_PDF_DIR%\asciidoctor-pdf --out-file %INPUTNAME%Ruby.pdf %ADOCFILE% >> %LOGFILE% 2>&1


@rem ******************************************************************************
@rem ****** End PDF Generation   **************************************************
@rem ******************************************************************************

@echo %time% >> %LOGFILE%
@echo Finish! >> %LOGFILE% 2>&1