Switch to ascidoctor for User Guide generation

Requires Ruby and asciidoctor to be installed.

git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@6131 ab8295b8-cf94-4d9e-aec4-7959e3be5d79
This commit is contained in:
Bill Somerville 2015-11-19 00:08:30 +00:00
parent 3b823c9c0c
commit dc672c4bb1
6 changed files with 41 additions and 602 deletions

View File

@ -88,22 +88,13 @@ set (UG_IMGS
) )
find_package (PythonInterp 2.4 REQUIRED) find_program (ASCIIDOCTOR_EXECUTABLE NAMES asciidoctor)
if (PYTHON_VERSION_STRING VERSION_GREATER 2.9.9) if (NOT ASCIIDOCTOR_EXECUTABLE)
message (FATAL_ERROR "The asciidoc package requires a Python version less than 3 message (FATAL_ERROR "asciidoctor is required to build the documentation
Use CMAKE_PREFIX_PATH to point to an earlier version or install one, Building the documenation may optionally be turned off by setting the CMake
you can also skip building the documentation by switching the option
WSJT_GENERATE_DOCS to OFF.")
endif (PYTHON_VERSION_STRING VERSION_GREATER 2.9.9)
find_program (ASCIIDOC_EXECUTABLE NAMES asciidoc asciidoc.py)
if (NOT ASCIIDOC_EXECUTABLE)
message (FATAL_ERROR "Asciidoc is required to build the documentation
Building the documenation may optionally be tured off by setting the CMake
option WSJT_GENERATE_DOCS to OFF.") option WSJT_GENERATE_DOCS to OFF.")
endif (NOT ASCIIDOC_EXECUTABLE) endif (NOT ASCIIDOCTOR_EXECUTABLE)
include (CMakeParseArguments) include (CMakeParseArguments)
@ -111,36 +102,34 @@ include (CMakeParseArguments)
# #
# HTML - variable for output file ${CMAKE_CURRENT_BINARY_DIR}/`$basename ${SOURCE}`.html # HTML - variable for output file ${CMAKE_CURRENT_BINARY_DIR}/`$basename ${SOURCE}`.html
# SOURCE - top level asciidoc file # SOURCE - top level asciidoc file
# ASCIIDOC_OPTIONS - asciidoc command options # ASCIIDOCTOR_OPTIONS - asciidoctor command options
# DEPENDS - dependent files # DEPENDS - dependent files
function (html_document) function (html_document)
cmake_parse_arguments (args "" "SOURCE;HTML" "ASCIIDOC_OPTIONS;DEPENDS" ${ARGN}) cmake_parse_arguments (args "" "SOURCE;HTML" "ASCIIDOCTOR_OPTIONS;DEPENDS" ${ARGN})
get_filename_component (_output_name_we ${args_SOURCE} NAME_WE) get_filename_component (_output_name_we ${args_SOURCE} NAME_WE)
get_filename_component (_path ${args_SOURCE} PATH) get_filename_component (_path ${args_SOURCE} PATH)
set (_doc_file ${CMAKE_CURRENT_BINARY_DIR}/${_output_name_we}.html) set (_doc_file ${CMAKE_CURRENT_BINARY_DIR}/${_output_name_we}.html)
add_custom_command ( add_custom_command (
OUTPUT ${_doc_file} OUTPUT ${_doc_file}
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${path} WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${path}
COMMAND ${PYTHON_EXECUTABLE} ARGS ${ASCIIDOC_EXECUTABLE} ${args_ASCIIDOC_OPTIONS} --out-file=${CMAKE_CURRENT_BINARY_DIR}/${_output_name_we}.html ${args_SOURCE} COMMAND ${ASCIIDOCTOR_EXECUTABLE} ${args_ASCIIDOCTOR_OPTIONS}
-b html5
-a VERSION_MAJOR=${WSJTX_VERSION_MAJOR}
-a VERSION_MINOR=${WSJTX_VERSION_MINOR}
-a VERSION_PATCH=${WSJTX_VERSION_PATCH}
-a VERSION=${wsjtx_VERSION}
--out-file=${_doc_file} ${args_SOURCE}
DEPENDS ${args_DEPENDS} DEPENDS ${args_DEPENDS}
COMMENT "Generating ${_doc_file}" COMMENT "Generating ${_doc_file}"
) )
set (${args_HTML} ${_doc_file} PARENT_SCOPE) set (${args_HTML} ${_doc_file} PARENT_SCOPE)
endfunction (html_document) endfunction (html_document)
configure_file (wsjtx.conf.in wsjtx.conf.out)
# copy the file to the final location only if the generated output
# changes reduces needless rebuilds
execute_process (
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMAND ${CMAKE_COMMAND} -E copy_if_different wsjtx.conf.out wsjtx.conf
)
html_document( html_document(
HTML user_guide HTML user_guide
SOURCE user_guide/wsjtx-main.adoc SOURCE user_guide/wsjtx-main.adoc
ASCIIDOC_OPTIONS -a data-uri -a toc2 -a max-width=1024px --conf-file=${CMAKE_CURRENT_BINARY_DIR}/wsjtx.conf --backend=xhtml11 --theme wsjt ASCIIDOCTOR_OPTIONS -d book -a data-uri -a toc=left -a max-width=1100px
DEPENDS ${common_SRCS} ${UG_SRCS} ${UG_IMGS} wsjtx.conf.in theme/wsjt/wsjt.css DEPENDS ${common_SRCS} ${UG_SRCS} ${UG_IMGS}
) )
add_custom_target (docs ALL DEPENDS ${user_guide}) add_custom_target (docs ALL DEPENDS ${user_guide})

View File

@ -1,5 +1,5 @@
This folder contains the sources of WSJT-X documentation. To build This folder contains the sources of WSJT-X documentation. To build
these you will need the asciidoc and Python v2 tools installed. these you will need the asciidoctor tool installed.
If you do not wish to build the documentation, it is possible to skip If you do not wish to build the documentation, it is possible to skip
this directory in the WSJT-X build by setting the CMake option this directory in the WSJT-X build by setting the CMake option
@ -13,11 +13,11 @@ You will probably have these installed already if you are building the
WSJT-X manpages, if you are not you will just need to install WSJT-X manpages, if you are not you will just need to install
asciidoc: asciidoc:
sudo apt-get install asciidoc sudo apt-get install asciidoctor
or or
sudo yum install asciidoc sudo yum install asciidoctor
or whatever your distribution and package management requires. or whatever your distribution and package management requires.
@ -27,25 +27,14 @@ On Mac OS X
I recommend MacPorts: I recommend MacPorts:
sudo port install asciidoc sudo port install rb-rubygems
sudo gem install asciidoctor
On Windows On Windows
========== ==========
The asciidoc tool is a Python script so you will need to install a The asciidoctor tool is a Ruby script so you will need to install a
version of Python v2. If you already have Python v3 as the default version of Ruby. The gem tool is a good way to install asciidoctor:
Python interpreter on your system then download and install Python v2
(probably v2.7.x) but adjust the installer options so as not to make
it the default system Python interpreter, this is normally a
configuration option in the MSI installer.
The current version of asciidoc (8.6.9) is broken on Windows so you gem install asciidoctor
will need to get the latest development version:
download https://github.com/asciidoc/asciidoc/archive/master.zip
and unzip it somewhere like C:\Tools then you will need to add the
path to asciidoc and possibly Python v2 to your CMake tool chain file
for building WSJT-X. The directory containing asciidoc.py needs to be
included in the CMAKE_PREFIX_PATH variable.

View File

@ -1,546 +0,0 @@
/* Below is the content of the asciidoc.css file from the asciidoc
distribution, the WSJT theme additions are at the bottom of this
file */
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
/* Default font. */
body {
font-family: Georgia,serif;
}
/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
font-family: Arial,Helvetica,sans-serif;
}
body {
margin: 1em 5% 1em 5%;
}
a {
color: blue;
text-decoration: underline;
}
a:visited {
color: fuchsia;
}
em {
font-style: italic;
color: navy;
}
strong {
font-weight: bold;
color: #083194;
}
h1, h2, h3, h4, h5, h6 {
color: #527bbd;
margin-top: 1.2em;
margin-bottom: 0.5em;
line-height: 1.3;
}
h1, h2, h3 {
border-bottom: 2px solid silver;
}
h2 {
padding-top: 0.5em;
}
h3 {
float: left;
}
h3 + * {
clear: left;
}
h5 {
font-size: 1.0em;
}
div.sectionbody {
margin-left: 0;
}
hr {
border: 1px solid silver;
}
p {
margin-top: 0.5em;
margin-bottom: 0.5em;
}
ul, ol, li > p {
margin-top: 0;
}
ul > li { color: #aaa; }
ul > li > * { color: black; }
.monospaced, code, pre {
font-family: "Courier New", Courier, monospace;
font-size: inherit;
color: navy;
padding: 0;
margin: 0;
}
pre {
white-space: pre-wrap;
}
#author {
color: #527bbd;
font-weight: bold;
font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}
#footer {
font-size: small;
border-top: 2px solid silver;
padding-top: 0.5em;
margin-top: 4.0em;
}
#footer-text {
float: left;
padding-bottom: 0.5em;
}
#footer-badges {
float: right;
padding-bottom: 0.5em;
}
#preamble {
margin-top: 1.5em;
margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
div.admonitionblock {
margin-top: 2.0em;
margin-bottom: 2.0em;
margin-right: 10%;
color: #606060;
}
div.content { /* Block element content. */
padding: 0;
}
/* Block element titles. */
div.title, caption.title {
color: #527bbd;
font-weight: bold;
text-align: left;
margin-top: 1.0em;
margin-bottom: 0.5em;
}
div.title + * {
margin-top: 0;
}
td div.title:first-child {
margin-top: 0.0em;
}
div.content div.title:first-child {
margin-top: 0.0em;
}
div.content + div.title {
margin-top: 0.0em;
}
div.sidebarblock > div.content {
background: #ffffee;
border: 1px solid #dddddd;
border-left: 4px solid #f0f0f0;
padding: 0.5em;
}
div.listingblock > div.content {
border: 1px solid #dddddd;
border-left: 5px solid #f0f0f0;
background: #f8f8f8;
padding: 0.5em;
}
div.quoteblock, div.verseblock {
padding-left: 1.0em;
margin-left: 1.0em;
margin-right: 10%;
border-left: 5px solid #f0f0f0;
color: #888;
}
div.quoteblock > div.attribution {
padding-top: 0.5em;
text-align: right;
}
div.verseblock > pre.content {
font-family: inherit;
font-size: inherit;
}
div.verseblock > div.attribution {
padding-top: 0.75em;
text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
text-align: left;
}
div.admonitionblock .icon {
vertical-align: top;
font-size: 1.1em;
font-weight: bold;
text-decoration: underline;
color: #527bbd;
padding-right: 0.5em;
}
div.admonitionblock td.content {
padding-left: 0.5em;
border-left: 3px solid #dddddd;
}
div.exampleblock > div.content {
border-left: 3px solid #dddddd;
padding-left: 0.5em;
}
div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }
dl {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
dt {
margin-top: 0.5em;
margin-bottom: 0;
font-style: normal;
color: navy;
}
dd > *:first-child {
margin-top: 0.1em;
}
ul, ol {
list-style-position: outside;
}
ol.arabic {
list-style-type: decimal;
}
ol.loweralpha {
list-style-type: lower-alpha;
}
ol.upperalpha {
list-style-type: upper-alpha;
}
ol.lowerroman {
list-style-type: lower-roman;
}
ol.upperroman {
list-style-type: upper-roman;
}
div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
margin-top: 0.1em;
margin-bottom: 0.1em;
}
tfoot {
font-weight: bold;
}
td > div.verse {
white-space: pre;
}
div.hdlist {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
div.hdlist tr {
padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
font-weight: bold;
}
td.hdlist1 {
vertical-align: top;
font-style: normal;
padding-right: 0.8em;
color: navy;
}
td.hdlist2 {
vertical-align: top;
}
div.hdlist.compact tr {
margin: 0;
padding-bottom: 0;
}
.comment {
background: yellow;
}
.footnote, .footnoteref {
font-size: 0.8em;
}
span.footnote, span.footnoteref {
vertical-align: super;
}
#footnotes {
margin: 20px 0 20px 0;
padding: 7px 0 0 0;
}
#footnotes div.footnote {
margin: 0 0 5px 0;
}
#footnotes hr {
border: none;
border-top: 1px solid silver;
height: 1px;
text-align: left;
margin-left: 0;
width: 20%;
min-width: 100px;
}
div.colist td {
padding-right: 0.5em;
padding-bottom: 0.3em;
vertical-align: top;
}
div.colist td img {
margin-top: 0.3em;
}
@media print {
#footer-badges { display: none; }
}
#toc {
margin-bottom: 2.5em;
}
#toctitle {
color: #527bbd;
font-size: 1.1em;
font-weight: bold;
margin-top: 1.0em;
margin-bottom: 0.1em;
}
div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
margin-top: 0;
margin-bottom: 0;
}
div.toclevel2 {
margin-left: 2em;
font-size: 0.9em;
}
div.toclevel3 {
margin-left: 4em;
font-size: 0.9em;
}
div.toclevel4 {
margin-left: 6em;
font-size: 0.9em;
}
span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }
span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }
span.big { font-size: 2em; }
span.small { font-size: 0.6em; }
span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }
div.unbreakable { page-break-inside: avoid; }
/*
* xhtml11 specific
*
* */
div.tableblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
div.tableblock > table {
border: 3px solid #527bbd;
}
thead, p.table.header {
font-weight: bold;
color: #527bbd;
}
p.table {
margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
border-style: none;
}
div.tableblock > table[frame="hsides"] {
border-left-style: none;
border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
border-top-style: none;
border-bottom-style: none;
}
/*
* html5 specific
*
* */
table.tableblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
thead, p.tableblock.header {
font-weight: bold;
color: #527bbd;
}
p.tableblock {
margin-top: 0;
}
table.tableblock {
border-width: 3px;
border-spacing: 0px;
border-style: solid;
border-color: #527bbd;
border-collapse: collapse;
}
th.tableblock, td.tableblock {
border-width: 1px;
padding: 4px;
border-style: solid;
border-color: #527bbd;
}
table.tableblock.frame-topbot {
border-left-style: hidden;
border-right-style: hidden;
}
table.tableblock.frame-sides {
border-top-style: hidden;
border-bottom-style: hidden;
}
table.tableblock.frame-none {
border-style: hidden;
}
th.tableblock.halign-left, td.tableblock.halign-left {
text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
text-align: right;
}
th.tableblock.valign-top, td.tableblock.valign-top {
vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
vertical-align: bottom;
}
/*
* manpage specific
*
* */
body.manpage h1 {
padding-top: 0.5em;
padding-bottom: 0.5em;
border-top: 2px solid silver;
border-bottom: 2px solid silver;
}
body.manpage h2 {
border-style: none;
}
body.manpage div.sectionbody {
margin-left: 3em;
}
@media print {
body.manpage div#toc { display: none; }
}
/* WSJT styling overriding the above which is the content of the
standard asciidoc.css style sheet */
body {
font-family: Arial, Hevetica, sans-serif;
}
h1, h2, h3, h4, h5, h6 {
font-family: Georgia, "Times New Roman", Times, serif;
}
a:visited {
color: purple;
}

