mirror of
https://git.code.sf.net/p/zint/code
synced 2025-12-17 18:07:02 +00:00
manual: use modified "haddock.theme" for nicer syntax highlighting;
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
@@ -9,6 +9,7 @@ SOURCE = manual.pmd
|
||||
OUT_PDF = manual.pdf
|
||||
OUT_TXT = manual.txt
|
||||
OUT_HTML = manual.html
|
||||
HIGHLIGHT_THEME = haddock.theme
|
||||
INC_HEADER_PDF = inc_header_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)
|
||||
@@ -17,7 +18,7 @@ INC_TXT = --include-in-header $(INCLUDES_TXT)
|
||||
SOURCE_MAN_PAGE = zint.1.pmd
|
||||
OUT_MAN_PAGE = zint.1
|
||||
LUA_FILTER = lua-crossrefs/lua-crossrefs.lua
|
||||
INFRASTRUCTURE = Makefile $(LUA_FILTER)
|
||||
INFRASTRUCTURE = Makefile $(LUA_FILTER) $(HIGHLIGHT_THEME)
|
||||
IMAGES = \
|
||||
images/zint.png \
|
||||
images/zint-qt.png \
|
||||
@@ -152,7 +153,7 @@ MONO_FONT = monofont="Liberation Mono"
|
||||
CJK_FONT = CJKmainfont="WenQuanYi Micro Hei Mono"
|
||||
PDF_OPTS = --pdf-engine=xelatex \
|
||||
--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
|
||||
TEX_MAN_PAGE = zint.1.tex
|
||||
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_OPTS = --lua-filter=$(LUA_FILTER) \
|
||||
--syntax-highlighting=haddock \
|
||||
--syntax-highlighting=$(HIGHLIGHT_THEME) \
|
||||
--template=templates/default.html --eol=lf -s -t html
|
||||
INC_BEFORE_BODY_HTML = inc_before_body_html.html
|
||||
INC_HTML = --include-before-body $(INC_BEFORE_BODY_HTML)
|
||||
|
||||
197
docs/haddock.theme
Normal file
197
docs/haddock.theme
Normal 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
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -18,18 +18,16 @@
|
||||
\ifx\tmp\@nnil\originalitem\else\originalitem[#1]\hfill\par\fi}
|
||||
\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}
|
||||
\definecolor{icfg}{HTML}{331a33}
|
||||
\definecolor{icfg}{HTML}{351c35} % "text-color" in modified "haddock.theme"
|
||||
\let\oldtexttt\texttt
|
||||
\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
|
||||
%% 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)
|
||||
\usepackage{hyperref}
|
||||
|
||||
%% pandoc-lua-crossrefs: required package
|
||||
%% Reduce gap after figures
|
||||
\usepackage{caption}
|
||||
\captionsetup[figure]{belowskip=-6pt}
|
||||
|
||||
%% Make footnotes go to bottom of page
|
||||
\usepackage[bottom]{footmisc}
|
||||
|
||||
13
docs/lua-crossrefs/.luacheckrc
Normal file
13
docs/lua-crossrefs/.luacheckrc
Normal file
@@ -0,0 +1,13 @@
|
||||
stds.pandoc = {
|
||||
read_globals = {
|
||||
'FORMAT',
|
||||
'pandoc',
|
||||
'PANDOC_VERSION',
|
||||
},
|
||||
|
||||
globals = {
|
||||
'Pandoc',
|
||||
},
|
||||
}
|
||||
|
||||
std = 'lua54+pandoc'
|
||||
@@ -5,12 +5,14 @@
|
||||
-- © 2025 R. N. West. Released under the GPL version 2 or greater.
|
||||
-- SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
PANDOC_VERSION:must_be_at_least '3.8.2'
|
||||
|
||||
-- Hacked from "pandoc-lua-crossrefs/init.lua"
|
||||
|
||||
-- Table of Ids and corresponding cross-referenceable elements. To be populated
|
||||
-- by various element numbering functions.
|
||||
---@type table<string, {type: ('fig'|'tbl'), number: string, caption: string}>
|
||||
IDs = {}
|
||||
local IDs = {}
|
||||
|
||||
-- Hacked from "pandoc-lua-crossrefs/lib/crossrefs.lua"
|
||||
|
||||
@@ -26,8 +28,8 @@ end
|
||||
---@param str Str
|
||||
---@return Inline[] | nil
|
||||
local _parse_crossref = function(str)
|
||||
local opening_bracket, prefix_suppressor, id, closing_bracket1, punctuation, closing_bracket2 =
|
||||
str.text:match('^(%[?)(%-?)#([%a%d-_:%.]-)(%]?)([\\%.!:?,;)]-)(%]?)$')
|
||||
local opening_paren, opening_bracket, prefix_suppressor, id, closing_bracket1, punctuation, closing_bracket2 =
|
||||
str.text:match('^(%(?)(%[?)(%-?)#([%a%d-_:%.]-)(%]?)([\\%.!:?,;)]-)(%]?)$')
|
||||
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]+$')
|
||||
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
|
||||
local elts = pandoc.List { crossref }
|
||||
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 punctuation ~= '' then elts:insert(pandoc.Str(punctuation)) end
|
||||
if closing_bracket2 == ']' then elts:insert(pandoc.Str(']')) end
|
||||
|
||||
1580
docs/manual.html
1580
docs/manual.html
File diff suppressed because it is too large
Load Diff
832
docs/manual.pmd
832
docs/manual.pmd
File diff suppressed because it is too large
Load Diff
796
docs/manual.txt
796
docs/manual.txt
File diff suppressed because it is too large
Load Diff
4
docs/templates/styles.html
vendored
4
docs/templates/styles.html
vendored
@@ -160,7 +160,6 @@ $endif$
|
||||
font-size: 90%;
|
||||
margin: 0;
|
||||
hyphens: manual;
|
||||
color: #000000;
|
||||
}
|
||||
pre {
|
||||
margin: 1em 0;
|
||||
@@ -180,8 +179,7 @@ pre code {
|
||||
overflow: visible;
|
||||
}
|
||||
div.sourceCode {
|
||||
background-color: #f7f7f7;
|
||||
padding: 0.3em 0;
|
||||
padding: 0.3em 1em;
|
||||
}
|
||||
aside.footnotes {
|
||||
font-size:90%;
|
||||
|
||||
Reference in New Issue
Block a user