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

[KI7MT <ki...@gm...>]

Hi Bill,


On 04/28/2015 12:55 PM, Bill Somerville wrote:
> 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.

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.

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.

>>
>> 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.

>>
>> 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.

>>
>> 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.

Yes, I dropped that off, sorry, I use that option for JTSDK doc builds
also or at least, I used to have it on the build line.

>>
>> 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.

>>
>>
>> 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