Execution of "make manual" created HTML output, but document inspection
suffered from missing screenshots. Symlink the images/ subdirectory so
that source file content is re-used in output hierarchies.
This has gone unnoticed because "make install" references source files,
and the manual author appears to not use out of source builds. Only
out of source builds and only HTML output inspection before installation
were affected. Installed manuals were not affected.
How to reproduce:
$ cmake --build $OUT --target manual
$ xdg-open $OUT/manual/manual.html
This amends commit f2f536aa7b which introduced manual build rules and
duplicated HTML in two locations. One of them is PDF creation. Fix it.
This was spotted by smuview maintenance.
The cmake rules in the manual/ subdirectory are designed to work both in
the context of the application build, as well as for exclusive creation
of the manual.
Add a project() directive in the manual/ cmake rules. Its absence was
not fatal but resulted in warnings. This amends commit 074da67ee2.
This will do the right thing for both the PDF and HMTL manual.
Without the double-quotes, copy-pasting the command-line invocations
will not work as expected.
It's good tradition to put options right after the command name, and
list positional arguments after the list of options. Putting options
late only works by coincidence and trains bad habits. Adjust the wget
command lines accordingly.
Reported-By: Peter Mortensen via IRC
Add a cmake_minimum_required() directive to the manual/ subdir's CMake
rules, such that the documentation can get built without involving the
application and its build dependencies.
Expand the discussion that timing information is not required or
optional to some decoders, but essential to others (because of the very
protocol that gets interpreted). Mention that some oversampling is
typically required. Don't suggest that PD exceptions must be bugs,
incomplete configuration may be even more typical.
Separate the "you can ..." introduction from the first check list item,
to increase visibility of the entry. Existing text was not re-flown, to
reduce the diff size.
Extend the CMake rules for the manual. Do install the images/ subdir but
omit the *.xcf files. Prepare the CSS file although this seems to be not
strictly necessary (gets inlined, but we are prepared if it's external).
Only install these additional files when the asciidoctor(1) tool is
available, and thus the .html file can get generated (to not install
some questionable combination of a .pdf and unrelated .png files, or to
not install the resources when none of the manual files got created).
This approach was tested with the following command sequence:
$ make manual
$ make install
$ xdg-open ~/share/doc/pulseview/*.html
The asciidoctor(1) executable is considered mandatory when building the
Pulseview manual. The asciidoctor-pdf(1) executable is not universally
available (is missing in Debian), accept its absence, avoid execution
failure in that case.
This implementation replaces the actual .txt to .pdf conversion with a
mere echo(1) message, which may go unnoticed in verbose build output.
"make --no-print-directories manual" may be required to remain aware.
Introduce new "manual", "manual-html" and "manual-pdf" make(1) targets
(the former depending on the latter). None of these targets are part of
"make all" by design, users decide whether to convert the manual text.
Execution will fail (fatally) in the absence of dependencies or tools.
Soeren Apel
Gerhard Sittig
Uwe Hermann
Devan Lai