Mirrors/zint
1
0
Fork 0
mirror of https://git.code.sf.net/p/zint/code synced 2025-12-18 10:27:09 +00:00
Code Issues Projects Releases Wiki Activity

manual: use modified "haddock.theme" for nicer syntax highlighting;

Browse Source 
use `tcolorbox` instead of `framed` for latex code blocks, works
  much better, especially as now when using a background colour;
  reduce gap after figures and force footnotes to bottom of page;
  move most symbology figures to after some text to lessen chance
  of subsection headers being orphaned on their own at end of page:
  required a number of rewordings;
  use named barcodes in example commands, rather than numbered;
  fix "lua-crossrefs" filter to allow parentheses around
  references;
  various other fixes and rephrasings
This commit is contained in:
gitlost
2025-10-12 22:17:14 +01:00
parent a3cca33f32
commit dc4ba75eb0
9 changed files with 1912 additions and 1568 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/Makefile
View File

@@ -9,6 +9,7 @@ SOURCE = manual.pmd
OUT_PDF = manual.pdf OUT_PDF = manual.pdf
OUT_TXT = manual.txt OUT_TXT = manual.txt
OUT_HTML = manual.html OUT_HTML = manual.html
HIGHLIGHT_THEME = haddock.theme
INC_HEADER_PDF = inc_header_pdf.tex INC_HEADER_PDF = inc_header_pdf.tex
INC_BEFORE_BODY_PDF = inc_before_body_pdf.tex INC_BEFORE_BODY_PDF = inc_before_body_pdf.tex
INC_PDF = --include-in-header $(INC_HEADER_PDF) --include-before-body $(INC_BEFORE_BODY_PDF) INC_PDF = --include-in-header $(INC_HEADER_PDF) --include-before-body $(INC_BEFORE_BODY_PDF)
@@ -17,7 +18,7 @@ INC_TXT = --include-in-header $(INCLUDES_TXT)
SOURCE_MAN_PAGE = zint.1.pmd SOURCE_MAN_PAGE = zint.1.pmd
OUT_MAN_PAGE = zint.1 OUT_MAN_PAGE = zint.1
LUA_FILTER = lua-crossrefs/lua-crossrefs.lua LUA_FILTER = lua-crossrefs/lua-crossrefs.lua
INFRASTRUCTURE = Makefile $(LUA_FILTER) INFRASTRUCTURE = Makefile $(LUA_FILTER) $(HIGHLIGHT_THEME)
IMAGES = \ IMAGES = \
images/zint.png \ images/zint.png \
images/zint-qt.png \ images/zint-qt.png \
@@ -152,7 +153,7 @@ MONO_FONT = monofont="Liberation Mono"
CJK_FONT = CJKmainfont="WenQuanYi Micro Hei Mono" CJK_FONT = CJKmainfont="WenQuanYi Micro Hei Mono"
PDF_OPTS = --pdf-engine=xelatex \ PDF_OPTS = --pdf-engine=xelatex \
--lua-filter=$(LUA_FILTER) \ --lua-filter=$(LUA_FILTER) \
--syntax-highlighting=haddock -V colorlinks -V geometry:margin=20mm -V papersize=a4 \ --syntax-highlighting=$(HIGHLIGHT_THEME) -V colorlinks -V geometry:margin=20mm -V papersize=a4 \
-V csquotes=true --dpi=300 -V csquotes=true --dpi=300
TEX_MAN_PAGE = zint.1.tex TEX_MAN_PAGE = zint.1.tex
TXT_OPTS = --lua-filter=$(LUA_FILTER) \ TXT_OPTS = --lua-filter=$(LUA_FILTER) \
@@ -210,7 +211,7 @@ manual.tex : $(SOURCE) $(SOURCE_MAN_PAGE) $(INC_HEADER_PDF) $(INC_BEFORE_BODY_PD
# HTML one-page (uses modified "templates/styles.html", unchanged "templates/default.html") # HTML one-page (uses modified "templates/styles.html", unchanged "templates/default.html")
HTML_OPTS = --lua-filter=$(LUA_FILTER) \ HTML_OPTS = --lua-filter=$(LUA_FILTER) \
--syntax-highlighting=haddock \ --syntax-highlighting=$(HIGHLIGHT_THEME) \
--template=templates/default.html --eol=lf -s -t html --template=templates/default.html --eol=lf -s -t html
INC_BEFORE_BODY_HTML = inc_before_body_html.html INC_BEFORE_BODY_HTML = inc_before_body_html.html
INC_HTML = --include-before-body $(INC_BEFORE_BODY_HTML) INC_HTML = --include-before-body $(INC_BEFORE_BODY_HTML)

197
docs/haddock.theme Normal file
View File

@@ -0,0 +1,197 @@
{
"text-color": "#351c35",
"background-color": "#fafafe",
"line-number-color": "#aaaaaa",
"line-number-background-color": null,
"text-styles": {
"Alert": {
"text-color": "#ff0000",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Annotation": {
"text-color": "#008000",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Attribute": {
"text-color": null,
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"BuiltIn": {
"text-color": null,
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Char": {
"text-color": "#008080",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Comment": {
"text-color": "#0047AB",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"CommentVar": {
"text-color": "#008000",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Constant": {
"text-color": null,
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"ControlFlow": {
"text-color": "#A52A2A",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"DataType": {
"text-color": "#2E8B57",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"DecVal": {
"text-color": "#DC143C",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Documentation": {
"text-color": "#008000",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Error": {
"text-color": "#ff0000",
"background-color": null,
"bold": true,
"italic": false,
"underline": false
},
"Extension": {
"text-color": null,
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Float": {
"text-color": "#DC143C",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Import": {
"text-color": "#DC143C",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Information": {
"text-color": "#008000",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Keyword": {
"text-color": "#2E8B57",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Operator": {
"text-color": null,
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Other": {
"text-color": "#ff4000",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Preprocessor": {
"text-color": null,
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"SpecialChar": {
"text-color": "#DC143C",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"SpecialString": {
"text-color": "#008080",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"String": {
"text-color": "#DC143C",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Variable": {
"text-color": null,
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"VerbatimString": {
"text-color": "#008080",
"background-color": null,
"bold": false,
"italic": false,
"underline": false
},
"Warning": {
"text-color": "#008000",
"background-color": null,
"bold": true,
"italic": false,
"underline": false
}
}
}

22
docs/inc_header_pdf.tex
View File

@@ -18,18 +18,16 @@
\ifx\tmp\@nnil\originalitem\else\originalitem[#1]\hfill\par\fi} \ifx\tmp\@nnil\originalitem\else\originalitem[#1]\hfill\par\fi}
\makeatother \makeatother
%% Text and background color for inline code %% Use the wonderful `tcolorbox` instead of `framed` for fenced code blocks
\usepackage{tcolorbox}
\tcbuselibrary{breakable}
\renewenvironment{Shaded}{\begin{tcolorbox}[colframe=white,boxrule=0pt,boxsep=0.5mm,top=0mm,bottom=0mm,colback=shadecolor,breakable=true]}{\end{tcolorbox}}
%% Text color for inline code
\usepackage{xcolor} \usepackage{xcolor}
\definecolor{icfg}{HTML}{331a33} \definecolor{icfg}{HTML}{351c35} % "text-color" in modified "haddock.theme"
\let\oldtexttt\texttt \let\oldtexttt\texttt
\renewcommand{\texttt}[1]{\textcolor{icfg}{\oldtexttt{#1}}} \renewcommand{\texttt}[1]{\textcolor{icfg}{\oldtexttt{#1}}}
%% Unfortunately this messes up wrapping TODO: fix
%% Background color for inline code https://tex.stackexchange.com/a/507116
%\definecolor{icbg}{HTML}{fafafa} % Same as modified pygments.theme
%\newcommand{\code}[1]{%
%\begingroup\setlength{\fboxsep}{1pt}
%\colorbox{icbg}{\oldtexttt{\hspace*{0.1pt}\vphantom{A}#1\hspace*{0.1pt}}}\endgroup}
%\renewcommand{\texttt}[1]{\textcolor{icfg}{\code{\oldtexttt{#1}}}}
%% Make level-4 headings standalone (not run-in) - for some reason "-V block-headings" doesn't seem to work, so do %% Make level-4 headings standalone (not run-in) - for some reason "-V block-headings" doesn't seem to work, so do
%% what it does manually here %% what it does manually here
@@ -39,5 +37,9 @@
%% PDF metadata - the values are set in "docs/inc_before_body_pdf.tex" (otherwise may get overridden) %% PDF metadata - the values are set in "docs/inc_before_body_pdf.tex" (otherwise may get overridden)
\usepackage{hyperref} \usepackage{hyperref}
%% pandoc-lua-crossrefs: required package %% Reduce gap after figures
\usepackage{caption} \usepackage{caption}
\captionsetup[figure]{belowskip=-6pt}
%% Make footnotes go to bottom of page
\usepackage[bottom]{footmisc}

13
docs/lua-crossrefs/.luacheckrc Normal file
View File

@@ -0,0 +1,13 @@
stds.pandoc = {
read_globals = {
'FORMAT',
'pandoc',
'PANDOC_VERSION',
},
globals = {
'Pandoc',
},
}
std = 'lua54+pandoc'

9
docs/lua-crossrefs/lua-crossrefs.lua
View File

@@ -5,12 +5,14 @@
-- © 2025 R. N. West. Released under the GPL version 2 or greater. -- © 2025 R. N. West. Released under the GPL version 2 or greater.
-- SPDX-License-Identifier: GPL-2.0-or-later -- SPDX-License-Identifier: GPL-2.0-or-later
PANDOC_VERSION:must_be_at_least '3.8.2'
-- Hacked from "pandoc-lua-crossrefs/init.lua" -- Hacked from "pandoc-lua-crossrefs/init.lua"
-- Table of Ids and corresponding cross-referenceable elements. To be populated -- Table of Ids and corresponding cross-referenceable elements. To be populated
-- by various element numbering functions. -- by various element numbering functions.
---@type table<string, {type: ('fig'|'tbl'), number: string, caption: string}> ---@type table<string, {type: ('fig'|'tbl'), number: string, caption: string}>
IDs = {} local IDs = {}
-- Hacked from "pandoc-lua-crossrefs/lib/crossrefs.lua" -- Hacked from "pandoc-lua-crossrefs/lib/crossrefs.lua"
@@ -26,8 +28,8 @@ end
---@param str Str ---@param str Str
---@return Inline[] | nil ---@return Inline[] | nil
local _parse_crossref = function(str) local _parse_crossref = function(str)
local opening_bracket, prefix_suppressor, id, closing_bracket1, punctuation, closing_bracket2 = local opening_paren, opening_bracket, prefix_suppressor, id, closing_bracket1, punctuation, closing_bracket2 =
str.text:match('^(%[?)(%-?)#([%a%d-_:%.]-)(%]?)([\\%.!:?,;)]-)(%]?)$') str.text:match('^(%(?)(%[?)(%-?)#([%a%d-_:%.]-)(%]?)([\\%.!:?,;)]-)(%]?)$')
if not id or id == '' then return end if not id or id == '' then return end
local only_internal_punctuation = id:find('^[%a%d]+[%a%d%-_:%.]*[%a%d]+$') or id:find('^[%a%d]+$') local only_internal_punctuation = id:find('^[%a%d]+[%a%d%-_:%.]*[%a%d]+$') or id:find('^[%a%d]+$')
if not only_internal_punctuation then return end if not only_internal_punctuation then return end
@@ -37,6 +39,7 @@ local _parse_crossref = function(str)
if prefix_suppressor == '-' then crossref.attributes['reference-type'] = 'ref' end if prefix_suppressor == '-' then crossref.attributes['reference-type'] = 'ref' end
local elts = pandoc.List { crossref } local elts = pandoc.List { crossref }
if opening_bracket == '[' then elts:insert(1, pandoc.Str('[')) end if opening_bracket == '[' then elts:insert(1, pandoc.Str('[')) end
if opening_paren == '(' then elts:insert(1, pandoc.Str('(')) end
if closing_bracket1 == ']' then elts:insert(pandoc.Str(']')) end if closing_bracket1 == ']' then elts:insert(pandoc.Str(']')) end
if punctuation ~= '' then elts:insert(pandoc.Str(punctuation)) end if punctuation ~= '' then elts:insert(pandoc.Str(punctuation)) end
if closing_bracket2 == ']' then elts:insert(pandoc.Str(']')) end if closing_bracket2 == ']' then elts:insert(pandoc.Str(']')) end

1580
docs/manual.html
View File

File diff suppressed because it is too large Load Diff

832
docs/manual.pmd
View File

File diff suppressed because it is too large Load Diff

796
docs/manual.txt
View File

File diff suppressed because it is too large Load Diff

4
docs/templates/styles.html vendored
View File

@@ -160,7 +160,6 @@ $endif$
font-size: 90%; font-size: 90%;
margin: 0; margin: 0;
hyphens: manual; hyphens: manual;
color: #000000;
} }
pre { pre {
margin: 1em 0; margin: 1em 0;
@@ -180,8 +179,7 @@ pre code {
overflow: visible; overflow: visible;
} }
div.sourceCode { div.sourceCode {
background-color: #f7f7f7; padding: 0.3em 1em;
padding: 0.3em 0;
} }
aside.footnotes { aside.footnotes {
font-size:90%; font-size:90%;