On 29/04/2015 16:24, KI7MT wrote:
> Hi Bill,
Hi Greg,
>
> Thanks for the update / info.
>
> A couple things to note.
>
> * The current method of build is linked, meaning, the images, JS and CSS
> is shared and not embedded into a single HTML file (data-uri). I don't
> know if you plan on adding the data-uri method of build or not but it is
> handy to have, as it removes any relative path problems for Images and
> icons.
Err, it is a data-uri generation! Extract from doc/CMakeLists.txt:
ASCIIDOC_OPTIONS -a data-uri -a toc2 -a max-width=1024px
--conf-file=${CMAKE_CURRENT_BINARY_DIR}/wsjtx.conf --backend=xhtml11
>
> * On Windows, due to several GNU dependencies (liboostboost-regex) that
> cannot easily be met, you cannot use source-highlight in the
> documentation source files. You can use Python Pygments, but you'd need
> to add the Pygments module into your Python2 installation and Generate
> the Pygments filter, then set the default highlight in asciidoc.conf to
> Pygments. The default highlighter is source-highlight.
Err, I am not aware of source highlighting being used in the User Guide.
Are you referring to the development guide?
> * 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.
>
> 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.
>
>
> 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
