include::[] resolution

I'm trying to build wireshark 2.6.3 branch and they have a user-guide that is in asciidoc format.  Their recommendation is to use Chocolatey to get the asciidoctor environment like the following (Windows 10 x64 environment)

(PowerShell)
PS$>choco install -y asciidoctorj xsltproc docbook-bundle

In my environment (govt IT), I'm still stuck on the older branch 2.4.4 that uses Cygwin and trying to build 2.6.3 in Cygwin.  To do this, I had to install the ruby and rubygems packages, do a 'gem install asciidoctor', and then copied asciidoctor to the /bin directory.  I then made a 'asciidoctor.bat' file that is

@echo off
C:\cygwin64\bin\ruby.exe /bin/asciidoctor %*

I can run C:\cygwin64\bin\asciidoctor.bat in a Visual Studio cmd prompt with the --version flag and I get version 1.5.7.1 with some extra text.

After tweaking their FindAsciidoctor.cmake file, I was able to insert my workaround into their generate_user-guide.xml.vcxproj.

Their command to generate the file looks like this:

"C:\Program Files\CMake\bin\cmake.exe" -E env TZ=UTC ASCIIDOCTORJ_OPTS="-Xmx800m" C:/cygwin64/bin/asciidoctor.bat --attribute build_dir=C:/Users/DillJA/Desktop/wsbuild64/docbook --require C:/Users/DillJA/Desktop/wireshark-v0.7/docbook/asciidoctor-macros/commaize-block.rb --require C:/Users/DillJA/Desktop/wireshark-v0.7/docbook/asciidoctor-macros/cveidlink-inline-macro.rb --require C:/Users/DillJA/Desktop/wireshark-v0.7/docbook/asciidoctor-macros/wsbuglink-inline-macro.rb --require C:/Users/DillJA/Desktop/wireshark-v0.7/docbook/asciidoctor-macros/wssalink-inline-macro.rb --backend docbook --out-file user-guide.xml C:/Users/DillJA/Desktop/wireshark-v0.7/docbook/user-guide.asciidoc

user-guide.asciidoc has a bunch of include::[] statements, and each of them error like so:

  asciidoctor : error : user-guide.asciidoc: line 37: include file not found: /cygdrive/c/Users/DillJA/Desktop/wsbuild64/docbook/C:/Users/DillJA/Desktop/wireshark-v0.7/docbook/C:/Users/DillJA/Desktop/wireshark-v0.7/docbook/common_src/GPL_appendix.asciidoc [C:\Users\DillJA\Desktop\wsbuild64\docbook\generate_user-guide.xml.vcxproj]

If I replace user-guide.asciidoc with 'common_src/GPL_appendix.asciidoc', I can make it through the build script fine, since that file is a leaf document fragment and doesn't depend on the include::[] statements working.

Been trying to work it out on the Wireshark list, and seeing if there's some ideas to try to find out why my include::[] isn't working.

Any ideas?  Is it possible to print or list what asciidoctor thinks my load-path and/or base-dir is?

Thanks,
John D.

Seeing the error ti seems the unix path is being appended to the windows one...but I ignore why.
I don't have cygwin now, so I tried with GitBash and I was unable to reproduce it. Even when running the command from a totally different path from the one where the files are located.

Here is what I did:
1. I downloaded master branch
2. Installed AsciidoctorJ with choco
3. Build with this:

----
base_path="/c/Users/asalgadr/temp/wireshark/docbook"

asciidoctorj \
--require $base_path/asciidoctor-macros/ws_utils.rb \
--require $base_path/asciidoctor-macros/commaize-block.rb \
--require $base_path/asciidoctor-macros/cveidlink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wsbuglink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wssalink-inline-macro.rb \
--backend docbook --out-file "build/user-guide.xml" \
$base_path/user-guide.asciidoc
----

The changes I have done are:
- remove build_dir attribute -> just set target path within --out-file
- use bash variable to set absolute path in unix format

In my experience with cygwin, other things you may want to try are using "cygpath -aw" to automatically replace unix paths by windows.

One last thing you can try is building directly with Ruby instead of AsciidoctorJ.

--

I prepared an environment with your instructions and reproduced the issue and found a possible fix, but I thing the underlying problem is that the CMake script does not deal correctly with cygwin. Unless this is fixed, you'll have to monkey patch the generated build files. But it seems odd to me that the wireshark list did not propose this, so maybe I am missing something.

According to the wireshark docs, cygwin is no longer mandatory, so maybe you should try build it without it.

NOTE: I tried generating the make files but they require installing msvc first, and I have some reasons not to do so in my machine. So I cannot go further :%, but you should be able to add an if in `FindAsciidoctor.cmake`line 16 to use cygpath and fix CMAKE_CURRENT_SOURCE_DIR variable.

Here is what I did....

