Hi Bill,
On 04/29/2015 09:32 AM, Bill Somerville wrote:
> 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
>
Ok, I just checked briefly, did not go into detail, will look into this
further.
>>
>> * 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 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.
>> * 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'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.
>>
>>
>> 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
