Skip to content

Commit 342de11

Browse files
BrianSiposBrianSipos
committed
Updated docs and using xslTNG output styleseet for better HTML rendering
1 parent 7755866 commit 342de11

17 files changed

Lines changed: 386 additions & 224 deletions

‎CMakeLists.txt‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,19 @@ cmake_minimum_required(VERSION 3.16)
2424
project(bsl-docs LANGUAGES )
2525
set(CMAKE_INSTALL_PREFIX "")
2626

27+
include(FetchContent)
28+
FetchContent_Declare(
29+
xsltng
30+
URL https://codeberg.org/DocBook/xslTNG/releases/download/2.8.0/docbook-xslTNG-2.8.0.zip
31+
URL_HASH SHA256=adbbddbf33a4fcc5c949a2851cac53e8111d30a5fd0b32429eeec68aedb61efd
32+
DOWNLOAD_EXTRACT_TIMESTAMP OFF
33+
)
34+
FetchContent_MakeAvailable(xsltng)
35+
file(GLOB xsltng_JAR "${xsltng_SOURCE_DIR}/libs/*.jar")
36+
if(NOT xsltng_JAR)
37+
message(FATAL_ERROR "No xslTNG jar file found under ${xsltng_SOURCE_DIR}")
38+
endif(NOT xsltng_JAR)
39+
2740
add_subdirectory(user-guide)
2841
add_subdirectory(product-guide)
2942

‎product-guide/CMakeLists.txt‎

Lines changed: 48 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -63,22 +63,30 @@ add_custom_target(
6363
${CMAKE_CURRENT_BINARY_DIR} ${OUT_DBOOK}
6464
)
6565

