[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 07:09, KI7MT wrote:
> Hello All,
Hi Greg & All,
>
> I don't know about Mac, but for Windows, we can do away with JTSDK-DOC,
> install a Full version of Python27 + Asciidoc, and that should do it. I
> need to test if base64 encoding is available with a full Python27
> install on Windows, but I think it is. Linux, is simple to implement.
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.
>
> 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.
>
> 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.
>
> With a full Python27 + AsciiDoc, Docs && Manpages can be compiled at
> build time, Linux and Windows. This should give you the versatility your
> needing. I think Mac should be OK with this approach also.
>
> If you want to go that route, I'll start working on the necessary changes.
>
> The Build commands are simple:
>
> Example Doc (for 1.5.1 or something):
> asciidoc -b xhtml11 -a data-uri -a toc2 -o wsjtx-1.5.0.html
> ./wsjtx-1.5.0.adoc
I had to add '-a max-width=1024px' to get similar output although the 
final rendering is a tiny bit different when built on Windows - this may 
well be due to the newer version of asciidoc.
>
> 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.
>
>
> While this sounds like allot, it's really not allot of work to implement.
>
> 73's
> Greg, KI7MT
>
73
Bill
G4WJS.