From 6c6a758b8b34e1cc411d247523821fee627d51d6 Mon Sep 17 00:00:00 2001 From: Bill Somerville Date: Sat, 21 Nov 2015 02:34:20 +0000 Subject: [PATCH] Add PDF generation to docs target Cleaned up some syntax anomolies because of the switch to asciidoctor. Minor text tweaks to improve PDF pagination. Reduced HTML master font size to 80% for better web rendering. Removed references to KVASD from User Guide. git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@6142 ab8295b8-cf94-4d9e-aec4-7959e3be5d79 --- doc/CMakeLists.txt | 100 ++++-- doc/user_guide/acknowledgements.adoc | 2 +- doc/user_guide/config-details.adoc | 8 +- doc/user_guide/controls-functions-center.adoc | 2 +- doc/user_guide/controls-functions-left.adoc | 2 +- .../controls-functions-main-window.adoc | 4 +- doc/user_guide/controls-functions-menus.adoc | 18 +- .../controls-functions-messages.adoc | 4 +- .../controls-functions-status-bar.adoc | 2 +- .../controls-functions-wide-graph.adoc | 2 +- doc/user_guide/cooperating-programs.adoc | 4 +- doc/user_guide/docinfo.html | 4 + doc/user_guide/docinfo.xml | 0 doc/user_guide/faq.adoc | 138 ++++---- doc/user_guide/font-sizes.adoc | 4 +- doc/user_guide/implementation.adoc | 174 +++++----- doc/user_guide/install-linux.adoc | 104 +++--- doc/user_guide/install-mac.adoc | 3 - doc/user_guide/install-windows.adoc | 2 +- doc/user_guide/introduction.adoc | 10 +- doc/user_guide/logging.adoc | 6 +- doc/user_guide/make-qso.adoc | 328 +++++++++--------- doc/user_guide/new_features.adoc | 2 +- doc/user_guide/protocols.adoc | 8 +- doc/user_guide/settings-audio.adoc | 5 +- doc/user_guide/settings-colors.adoc | 4 +- doc/user_guide/settings-frequencies.adoc | 6 +- doc/user_guide/settings-general.adoc | 2 +- doc/user_guide/settings-radio.adoc | 4 +- doc/user_guide/settings-reporting.adoc | 2 +- doc/user_guide/settings-txmacros.adoc | 2 +- doc/user_guide/support.adoc | 60 ++-- doc/user_guide/transceiver-setup.adoc | 2 +- doc/user_guide/tutorial-example1.adoc | 12 +- doc/user_guide/tutorial-example2.adoc | 18 +- doc/user_guide/utilities.adoc | 188 +++++----- doc/user_guide/vhf-features.adoc | 268 +++++++------- doc/user_guide/wsjtx-main.adoc | 1 + doc/user_guide/wspr.adoc | 144 ++++---- 39 files changed, 841 insertions(+), 808 deletions(-) create mode 100644 doc/user_guide/docinfo.xml diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index fb61d134d..b8e3df790 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -5,6 +5,8 @@ set (common_SRCS ) set (UG_SRCS + user_guide/docinfo.html + user_guide/docinfo.xml user_guide/acknowledgements.adoc user_guide/compiling.adoc user_guide/config-details.adoc @@ -96,45 +98,89 @@ Building the documenation may optionally be turned off by setting the CMake option WSJT_GENERATE_DOCS to OFF.") endif (NOT ASCIIDOCTOR_EXECUTABLE) +find_program (FOPUB_EXECUTABLE NAMES fopub) + include (CMakeParseArguments) -# generate an HTML document from asciidoc text files(s) +# generate a document from asciidoc text files(s) # -# HTML - variable for output file ${CMAKE_CURRENT_BINARY_DIR}/`$basename ${SOURCE}`.html +# HTML - generate an HTML document +# PDF - generate a PDF document # SOURCE - top level asciidoc file # ASCIIDOCTOR_OPTIONS - asciidoctor command options # DEPENDS - dependent files -function (html_document) - cmake_parse_arguments (args "" "SOURCE;HTML" "ASCIIDOCTOR_OPTIONS;DEPENDS" ${ARGN}) - get_filename_component (_output_name_we ${args_SOURCE} NAME_WE) - get_filename_component (_path ${args_SOURCE} PATH) - set (_doc_file ${CMAKE_CURRENT_BINARY_DIR}/${_output_name_we}.html) - add_custom_command ( - OUTPUT ${_doc_file} - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${path} - 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} - COMMENT "Generating ${_doc_file}" - ) - set (${args_HTML} ${_doc_file} PARENT_SCOPE) -endfunction (html_document) +function (document) + cmake_parse_arguments (_args "HTML" "SOURCE;OUTPUT" "ASCIIDOCTOR_OPTIONS;PDF;DEPENDS" ${ARGN}) + get_filename_component (_source_path ${_args_SOURCE} PATH) + get_filename_component (_source_name ${_args_SOURCE} NAME) + get_filename_component (_output_name_we ${_args_SOURCE} NAME_WE) -html_document( - HTML user_guide + # HTML + if (${_args_HTML}) + set (_html_file ${CMAKE_CURRENT_BINARY_DIR}/${_output_name_we}.html) + add_custom_command ( + OUTPUT ${_html_file} + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${_source_path} + 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=${_html_file} ${_source_name} + DEPENDS ${_args_DEPENDS} + COMMENT "Generating ${_html_file}" + ) + list (APPEND _output_files ${_html_file}) + endif (${_args_HTML}) + + # PDF + if (_args_PDF AND EXISTS ${FOPUB_EXECUTABLE}) + set (_docbook_file ${CMAKE_CURRENT_BINARY_DIR}/${_output_name_we}.xml) + set (_pdf_file_we ${CMAKE_CURRENT_BINARY_DIR}/${_output_name_we}) + add_custom_command ( + OUTPUT ${_docbook_file} "${_pdf_file_we} (USLetter).pdf" "${_pdf_file_we} (A4).pdf" + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${_source_path} + COMMAND ${ASCIIDOCTOR_EXECUTABLE} ARGS ${_args_ASCIIDOCTOR_OPTIONS} + -b docbook + -a data-uri! + -a VERSION_MAJOR=${WSJTX_VERSION_MAJOR} + -a VERSION_MINOR=${WSJTX_VERSION_MINOR} + -a VERSION_PATCH=${WSJTX_VERSION_PATCH} + -a VERSION=${wsjtx_VERSION} + -D ${CMAKE_CURRENT_BINARY_DIR} + -o ${_docbook_file} ${_source_name} + COMMAND ${FOPUB_EXECUTABLE} ARGS ${_docbook_file} ${_args_PDF} -param paper.type USLetter + COMMAND ${CMAKE_COMMAND} ARGS -E rename ${_pdf_file_we}.pdf '${_pdf_file_we} \(USLetter\).pdf' + COMMAND ${FOPUB_EXECUTABLE} ARGS ${_docbook_file} ${_args_PDF} -param paper.type A4 + COMMAND ${CMAKE_COMMAND} ARGS -E rename ${_pdf_file_we}.pdf '${_pdf_file_we} \(A4\).pdf' + DEPENDS ${_args_DEPENDS} + COMMENT "Generating ${_pdf_file_we}.pdf" + ) + list (APPEND _output_files "${_pdf_file_we} (USLetter).pdf" "${_pdf_file_we} (A4).pdf") + endif (_args_PDF AND EXISTS ${FOPUB_EXECUTABLE}) + + set (${_args_OUTPUT} ${_output_files} PARENT_SCOPE) +endfunction (document) + +document( + HTML SOURCE user_guide/wsjtx-main.adoc - ASCIIDOCTOR_OPTIONS -d book -a data-uri -a toc=left -a max-width=1100px + OUTPUT html + ASCIIDOCTOR_OPTIONS -d book -a data-uri -a toc=left -a max-width=1024px DEPENDS ${common_SRCS} ${UG_SRCS} ${UG_IMGS} ) -add_custom_target (docs ALL DEPENDS ${user_guide}) +document( + PDF -param body.font.master 11 -param body.font.family "'Noto Sans, Helvetica, sans-serif'" -param title.font.family "'Noto Serif, Times New Roman, serif'" -param page.margin.inner 1cm -param page.margin.outer 1cm -param page.margin.top 0.75cm -param page.margin.bottom 0.5cm -param generate.toc 0 + SOURCE user_guide/wsjtx-main.adoc + OUTPUT pdf + ASCIIDOCTOR_OPTIONS -d book + DEPENDS ${common_SRCS} ${UG_SRCS} ${UG_IMGS} + ) +add_custom_target (docs ALL DEPENDS ${html} ${pdf}) install (FILES - ${user_guide} + ${html} DESTINATION ${WSJT_SHARE_DESTINATION}/${WSJT_DOC_DESTINATION} RENAME ${PROJECT_MANUAL} #COMPONENT runtime diff --git a/doc/user_guide/acknowledgements.adoc b/doc/user_guide/acknowledgements.adoc index a35b10680..827dcf736 100644 --- a/doc/user_guide/acknowledgements.adoc +++ b/doc/user_guide/acknowledgements.adoc @@ -1,7 +1,7 @@ // Status=review Since 2005 the _WSJT_ project (including programs _WSJT_, _MAP65_, -_WSPR_, _WSJT-X_, and _WSPR-X_) has been ``open source'', with all +_WSPR_, _WSJT-X_, and _WSPR-X_) has been "`open source`", with all code licensed under the GNU Public License (GPL). Many users of these programs, too numerous to mention here individually, have contributed suggestions and advice that have greatly aided the development of diff --git a/doc/user_guide/config-details.adoc b/doc/user_guide/config-details.adoc index 8b4234c41..635e27d8f 100644 --- a/doc/user_guide/config-details.adoc +++ b/doc/user_guide/config-details.adoc @@ -1,4 +1,4 @@ -// Status=review -[[CONFIG_DETAILS]] - -Are we here? +// Status=review +[[CONFIG_DETAILS]] + +Are we here? diff --git a/doc/user_guide/controls-functions-center.adoc b/doc/user_guide/controls-functions-center.adoc index 59f463f14..92b72a1c0 100644 --- a/doc/user_guide/controls-functions-center.adoc +++ b/doc/user_guide/controls-functions-center.adoc @@ -4,7 +4,7 @@ At the center of the main window are a number of controls used when making QSOs: //.Misc Controls Center -image::images/misc-controls-center.png[align="center",alt="Misc Controls Center"] +image::misc-controls-center.png[align="center",alt="Misc Controls Center"] * Check *Tx even* to transmit in even-numbered UTC minutes. Uncheck this box to transmit in the odd minutes. This selection is made diff --git a/doc/user_guide/controls-functions-left.adoc b/doc/user_guide/controls-functions-left.adoc index 479c12ac4..b92e4a26d 100644 --- a/doc/user_guide/controls-functions-left.adoc +++ b/doc/user_guide/controls-functions-left.adoc @@ -5,7 +5,7 @@ station being called, and date and time are found at lower left of the main window: //.Misc Controls Left -image::images/misc-main-ui.png[align="center",alt="Mist Menu Items"] +image::misc-main-ui.png[align="center",alt="Misc Menu Items"] * A drop-down list of frequencies and bands at upper left lets you select the operating band and sets dial frequency to a value taken diff --git a/doc/user_guide/controls-functions-main-window.adoc b/doc/user_guide/controls-functions-main-window.adoc index 7da31746c..e45ca1b7c 100644 --- a/doc/user_guide/controls-functions-main-window.adoc +++ b/doc/user_guide/controls-functions-main-window.adoc @@ -3,7 +3,7 @@ The following buttons appear just under the decoded text windows on the main screen: //.Main UI Controls -image::images/main-ui-controls.png[align="left",width=650,alt="Main UI Controls"] +image::main-ui-controls.png[align="left",width=650,alt="Main UI Controls"] * *Log QSO* raises a dialog window pre-filled with known information about a QSO you have nearly completed. You can edit or add to this @@ -13,7 +13,7 @@ confirmation screen automatically when you send a message containing 73. //.Log QSO Window -image::images/log-qso.png[align="center",alt="Log QSO"] +image::log-qso.png[align="center",alt="Log QSO"] * *Stop* will terminate normal data acquisition in case you want to freeze the waterfall or open and explore a previously recorded audio diff --git a/doc/user_guide/controls-functions-menus.adoc b/doc/user_guide/controls-functions-menus.adoc index 6e1e7e68a..7aba18202 100644 --- a/doc/user_guide/controls-functions-menus.adoc +++ b/doc/user_guide/controls-functions-menus.adoc @@ -6,7 +6,7 @@ provided below. Keyboard shortcuts for some frequently used menu items are listed at the right. ==== WSJT-X menu -image::images/MacAppMenu.png[align="left",alt="Mac App Menu"] +image::MacAppMenu.png[align="left",alt="Mac App Menu"] This menu appears on the Macintosh only. *Settings* appears here, labeled as *Preferences*, rather than on the *File* menu. *About @@ -14,24 +14,24 @@ WSJT-X* appears here rather than on the *Help* menu. [[FILE_MENU]] ==== File menu -image::images/file-menu.png[align="left",alt="File Menu"] +image::file-menu.png[align="left",alt="File Menu"] [[VIEW_MENU]] ==== View Menu -image::images/view-menu.png[align="left",alt="View Menu"] +image::view-menu.png[align="left",alt="View Menu"] [[MODE_MENU]] ==== Mode Menu -image::images/mode-menu.png[align="left",alt="Mode Menu"] +image::mode-menu.png[align="left",alt="Mode Menu"] [[DECODE_MENU]] ==== Decode Menu -image::images/decode-menu.png[align="left",alt="Decode Menu"] +image::decode-menu.png[align="left",alt="Decode Menu"] [[SAVE_MENU]] [[SAVE-WAV]] ==== Save Menu -image::images/save-menu.png[align="left",alt="Save Menu"] +image::save-menu.png[align="left",alt="Save Menu"] Choose *Save all* to save received data as audio +.wav+ files. *Save decoded* will save only those files containing at least one @@ -39,10 +39,10 @@ decoded message. [[HELP_MENU]] ==== Help Menu -image::images/help-menu.png[align="left",alt="Help Menu"] +image::help-menu.png[align="left",alt="Help Menu"] ===== Keyboard Shortcuts (F3) -image::images/keyboard-shortcuts.png[align="left",alt="Help Menu"] +image::keyboard-shortcuts.png[align="left",alt="Keyboard Shortcuts"] ===== Special Mouse Commands (F5) -image::images/special-mouse-commands.png[align="left",alt="Help Menu"] +image::special-mouse-commands.png[align="left",alt="Special Mouse Commands"] diff --git a/doc/user_guide/controls-functions-messages.adoc b/doc/user_guide/controls-functions-messages.adoc index bde4a4402..ec26cda8c 100644 --- a/doc/user_guide/controls-functions-messages.adoc +++ b/doc/user_guide/controls-functions-messages.adoc @@ -8,7 +8,7 @@ you click *Generate Std Msgs* or double-click on an appropriate line in one of the decoded text windows. //.Traditional Message Menu -image::images/traditional-msg-box.png[align="center",alt="Traditional Message Menu"] +image::traditional-msg-box.png[align="center",alt="Traditional Message Menu"] * Select the next message to be transmitted (at the start of your next Tx sequence) by clicking on the circle under *Next*. @@ -33,7 +33,7 @@ The second arrangement of controls for generating and selecting Tx messages appears on *Tab 2* of the Message Control Panel: //.New Message Menu -image::images/new-msg-box.png[align="center",alt="New Message Menu"] +image::new-msg-box.png[align="center",alt="New Message Menu"] With this setup you normally follow a top-to-bottom sequence of transmissions from the left column if you are calling CQ, or the right diff --git a/doc/user_guide/controls-functions-status-bar.adoc b/doc/user_guide/controls-functions-status-bar.adoc index 71f00bead..1e244e1aa 100644 --- a/doc/user_guide/controls-functions-status-bar.adoc +++ b/doc/user_guide/controls-functions-status-bar.adoc @@ -4,7 +4,7 @@ A *Status Bar* at the bottom edge of the main window provides information about operating conditions. //.Status Bar -image::images/status-bar-a.png[align="left",alt="New Message Menu"] +image::status-bar-a.png[align="left",alt="Status Bar"] Labels on the *Status Bar* display such information as the program's current operating state, operating mode, the content of your most diff --git a/doc/user_guide/controls-functions-wide-graph.adoc b/doc/user_guide/controls-functions-wide-graph.adoc index e6d02d039..0c148d465 100644 --- a/doc/user_guide/controls-functions-wide-graph.adoc +++ b/doc/user_guide/controls-functions-wide-graph.adoc @@ -4,7 +4,7 @@ The following controls appear at the bottom of the Wide Graph window. With the exception of *JT65 nnnn JT9*, they affect only the graphical displays — they have no effect on the decoding process. -image::images/wide-graph-controls.png[align="center",alt="Wide Graph Controls"] +image::wide-graph-controls.png[align="center",alt="Wide Graph Controls"] - *Bins/Pixel* controls the displayed frequency resolution. Set this value to 1 for the highest possible resolution, or to higher numbers diff --git a/doc/user_guide/cooperating-programs.adoc b/doc/user_guide/cooperating-programs.adoc index 57a8b7abb..8be896375 100644 --- a/doc/user_guide/cooperating-programs.adoc +++ b/doc/user_guide/cooperating-programs.adoc @@ -12,7 +12,7 @@ showing world-wide JT65 activity on all amateur bands over over the past hour. Such a map might look like this, where different colors represent different bands: -image::images/psk-reporter.png[align="left",alt="PSK Reporter"] +image::psk-reporter.png[align="left",alt="PSK Reporter"] * {jtalert}, by VK3AMA, is available only for Windows. It provides many operating aids including automatic logging to several third-party @@ -20,7 +20,7 @@ logging programs, audio and visual alerts following a number of optional alert conditions (decoding of a new DXCC, new state, etc.), and convenient direct access to web services such as callsign lookup. -image::images/jtalert.png[align="left",alt="JTAlert-X image"] +image::jtalert.png[align="left",alt="JTAlert-X image"] * {alarmejt}, by F5JMH, is available only for Linux. The program keeps its own logbook. It fetches contact information from _WSJT-X_ and diff --git a/doc/user_guide/docinfo.html b/doc/user_guide/docinfo.html index 1312ee754..f74a1119d 100644 --- a/doc/user_guide/docinfo.html +++ b/doc/user_guide/docinfo.html @@ -1,4 +1,8 @@