7.1.3

QuantumLeaps · Nov 17, 2022 · 4b3042e · 4b3042e
1 parent 094e463
commit 4b3042e
Show file tree

Hide file tree

Showing 12 changed files with 302 additions and 244 deletions.
diff --git a/.gitignore b/.gitignore
@@ -24,6 +24,7 @@
 version-*
 
 html/
+latex/
 test_priv/
 bin/*.exe
 bin/*.dll

diff --git a/doxygen/Doxyfile b/doxygen/Doxyfile
@@ -1,11 +1,13 @@
 # Doxyfile 1.9.5
 
+@INCLUDE = ../../ql-doxygen/ql-doxyfile
+
 #---------------------------------------------------------------------------
 # Project related configuration options
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = QTools
-PROJECT_NUMBER         = 7.1.2
+PROJECT_NUMBER         = 7.1.3
 PROJECT_BRIEF          = "Collection of Host-Based Tools"
 PROJECT_LOGO           = ../../ql-doxygen/images/logo_ql.png
 OUTPUT_DIRECTORY       =
@@ -40,18 +42,7 @@ PYTHON_DOCSTRING       = YES
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 4
-ALIASES                = "nav{2}=<span class=\"prev_button\">@ref \1</span><span class=\"next_button\">@ref \2</span>" \
-                         "nav_prev{1}=<span class=\"prev_button\">@ref \1</span>" \
-                         "nav_next{1}=<span class=\"next_button\">@ref \1</span>" \
-                         "next{1}=<span class=\"next_button\">@ref \1</span>" \
-                         "description=@par Description" \
-                         "usage=@par Usage" \
-                         "hint=@par Hint" \
-                         "label{1}=<div class=\"label\">\1</div>" \
-                         "caption{1}=<div class=\"caption\" align=\"center\">\1</div>" \
-                         "webref{2}=<a class=\"extern\" target=\"_blank\" href=\"https://www.state-machine.com/\1\">\2</a>" \
-                         "tr{1}=@xrefitem tr \"Traceability\" \"\" traces to: @ref \1"
-OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_FOR_C  = NO
 OPTIMIZE_OUTPUT_JAVA   = NO
 OPTIMIZE_FOR_FORTRAN   = NO
 OPTIMIZE_OUTPUT_VHDL   = NO
@@ -184,7 +175,7 @@ FORTRAN_COMMENT_AFTER  = 72
 #---------------------------------------------------------------------------
 SOURCE_BROWSER         = YES
 INLINE_SOURCES         = NO
-STRIP_CODE_COMMENTS    = YES
+STRIP_CODE_COMMENTS    = NO
 REFERENCED_BY_RELATION = NO
 REFERENCES_RELATION    = NO
 REFERENCES_LINK_SOURCE = YES
@@ -272,68 +263,6 @@ SEARCHDATA_FILE        = searchdata.xml
 EXTERNAL_SEARCH_ID     = QTOOLS
 EXTRA_SEARCH_MAPPINGS  =
 #---------------------------------------------------------------------------
-# Configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-LATEX_MAKEINDEX_CMD    = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = letter
-EXTRA_PACKAGES         =
-LATEX_HEADER           =
-LATEX_FOOTER           =
-LATEX_EXTRA_STYLESHEET =
-LATEX_EXTRA_FILES      =
-PDF_HYPERLINKS         = YES
-USE_PDFLATEX           = YES
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-LATEX_BIB_STYLE        = plain
-LATEX_TIMESTAMP        = NO
-LATEX_EMOJI_DIRECTORY  =
-#---------------------------------------------------------------------------
-# Configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    =
-RTF_EXTENSIONS_FILE    =
-#---------------------------------------------------------------------------
-# Configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN           = NO
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_SUBDIR             =
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_PROGRAMLISTING     = YES
-XML_NS_MEMB_FILE_SCOPE = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the DOCBOOK output
-#---------------------------------------------------------------------------
-GENERATE_DOCBOOK       = NO
-DOCBOOK_OUTPUT         = docbook
-#---------------------------------------------------------------------------
-# Configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX =
-#---------------------------------------------------------------------------
 # Configuration options related to the preprocessor
 #---------------------------------------------------------------------------
 ENABLE_PREPROCESSING   = YES
@@ -343,54 +272,9 @@ SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = Q_SPY \
-                         Q_UTEST
+                         Q_UTEST \
+                         QS_OBJ_PTR_SIZE=4U \
+                         QS_FUN_PTR_SIZE=4U \
+                         Q_SIGNAL_SIZE=2U
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
-#---------------------------------------------------------------------------
-# Configuration options related to external references
-#---------------------------------------------------------------------------
-TAGFILES               =
-GENERATE_TAGFILE       =
-ALLEXTERNALS           = NO
-EXTERNAL_GROUPS        = YES
-EXTERNAL_PAGES         = YES
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-DIA_PATH               =
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = NO
-DOT_NUM_THREADS        = 0
-DOT_COMMON_ATTR        = "fontname=Helvetica,fontsize=10"
-DOT_EDGE_ATTR          = "labelfontname=Helvetica,labelfontsize=10"
-DOT_NODE_ATTR          = "shape=box,height=0.2,width=0.4"
-DOT_FONTPATH           =
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = NO
-GROUP_GRAPHS           = YES
-UML_LOOK               = YES
-UML_LIMIT_NUM_FIELDS   = 10
-DOT_UML_DETAILS        = NO
-DOT_WRAP_THRESHOLD     = 17
-TEMPLATE_RELATIONS     = NO
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
-CALL_GRAPH             = NO
-CALLER_GRAPH           = NO
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
-DIR_GRAPH_MAX_DEPTH    = 1
-DOT_IMAGE_FORMAT       = png
-INTERACTIVE_SVG        = NO
-DOT_PATH               = C:/tools/graphviz/bin
-DOTFILE_DIRS           =
-MSCFILE_DIRS           =
-DIAFILE_DIRS           =
-PLANTUML_JAR_PATH      =
-PLANTUML_CFG_FILE      =
-PLANTUML_INCLUDE_PATH  =
-DOT_GRAPH_MAX_NODES    = 50
-MAX_DOT_GRAPH_DEPTH    = 0
-DOT_MULTI_TARGETS      = NO
-GENERATE_LEGEND        = YES
-DOT_CLEANUP            = YES
diff --git a/doxygen/Doxyfile-CHM b/doxygen/Doxyfile-CHM
@@ -1,10 +1,7 @@
-# Doxyfile 1.9.4
+# Doxyfile 1.9.5
 
 @INCLUDE = Doxyfile
 
-#---------------------------------------------------------------------------
-# Configuration options related to the HTML output
-#---------------------------------------------------------------------------
 PROJECT_LOGO           = images/logo_ql-comp.png
 
 HTML_OUTPUT            = tmp

diff --git a/doxygen/Doxyfile-LATEX b/doxygen/Doxyfile-LATEX
@@ -0,0 +1,11 @@
+# Doxyfile 1.9.5
+
+@INCLUDE = Doxyfile
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = YES
+ENABLED_SECTIONS      += LATEX
+
+# no source code in latex
+SOURCE_BROWSER         = NO
+VERBATIM_HEADERS       = NO
diff --git a/doxygen/history.dox b/doxygen/history.dox
@@ -1,6 +1,14 @@
 /**
 @page history Revision History
 
+@section qtools_7_1_3 Version 7.1.3, 2022-11-18
+@ref qclean "QCLEAN host application":
+- Added new file types and changing some cleaning rules for white-space cleaning.
+
+__Documentation__
+- Modified the `doxygen/` folder for generation of QM Manual in LaTeX (enables generation of PDF)
+
+
 @section qtools_7_1_2 Version 7.1.2, 2022-09-28
 __QSPY host application:__
 - Added pre-defined "Scheduler" records:

diff --git a/doxygen/make.bat b/doxygen/make.bat
@@ -28,12 +28,13 @@
 @echo usage:
 @echo make
 @echo make -CHM
-@echo make ...
+@echo make -LATEX
 
-:: Doxygen tool (adjust to your system) ......................................
+:: tools (adjust to your system)---------------------------------------------
+:: Doxygen tool
 @set DOXYGEN=doxygen
 
-:: HTML Help tool (needed only with the -CHM option, (adjust to your system) .
+:: HTML Help tool (needed only with the -CHM option) .
 @set HHC="C:\tools\HTML Help Workshop\hhc.exe"
 
 :: QTOOLS directory ..........................................................
@@ -42,8 +43,9 @@
 :: HTML outut directory ......................................................
 @set HTML_OUT=%QTOOLS%\html
 
-:: Generate Doxygen Documentation...
+:: Generate Doxygen Documentation -------------------------------------------
 if "%1"=="-CHM" (
+
     @echo Generating HTML...
     %DOXYGEN% Doxyfile-CHM
 
@@ -59,15 +61,31 @@ if "%1"=="-CHM" (
     @rmdir /S /Q  tmp
     @echo CHM file generated
 
+) else if "%1"=="-LATEX" (
+
+    @echo.
+    @echo Cleanup...
+    rmdir /S /Q  %LATEX_OUT%
+
+    @echo Generating LATEX...
+    %DOXYGEN% Doxyfile-LATEX
+
+    @echo Adding custom files...
+    xcopy img %LATEX_OUT%\img\
+
+    @cd %LATEX_OUT%
+    @call make.bat
+
 ) else (
+
     @echo.
     @echo Cleanup...
     rmdir /S /Q  %HTML_OUT%
 
     @echo Generating HTML...
     %DOXYGEN% Doxyfile%1
 
-    @echo Adding custom images...
+    @echo Adding custom files...
     xcopy img %HTML_OUT%\img\
     xcopy /Y ..\..\ql-doxygen\jquery.js %HTML_OUT%
     @qclean %HTML_OUT%

diff --git a/doxygen/qclean.dox b/doxygen/qclean.dox
@@ -72,30 +72,45 @@ QClean can optionally check the code for **long lines of code** that exceed a sp
 QClean applies the following rules for cleaning the whitespace depending on the file types:
 
 <center>
-FILE TYPE      | END-OF-LINE | TRAILING WS | TABS    | LONG-LINES
-:--------------|:------------|:-----------:|:--------:|:------------:
-`.c`           | Unix (LF)   | remove  | replace | check
-`.h`           | Unix (LF)   | remove  | replace | check
-`.cpp`         | Unix (LF)   | remove  | replace | check
-`.hpp`         | Unix (LF)   | remove  | replace | check
-`.s`           | Unix (LF)   | remove  | replace | check
-`.asm`         | Unix (LF)   | remove  | replace | check
-`.lnt`         | Unix (LF)   | remove  | replace | check
-`.txt`         | Unix (LF)   | remove  | replace | don't check
-`.md`          | Unix (LF)   | remove  | replace | don't check
-`.bat`         | DOS (CR,LF) | remove  | replace | don't check
-`.ld`          | Unix (LF)   | remove  | replace | check
-`.py`          | Unix (LF)   | remove  | replace | check
-`.pyw`         | Unix (LF)   | remove  | replace | check
-`.tcl`         | Unix (LF)   | remove  | replace | check
-`.java`        | Unix (LF)   | remove  | replace | check
-`Makefile`     | Unix (LF)   | remove  | leave   | check
-`.mak`         | Unix (LF)   | remove  | leave   | check
-`.html`        | Unix (LF)   | remove  | replace | don't check
-`.htm`         | Unix (LF)   | remove  | replace | don't check
-`.php`         | Unix (LF)   | remove  | replace | don't check
-`.dox`         | Unix (LF)   | remove  | replace | don't check
-`.m`           | Unix (LF)   | remove  | replace | check
+FILE TYPE       | END-OF-LINE | TRAILING WS | TABS    | LONG-LINES
+:---------------|:------------|:-----------:|:--------:|:------------:
+`.c`            | Unix (LF)   | remove  | replace | check
+`.h`            | Unix (LF)   | remove  | replace | check
+`.cpp`          | Unix (LF)   | remove  | replace | check
+`.hpp`          | Unix (LF)   | remove  | replace | check
+`.s/.S`         | Unix (LF)   | remove  | replace | check
+`.asm`          | Unix (LF)   | remove  | replace | check
+`.txt`          | Unix (LF)   | remove  | replace | don't check
+`.xml`          | Unix (LF)   | remove  | replace | don't check
+`.dox`          | Unix (LF)   | remove  | replace | don't check
+`.md`           | Unix (LF)   | remove  | replace | don't check
+`.bat`          | Unix (LF)   | remove  | replace | don't check
+`.ld`           | Unix (LF)   | remove  | replace | check
+`.py`           | Unix (LF)   | remove  | replace | check
+`.pyw`          | Unix (LF)   | remove  | replace | check
+`.java`         | Unix (LF)   | remove  | replace | check
+`Makefile`      | Unix (LF)   | remove  | leave   | check
+`mak_*`         | Unix (LF)   | remove  | leave   | check
+`.mak`          | Unix (LF)   | remove  | leave   | check
+`.make`         | Unix (LF)   | remove  | leave   | check
+`.html`         | Unix (LF)   | remove  | replace | don't check
+`.htm`          | Unix (LF)   | remove  | replace | don't check
+`.css`          | Unix (LF)   | remove  | replace | don't check
+`.eww`          | Unix (LF)   | remove  | replace | don't check
+`.ewp`          | Unix (LF)   | remove  | replace | don't check
+`.ewd`          | Unix (LF)   | remove  | replace | don't check
+`.icf`          | Unix (LF)   | remove  | replace | don't check
+`.sln`          | Unix (LF)   | remove  | replace | don't check
+`.vcxproj`      | Unix (LF)   | remove  | replace | don't check
+`.filters`      | Unix (LF)   | remove  | replace | don't check
+`.vcxproj.filters` | Unix (LF) | remove | replace | don't check
+`.project`      | Unix (LF)   | remove  | replace | don't check
+`.cproject`     | Unix (LF)   | remove  | replace | don't check
+`.pro`          | Unix (LF)   | remove  | replace | don't check
+`.m`            | Unix (LF)   | remove  | replace | check
+`.lnt`          | Unix (LF)   | remove  | replace | check
+`.cfg`          | Unix (LF)   | remove  | replace | don't check
+`.properties`   | Unix (LF)   | remove  | replace | don't check
 </center>
 
 <br>

diff --git a/doxygen/qpspy.dox b/doxygen/qpspy.dox
@@ -9,7 +9,7 @@ So the questions are: How can you monitor the behavior of a running real-time sy
 Techniques based on **software tracing** can answer many of these questions. Software tracing is a method for obtaining diagnostic information in a live environment without the need to stop the application to get system feedback. Software tracing always involves some form of target system instrumentation to log interesting discrete events for subsequent retrieval from the system and analysis.
 
 @anchor qpspy_framework
-@note
+@remarks
 Software tracing is particularly effective and powerful in combination with the event-driven **reactive programming** model, such as the one implemented in <a class="extern" target="_blank" href="https://www.state-machine.com/products/#QP">QP&trade; real-time frameworks</a>. Due to the inversion of control, a real-time framework controls almost all interesting interactions in the system, so an instrumented real-time framework can provide much **more comprehensive** and detailed information than can any traditional RTOS kernel.<br>
 ![Comprehensive tracing information available in a Real-Time Embedded Framework](qspy-funnel.png)
 
@@ -122,19 +122,20 @@ Of course, now the Escape byte itself must also be transparent to avoid interpre
 
 The transparency of the Flag and Escape bytes complicates slightly the computation of the Checksum. The transmitter computes the Checksum over the Frame Sequence Number, the Record-Type, and all Data bytes before performing any “byte-stuffing”. The receiver must apply the exact reversed procedure of performing the “byte-un-stuffing” before computing the Checksum.
 
-An example may make this clearer. Suppose that the following trace record needs to be inserted into the trace buffer (the transparent bytes are shown in bold):
+An example may make this clearer. Suppose that the following trace record needs to be inserted into the trace buffer (the transparent bytes are shown in in `code` format):
 
-> Record-Type = <b>0x7D</b>, Record Data = <b>0x7D</b> 0x08 0x01
+&nbsp;&nbsp;&nbsp;&nbsp; Record-Type = `0x7D`, Record Data = `0x7D` 0x08 0x01
 
 Assuming that the current Frame Sequence Number is, say `0x7E`, the Checksum will be computed over the following bytes:
 
-> Checksum == (uint8_t)(~(0x7E + <b>0x7D</b> + <b>0x7D</b> + 0x08 + 0x01)) == 0x7E
+&nbsp;&nbsp;&nbsp;&nbsp; Checksum == (uint8_t)(~(0x7E + `0x7D` + `0x7D` + 0x08 + 0x01)) == 0x7E
 
 and the actual frame inserted into the QS trace buffer will be as follows:
 
-> 0x7D <b>0x5E</b> 0x7D <b>0x5D</b> 0x7D <b>0x5D</b> 0x08 0x01 0x7D <b>0x5E</b> 0x7E
+&nbsp;&nbsp;&nbsp;&nbsp; 0x7D `0x5E` 0x7D `0x5D` 0x7D `0x5D` 0x08 0x01 0x7D `0x5E` 0x7E
 
-Obviously, this is a degenerate example, where the Frame Sequence Number, the Record-Type, a Data byte, and the Checksum itself turned out to be the transparent bytes. Typical overhead of transparency with real trace data is one escape sequence per several trace records.
+@note
+This is a degenerate example, where the Frame Sequence Number, the Record-Type, a Data byte, and the Checksum itself turned out to be the transparent bytes. A more typical overhead of transparency with real trace data is one escape sequence per several trace records.
 
 
 @section qpspy_endianness Endianness