On 29/04/2015 16:44, KI7MT wrote: > Hi Bill, Hi Greg, <snip> >> Err, I am not aware of source highlighting being used in the User Guide. >> Are you referring to the development guide? > I think we took source-highlight out of all the docs for this reason. I > was merely providing this for information, as the Cyg32 method of build > allows the use of source-highlight on Windows, but that will change when > moving to the new method build. OK, thanks for that. I am aware of the complexities of using Pygments and other source highlighters on Windows :( > >>> * I working on an update to JTSDK-Win32 to add everything to build the >>> docs, but it's going to take a while. This will also remove the Cyg32 >>> install, which was useful for more than just docs. >> Just asciidoc and a working, but not necessarily default, Python 2.x >> where x>4 is all that is needed. > Yes, I need to add AsciiDoc and Python2 too the JTSDK Windows installer > and update paths in the WSJT-X build scripts.. I assume CMAKE_PREFIX_PATH is what you mean, yes that is all. > >>> I'm not sure how Joe wants to handle all the other documentation yet, so >>> will need some guidance there. >> I expect the answer will be "There's no need to change them for now." >> given that WSPR and a large part of WSJT may be subsumed by WSJT-X's >> added modes. > Maybe, but If I take out Cyg32, there wont be any other doc builds, so I > can't do that until the shift is complete for all apps. OK, I was not proposing any changes to existing documentation build processes, just eliding the WSJT-X user guide generation.
The WSJT-X build could use custom CMake commands to shell out to CygWin if absolutely necessary, for example if we wished to generate a PDF version of the manual using FOP or similar, but I would rather not go there right now. 73 Bill G4WJS. > >>> >>> 73's >>> Greg, KI7MT >> 73 >> Bill >> G4WJS. >>> On 04/29/2015 05:49 AM, Bill Somerville wrote: >>>> Hi All, >>>> >>>> I have added steps to the build to generate the WSJT-X user guide >>>> automatically. Currently this is working on a copy of the user guide >>>> sources. This has been added as a proof of concept and IMHO it is >>>> working correctly and provides several benefits over the current >>>> arrangement with a separate documentation branch and build tools: >>>> >>>> 1) Documentation sources are held in the same VCS branch as the >>>> application source code, therefore they are branched and tagged along >>>> with the application source code they refer to, >>>> 2) The build script injects asciidoc attributes for the current version >>>> identification automatically, saving effort of routine editing tasks on >>>> the documentation source for every release. Other attributes that the >>>> the build script can generate can be easily added, >>>> 3) The documentation generation works on all platforms, >>>> 4) Developers and testers see the latest documentation when they make or >>>> download a development build, >>>> 5) The project web server can hold old versions of the documentation >>>> which will be automatically referenced by the old version of WSJT-X, >>>> this is facilitated by the generated document name being unique to the >>>> version. >>>> >>>> With any new build component there may be a requirement for tools to be >>>> installed, this is no exception as the user guide generation requires >>>> the asciidoc tool and that itself requires a Python interpreter. For >>>> *nix systems including Mac this is not a big issue as these can be >>>> trivially installed on a build host system. On Windows there are a >>>> couple of complications, as always :( Firstly the latest release of >>>> asciidoc is broken and hangs on Windows, secondly as asciidoc does not >>>> work with Python 3 there needs to be a way of doing builds on a Windows >>>> build host that may well have both Python v2 and Python v3 installed. To >>>> help with this I have set the build script to run asciidoc with a >>>> specific Python interpreter located by an absolute path, this means that >>>> even on a system where Pythion v3 is the default version, i.e. on the >>>> PATH, the build will still work after a minor adjustment to your CMake >>>> toolchain file. >>>> >>>> To try out the documentation build you need to checkout the development >>>> branch ^/branches/wsjtx and make sure you have asciidoc and Python v2 >>>> installed. On Windows you will need to download the latest snapshot of >>>> asciidoc rather than the broken release version v8.6.9, this can be >>>> fetched from https://github.com/asciidoc/asciidoc/archive/master.zip . >>>> Unzip it somewhere and adjust your CMake tool chain file to add it to >>>> the CMAKE_PREFIX_PATH variable. >>>> >>>> Currently the documentation generation is switched off unless you set >>>> the CMake option WSJT_GENERATE_DOCS to ON in your build tree >>>> configuration, if adopted this option would be ON by default. >>>> >>>> The only disadvantage I can see is that the documentation for the >>>> various applications are no longer held in a single branch, but TBH I >>>> believe this is actually an advantage and the single branch was more of >>>> a solution to the problem of generation not being easy on some platforms >>>> rather than providing any real benefit. Obviously the other applications >>>> can maintain the current structure or move to a per application >>>> documentation VCS and build. >>>> >>>> The implementation in the development branch is only a proof of concept >>>> at this point, the actual documentation content is a copy of the WSJT-X >>>> user guide sources with a few minor edits to take advantage of the new >>>> features like automatic version number injection. If we decide to go >>>> ahead with this change; I would delete the trial documentation sources >>>> and move across the real sources in Subversion along with their full >>>> history. This would require a small amount of coordination during the >>>> switch over to ensure any in progress edits are not lost. >>>> >>>> I would also propose that this change is small enough in scope and >>>> implications to merge into the WSJT-X branch for use in the impending >>>> v1.5.0 release. >>>> >>>> 73 >>>> Bill >>>> G4WJS. ------------------------------------------------------------------------------ One dashboard for servers and applications across Physical-Virtual-Cloud Widest out-of-the-box monitoring support with 50+ applications Performance metrics, stats and reports that give you Actionable Insights Deep dive visibility with transaction tracing using APM Insight. http://ad.doubleclick.net/ddm/clk/290420510;117567292;y _______________________________________________ wsjt-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/wsjt-devel