66+
find_program(JAVA_BIN java REQUIRED)
67+
find_program(XMLSTARLET xmlstarlet REQUIRED)
6668
set(HTML_XSLT "${CMAKE_CURRENT_SOURCE_DIR}/xhtml-opts.xsl")
6769
set(MANUAL_CSS "${CMAKE_CURRENT_SOURCE_DIR}/manual.css")
68-
find_program(XMLSTARLET xmlstarlet REQUIRED)
70+
set(DOCBOOK_CSS_FILES
71+
"docbook.css" "docbook-paged.css"
72+
"docbook-toc.css" "pygments.css"
73+
)
74+
set(DOCBOOK_JS_FILES "copy-verbatim.js" "persistent-toc.js")
75+
set(OUT_MANUAL_CSS "html/css/manual.css")
6976
set(OUT_HTML "html/index.html")
70-
set(OUT_DOCBOOK_CSS "html/docbook.css")
71-
set(OUT_MANUAL_CSS "html/manual.css")
72-
add_custom_command(
73-
OUTPUT "html"
74-
COMMAND ${CMAKE_COMMAND} -E make_directory html
77+
78+
configure_file(
79+
"xml-catalog.xml.in"
80+
"xml-catalog.xml"
81+
@ONLY
7582
)
7683
add_custom_command(
7784
OUTPUT ${OUT_HTML}
78-
BYPRODUCTS ${OUT_DOCBOOK_CSS}
79-
DEPENDS ${OUT_DBOOK} ${HTML_XSLT} "html"
80-
WORKING_DIRECTORY html
81-
COMMAND ${XMLSTARLET} tr ${HTML_XSLT} ${OUT_DBOOK} >index.html
85+
DEPENDS ${OUT_DBOOK} "xml-catalog.xml" ${HTML_XSLT}
86+
COMMAND
87+
${JAVA_BIN} -jar ${xsltng_JAR}
88+
-catalog:xml-catalog.xml -xsl:${HTML_XSLT}
89+
-o:${OUT_HTML} ${OUT_DBOOK}
8290
)
8391
# Place needed files into HTML tree
8492
add_custom_command(
@@ -87,6 +95,29 @@ add_custom_command(
8795
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${MANUAL_CSS} ${OUT_MANUAL_CSS}
8896
COMMENT "Copy manual.css"
8997
)
98+
set(OUT_DOCBOOK_FILES "")
99+
foreach(FILENAME ${DOCBOOK_CSS_FILES})
100+
set(INPATH "${xsltng_SOURCE_DIR}/resources/css/${FILENAME}")
101+
set(OUTPATH "html/css/${FILENAME}")
102+
add_custom_command(
103+
OUTPUT ${OUTPATH}
104+
DEPENDS ${INPATH}
105+
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${INPATH} ${OUTPATH}
106+
COMMENT "Copy css/${FILENAME}"
107+
)
108+
list(APPEND OUT_DOCBOOK_FILES ${OUTPATH})
109+
endforeach()
110+
foreach(FILENAME ${DOCBOOK_JS_FILES})
111+
set(INPATH "${xsltng_SOURCE_DIR}/resources/js/${FILENAME}")
112+
set(OUTPATH "html/js/${FILENAME}")
113+
add_custom_command(
114+
OUTPUT ${OUTPATH}
115+
DEPENDS ${INPATH}
116+
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${INPATH} ${OUTPATH}
117+
COMMENT "Copy js/${FILENAME}"
118+
)
119+
list(APPEND OUT_DOCBOOK_FILES ${OUTPATH})
120+
endforeach()
90121
add_custom_target(
91122
${PROJECT_NAME}-img-html
92123
DEPENDS ${INSTALL_IMGS} ${OUT_HTML} ${PROJECT_NAME}-img-bin
@@ -97,7 +128,7 @@ add_custom_target(
97128
add_custom_target(
98129
${PROJECT_NAME}-html ALL
99130
DEPENDS
100-
${OUT_HTML} ${OUT_DOCBOOK_CSS} ${OUT_MANUAL_CSS} ${PROJECT_NAME}-img-html
131+
${OUT_HTML} ${OUT_MANUAL_CSS} ${OUT_DOCBOOK_FILES} ${PROJECT_NAME}-img-html
101132
)
102133
install(
103134
DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html"
@@ -134,12 +165,16 @@ add_custom_target(
134165

135166
# PDF document output
136167
find_program(DBLATEX dblatex REQUIRED)
168+
set(PDF_STYLE "${CMAKE_CURRENT_SOURCE_DIR}/manual.sty")
137169
set(PDF_XSLT "${CMAKE_CURRENT_SOURCE_DIR}/pdf-opts.xsl")
138170
set(OUT_PDF "manual.pdf")
139171
add_custom_command(
140172
OUTPUT ${OUT_PDF}
141-
DEPENDS ${OUT_DBOOK} ${PDF_XSLT} ${PROJECT_NAME}-img-bin
142-
COMMAND ${DBLATEX} -o ${OUT_PDF} --xsl-user=${PDF_XSLT} ${OUT_DBOOK}
173+
DEPENDS ${OUT_DBOOK} ${PDF_STYLE} ${PDF_XSLT} ${PROJECT_NAME}-img-bin
174+
COMMAND
175+
${DBLATEX}
176+
--texstyle=${PDF_STYLE} --xsl-user=${PDF_XSLT}
177+
-o ${OUT_PDF} ${OUT_DBOOK}
143178
)
144179
add_custom_target(
145180
${PROJECT_NAME}-pdf ALL

‎product-guide/dictionary.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ MCS
4949
MGSS
5050
middleware
5151
MIMTaR
52+
MLIB
5253
NIST
5354
OpenSSL
5455
PDU
@@ -78,9 +79,12 @@ subpackage
7879
superset
7980
TBD
8081
texlive
82+
tito
83+
toc
8184
UDP
8285
UDPCL
8386
un
8487
Verifier
8588
virtualenv
89+
wireshark
8690
Wireshark

‎product-guide/images/dep_chart.dot‎

Lines changed: 3 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,7 @@
11
digraph "bsl" {
2-
node [
3-
fontsize = "12"
4-
];
5-
subgraph clusterLegend {
6-
label = "Legend";
7-
color = black;
8-
edge [ style = invis ];
9-
legendNode0 [ label = "Executable", shape = egg ];
10-
legendNode1 [ label = "Static Library", shape = octagon ];
11-
legendNode2 [ label = "Shared Library", shape = doubleoctagon ];
12-
legendNode3 [ label = "Module Library", shape = tripleoctagon ];
13-
legendNode4 [ label = "Interface Library", shape = pentagon ];
14-
legendNode5 [ label = "Object Library", shape = hexagon ];
15-
legendNode6 [ label = "Unknown Library", shape = septagon ];
16-
legendNode7 [ label = "Custom Target", shape = box ];
17-
legendNode0 -> legendNode1 [ style = solid ];
18-
legendNode0 -> legendNode2 [ style = solid ];
19-
legendNode0 -> legendNode3;
20-
legendNode1 -> legendNode4 [ label = "Interface", style = dashed ];
21-
legendNode2 -> legendNode5 [ label = "Private", style = dotted ];
22-
legendNode3 -> legendNode6 [ style = solid ];
23-
legendNode0 -> legendNode7;
24-
}
2+
node [
3+
fontsize = "12"
4+
];
255
"node0" [ label = "bsl-mock-bpa", shape = egg ];
266
"node1" [ label = "Threads::Threads", shape = pentagon ];
277
"node0" -> "node1" [ style = dotted ] // bsl-mock-bpa -> Threads::Threads

‎product-guide/images/dep_chart_legend.dot‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
digraph clusterLegend {
2+
node [
3+
fontsize = "12"
4+
];
5+
6+
color = black;
7+
edge [ style = invis ];
8+
legendNode0 [ label = "Executable", shape = egg ];
9+
legendNode1 [ label = "Static Library", shape = octagon ];
10+
legendNode2 [ label = "Shared Library", shape = doubleoctagon ];
11+
legendNode3 [ label = "Module Library", shape = tripleoctagon ];
12+
legendNode4 [ label = "Interface Library", shape = pentagon ];
13+
legendNode5 [ label = "Object Library", shape = hexagon ];
14+
legendNode6 [ label = "Unknown Library", shape = septagon ];
15+
legendNode7 [ label = "Custom Target", shape = box ];
16+
legendNode0 -> legendNode1 [ style = solid ];
17+
legendNode0 -> legendNode2 [ style = solid ];
18+
legendNode0 -> legendNode3;
19+
legendNode1 -> legendNode4 [ label = "Interface", style = dashed ];
20+
legendNode2 -> legendNode5 [ label = "Private", style = dotted ];
21+
legendNode3 -> legendNode6 [ style = solid ];
22+
legendNode0 -> legendNode7;
23+
}

‎product-guide/manual.adoc‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -319,7 +319,11 @@ These components are represented as targets (libraries and executables) in the d
319319

320320
[#fig-bsl-targets]
321321
.CMake-Generated Target Graph
322-
graphviz::images/dep_chart.dot[format=svg,scaledwidth=100%]
322+
graphviz::images/dep_chart.dot[format=svg,width=180mm]
323+
324+
[#fig-cmake-legent]
325+
.CMake Graph Legend
326+
graphviz::images/dep_chart_legend.dot[format=svg,width=120mm]
323327

324328
=== Build and Runtime Environments
325329

‎product-guide/manual.css‎

Lines changed: 35 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,57 @@
1-
html {
2-
font-family: sans-serif;
3-
-webkit-text-size-adjust: 100%;
1+
:root {
2+
background-color: #f8f8f8;
43
}
54

6-
html,
7-
body {
8-
font-size: 100%;
5+
main {
6+
padding-top: 0em;
7+
padding-left: 1em;
8+
padding-right: 1em;
9+
background-color: #ffffff;
10+
--background-color: #ffffff;
11+
--header-color: #ffffff;
912
}
1013

11-
body {
14+
div.legalnotice {
15+
margin: 0.5em;
16+
padding: 0.5em;
17+
}
18+
div.legalnotice header {
1219
margin-top: 1em;
13-
margin-bottom: 2em;
14-
margin-left: 7em;
15-
margin-right: 10em;
1620
}
1721

18-
body {
19-
color: rgba(0, 0, 0, 0.8);
20-
font-family: "Open Sans", "DejaVu Sans", sans-serif;
21-
line-height: 1;
22-
position: relative;
23-
cursor: auto;
24-
tab-size: 4;
25-
word-wrap: anywhere;
26-
-moz-osx-font-smoothing: grayscale;
27-
-webkit-font-smoothing: antialiased;
22+
div.revhistory div.title, div.revhistory ul {
23+
border-bottom-style: solid;
24+
border-bottom-width: 1px;
25+
border-bottom-color: #808080;
2826
}
29-
30-
ul,
31-
ol,
32-
dl {
33-
line-height: 1.2;
34-
margin-bottom: 1.25em;
35-
list-style-position: outside;
36-
font-family: inherit;
27+
div.revhistory p {
28+
margin-top: 8px;
29+
margin-bottom: 8px;
3730
}
3831

39-
ul,
40-
ol {
41-
margin-left: 1.5em;
32+
ul.toc {
33+
padding-left: 1em;
4234
}
43-
44-
ul li ul,
45-
ul li ol {
46-
margin-left: 1.25em;
35+
ul.toc li {
36+
padding-left: 1em;
4737
}
4838

49-
dl dt {
50-
margin-bottom: 0.3125em;
39+
div.varlistentry dt {
5140
font-weight: bold;
5241
}
53-
54-
dl dd {
55-
margin-bottom: 1.25em;
42+
div.varlistentry dd p {
43+
margin-top: 0;
5644
}
5745

58-
div.figure {
59-
text-align: center;
60-
margin-top: 1em;
61-
margin-bottom: 1em;
62-
}
63-
div.figure-title {
64-
margin-bottom: 1em;
46+
td p {
47+
margin-top: 4px;
48+
margin-bottom: 4px;
6549
}
6650

67-
div.table {
68-
text-align: center;
69-
margin-top: 1em;
70-
margin-bottom: 1em;
71-
}
72-
div.table-title {
73-
margin-bottom: 1em;
74-
}
75-
div.table table {
76-
margin-left: auto;
77-
margin-right: auto;
51+
div.figure {
52+
border-color: #c8c8c8;
7853
}
7954

80-
div.note {
81-
margin-left: 4em;
82-
margin-right: 6em;
55+
div.qanda div.question {
56+
font-weight: bold;
8357
}

‎product-guide/manual.sty‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
%%
2+
%% This style is derivated from the docbook one
3+
%%
4+
\NeedsTeXFormat{LaTeX2e}
5+
\ProvidesPackage{mystyle}[2007/04/04 My DocBook Style]
6+
7+
%% Just use the original package and pass the options
8+
\RequirePackageWithOptions{docbook}
9+
10+
%% Allow "json" source files
11+
\lstdefinelanguage{json}{
12+
basicstyle=\normalfont\small\ttfamily,
13+
numbers=left,
14+
numberstyle=\scriptsize,
15+
stepnumber=1,
16+
numbersep=8pt,
17+
showstringspaces=false,
18+
breaklines=true,
19+
frame=lines,
20+
string=[s]{"}{"},
21+
comment=[l]{:[},
22+
morecomment=[l]{:"},
23+
literate=
24+
*{0}{{{\color{red}0}}}{1}
25+
{1}{{{\color{red}1}}}{1}
26+
{2}{{{\color{red}2}}}{1}
27+
{3}{{{\color{red}3}}}{1}
28+
{4}{{{\color{red}4}}}{1}
29+
{5}{{{\color{red}5}}}{1}
30+
{6}{{{\color{red}6}}}{1}
31+
{7}{{{\color{red}7}}}{1}
32+
{8}{{{\color{red}8}}}{1}
33+
{9}{{{\color{red}9}}}{1}
34+
{:}{{{\color{black}:}}}{1}
35+
{,}{{{\color{black},}}}{1}
36+
{\{}{{{\color{black}\{}}}{1}
37+
{\}}{{{\color{black}\}}}}{1}
38+
{[}{{{\color{black}[}}}{1}
39+
{]}{{{\color{black}]}}}{1},
40+
}

0 commit comments

Comments
 (0)