View File

@ -0,0 +1,13 @@
<style>
body {
font-family: Arial, Hevetica, sans-serif;
}
h1, h2, h3, h4, h5, h6 {
font-family: Georgia, "Times New Roman", Times, serif;
}
a:visited {
color: purple;
}
</style>

View File

@ -1,11 +1,13 @@
// This is a comment line, anything with // is ignored at process time. // This is a comment line, anything with // is ignored at process time.
= WSJT-X User Guide = WSJT-X User Guide
:Revision: {VERSION} Joseph H Taylor, Jr, K1JT
:revnumber: {VERSION}
// For web-pages, adding :badges: is ok, but is a security issue for // For web-pages, adding :badges: is ok, but is a security issue for
// package building .deb, .rpm, etc as it exposes the IP address and the images // package building .deb, .rpm, etc as it exposes the IP address and the images
// are non-free, so can't be included as part of the Debian package. // are non-free, so can't be included as part of the Debian package.
// :badges: // :badges:
:icons: :docinfo1:
:icons: font
:numbered: :numbered:
:keywords: amateur radio weak signal communication K1JT WSJT JT65 JT9 :keywords: amateur radio weak signal communication K1JT WSJT JT65 JT9
:description: Software for Amateur Radio Weak-Signal Communication :description: Software for Amateur Radio Weak-Signal Communication

View File

@ -1,8 +0,0 @@
# This is an asciidoc configuraiton file which is processed by CMake
# as a configuration file to substitute variables
[attributes]
themedir=@CMAKE_CURRENT_SOURCE_DIR@/theme/wsjt
VERSION_MAJOR=@WSJTX_VERSION_MAJOR@
VERSION_MINOR=@WSJTX_VERSION_MINOR@
VERSION_PATCH=@WSJTX_VERSION_PATCH@
VERSION=@wsjtx_VERSION@