My environment (Win 10):
- Uninstalled my Ruby installation, AsciidoctorJ and all gems.
- Installed Cygwin (x64) in `c:\home\bin`
- Installed cygwin `rubygems` package
- Installed asciidoctor as usual with `gem install ...` from cygwin shell
- Copied `asciidoctor` to /bin and create a bat file with `C:\home\bin\cygwin64\bin\ruby.exe /bin/asciidoctor %*` . But I checked and at least for me, this is not really necessary.
- Reproduced issue running from another path (`~/temp`), using absolute windows paths. With that, I got all the `include file not found` messages.

I assume that if if the path does not start with /, Ruby fetches the current path and concats it to the one you are passing. My previous test was with AsciidoctorJ and I see it is able to better deal with it.

The fix is simple, pass the cygwin unix-like paths. Either pass it directly

----
base_path="/cygdrive/c/Users/asalgadr/temp/wireshark/docbook"

C:/Users/asalgadr/temp/ascii/asciidoctorc.bat \
--require $base_path/asciidoctor-macros/commaize-block.rb \
--require $base_path/asciidoctor-macros/cveidlink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wsbuglink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wssalink-inline-macro.rb \
--backend docbook --out-file user-guide.xml \
$base_path/user-guide.asciidoc
----

or use cygpath to translate it
----
win_path="C:/Users/asalgadr/temp/wireshark/docbook"
base_path=$(cygpath $win_path)

C:/Users/asalgadr/temp/ascii/asciidoctorc.bat \
--require $base_path/asciidoctor-macros/commaize-block.rb \
--require $base_path/asciidoctor-macros/cveidlink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wsbuglink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wssalink-inline-macro.rb \
--backend docbook --out-file user-guide.xml \
$base_path/user-guide.asciidoc
----

The fix worked for both `master` and `master-2.6` branch. Note that the master requires adding another gem with `--require $base_path/asciidoctor-macros/ws_utils.rb`.

abelsromero wrote

I prepared an environment with your instructions and reproduced the issue and found a possible fix, but I thing the underlying problem is that the CMake script does not deal correctly with cygwin. Unless this is fixed, you'll have to monkey patch the generated build files. But it seems odd to me that the wireshark list did not propose this, so maybe I am missing something.

According to the wireshark docs, cygwin is no longer mandatory, so maybe you should try build it without it.

NOTE: I tried generating the make files but they require installing msvc first, and I have some reasons not to do so in my machine. So I cannot go further :%, but you should be able to add an if in `FindAsciidoctor.cmake`line 16 to use cygpath and fix CMAKE_CURRENT_SOURCE_DIR variable.

Here is what I did....

My environment (Win 10):
- Uninstalled my Ruby installation, AsciidoctorJ and all gems.
- Installed Cygwin (x64) in `c:\home\bin`
- Installed cygwin `rubygems` package
- Installed asciidoctor as usual with `gem install ...` from cygwin shell
- Copied `asciidoctor` to /bin and create a bat file with `C:\home\bin\cygwin64\bin\ruby.exe /bin/asciidoctor %*` . But I checked and at least for me, this is not really necessary.
- Reproduced issue running from another path (`~/temp`), using absolute windows paths. With that, I got all the `include file not found` messages.

I assume that if if the path does not start with /, Ruby fetches the current path and concats it to the one you are passing. My previous test was with AsciidoctorJ and I see it is able to better deal with it.

The fix is simple, pass the cygwin unix-like paths. Either pass it directly

----
base_path="/cygdrive/c/Users/asalgadr/temp/wireshark/docbook"

C:/Users/asalgadr/temp/ascii/asciidoctorc.bat \
--require $base_path/asciidoctor-macros/commaize-block.rb \
--require $base_path/asciidoctor-macros/cveidlink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wsbuglink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wssalink-inline-macro.rb \
--backend docbook --out-file user-guide.xml \
$base_path/user-guide.asciidoc
----

or use cygpath to translate it
----
win_path="C:/Users/asalgadr/temp/wireshark/docbook"
base_path=$(cygpath $win_path)

C:/Users/asalgadr/temp/ascii/asciidoctorc.bat \
--require $base_path/asciidoctor-macros/commaize-block.rb \
--require $base_path/asciidoctor-macros/cveidlink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wsbuglink-inline-macro.rb \
--require $base_path/asciidoctor-macros/wssalink-inline-macro.rb \
--backend docbook --out-file user-guide.xml \
$base_path/user-guide.asciidoc
----

The fix worked for both `master` and `master-2.6` branch. Note that the master requires adding another gem with `--require $base_path/asciidoctor-macros/ws_utils.rb`.

Awesome!  I can confirm that setting the Windows paths to Cygwin paths manually in a cmd prompt gets rid of the include::[] errors that I'm seeing.  I should be able to patch FindAsciidoctor.cmake to something that works in my environment.  Maybe it'll trickle back upstream if the fix is robust enough.

The thing with govt IT is that they control the OS environment, so it's somewhat of a pain to justify introducing a new package system that they have to manage.  I prefer dealing with technical over political problems ;-)

Best regards,
John D.