Re: [wsjt-devel] WSJT-X: User Guide built with CMake - was: Re: WSJT-X: User Guide updates for v1.5.0

[Bill S. <g4...@cl...>]

On 28/04/2015 21:54, KI7MT wrote:
> Hi Bill,
Hi Greg,
>
>
> On 04/28/2015 12:55 PM, Bill Somerville wrote:
>> On 28/04/2015 07:09, KI7MT wrote:
>>> Hello All,
<snip>
>> OK I have tweaked the CMake build script to build the user guide. I
>> found that asciidoc 8.6.9 (the latest release) is broken on Windows but
>> using the latest development source from github was OK. You can get it from:
>>
>>          https://github.com/asciidoc/asciidoc/archive/master.zip
>>
>> Unzip this somewhere (I used c:\Tools) and add the new asciidoc-master
>> directory to the CMAKE_PREFIX_PATH set up in your CMake toolchain file.
>> Assuming you have some form of Python 2.7 or later installed such that
>> .py files are automatically executable, this should be all you need to
>> do. On Linux and Mac just install asciidoc by the normal route and all
>> will be fine.
> For Windows, adding Python27 is a sensitive situation with regards to
> WSPR and WSJT builds. I will need to do some testing. Will take fare bit
> of time to sort that all out.
Looking at the asciidoc prequisites it says Python 2.4 and up is OK so 
it may not be an issue. I haven't put any Python checks in the WSJT-X 
CMake script, it just finds asciidoc and takes the view that if you have 
installed asciidoc then you really ought to have a working Python around.
>
> I don't know what the diff's are in packages, but the Distro versions
> are 8.6.9 and his Git repo is 8.6.9 .. so dunno.
That is the official git repo (a bit confusing as the home page still 
refers to the Google Code repositiory), fetching a snapshot of master is 
pre-release code. The actual issue that causes 8.6.9 not to work on 
Windows is:

https://github.com/asciidoc/asciidoc/pull/39

See the associated ML link for details.
>
>>> The Cmake scripts should be able to deal with this easily, it's just
>>> paths to Python2 and Asciidoc (maybe a toolchain.cmake file item? not
>>> sure). For WSPR and WSJT, we can add a small Makefile in the docs
>>> directory, building both the HTML docs and Manpages, and it's done.
>> I have added a new option to the WSJT-X CMakeLists.txt, set
>> WSJT_GENERATE_DOCS to ON (it is OFF by default) in your build area if
>> you want to build the user guide.
> Until I have a solution for keeping Py2 and Py3 separate on Windows,
> I'll hold off on Building Docs during compile.
>
> Linux can be added no problem.
There is no point progressing until the user guide sources can be moved 
across.

Assuming that it builds with all Pythons since 2.4, that shouldn't be an 
issue.
>
>>> I'm working on this approach for JTSDK Nix now. The biggest change is
>>> the location of Icons and Images. For Data-URI builds (single file HTML)
>>> the images must be in the same directory (./icons ./images
>>> ./main-file.adoc ) as the file being built. This will no doubt cause
>>> duplication of a few files (links.adoc xyz.icon etc).
>> I have copied the documentation sources across to the ^/branches/wsjtx
>> tree as a temporary measure for testing purposes, DO NOT EDIT THESE
>> FILES as hey will be deleted when the real ones are migrated with their
>> svn history in tact.
>>
>> I renamed globals to common and rearranged the directory structure a
>> little as it seemed to be broken, I'm not sure how it builds in the docs
>> branch as the relative paths of the images seem to be wrong.
> Yes, this is a PITA, as there is a bug or something in AsciiDoc. For the
> build scripts I use, Data-URI, I have to copy (rsync) the image folders
> into the source folder before building. This same problem *is not*
> present when building Linked Documents. I chased this one in circles for
> a long time, and finally, just copied the stuff over and let it be.
I don't think it is a bug. The .adoc files reference the images as 
image::images/<file> so the images are expected to be in a subdirectory 
of the file that references them. I simply moved the .adoc files up one 
level and did away with the 'source' directory and all is fine.

<snip>
>>> Example Manpage:
>>> a2x --doctype manpage --format manpage --no-xmllint wsjtx.1.txt
>> I not going to even attempt this on Windows as a2x isn't practical
>> without adding various things to the PATH which I have no desire to
>> force developers to do. If we want to do fancier document generation I
>> think doing a Docbook XML generation with asciidoc and the various post
>> processing steps like xmllint, xsltproc, dot and FOP can be added as
>> CMake custom commands rather than using the a2x driver.
> Yup. Windows and Manpages are a zoo. DockBook is massive overkill for
> the simple manpages we generate. FOP has some odd dependencies on
> Ubuntu, I don't recall what it is now, But I just use a2x.py on Ubuntu /
> Linux, no problems at all. DocBook itself wants to install like 1GB
> worth of files, that is crazy for a manpage.
I don't think Docbook is the problem, it is the back end stuff that a2x 
can potentially use - particularly dblatex.

The issue is that a2x is a wrapper script for everything and therefore 
installing it requires everything. Anyway a2x is a nuisance on widows 
because it expects all the intermediate and back end tools to be on the 
PATH and provides no way to provide explicit locations for programs :(

I don't think manpage generation for ascidoc generated Docbook XML is 
any more than a simple xslt transform.
>
>>>
>>> While this sounds like allot, it's really not allot of work to implement.
>>>
>>> 73's
>>> Greg, KI7MT
>>>
>> 73
>> Bill
>> G4WJS.
>>
> 73's
> Greg, KI7MT
73
Bill
G4WJS.