*! version 0.8.4 09nov2026 Eric Booth
*! _sm_renderhtml -- render a surveymap journal (TSV, 20 columns) as HTML
*! with one inline SVG flow map.
*!
*! syntax: _sm_renderhtml using journal.tsv, saving(x.html)
*! [name(string) embed noheader replace accent(hex)]
*!
*! Layout is horizontal, left to right: items are columns in position order.
*! An ungated stretch is one row of item boxes on the spine. At a gate the
*! flow fans out into one lane per cat row of the (already pruned) journal --
*! kept categories + other + noanswer -- each lane crossing the gate's
*! segment cell by cell, and the lanes merge at a join point before the next
*! stretch. A cell the lane was routed around draws as a dashed grey ghost
*! box. Width grows with items; the page scrolls sideways (.sm-wrap is
*! overflow-x auto), and lane rows stack vertically, so total height follows
*! the widest gate.
*!
*! Two output shapes:
*! page (default) a self-contained document; the map runs full height
*! embed (option) a FRAGMENT for pasting into a host report: one scoped
*! "' _n
file write `H' `""' _n
file write `H' `"
scope: only respondents where `s(o)' · every count and share on this page describes that group
"' _n
}
file write `H' `"
!! = warning (never colour alone) · !? = the declared routing and the data disagree · dashed box = skipped, routed around by the gate · lanes partition the sample · hover a node for detail
"' _n
* ---- how to read this map, generated with this survey's own names --
local rdir "left to right"
local rd1 "leftmost"
if `vert' {
local rdir "top to bottom"
local rd1 "top"
}
_srh_n `"`na_1'"'
local rn1 `"`s(o)'"'
local gname ""
forvalues p = 1/`K' {
if "`gname'" == "" & "`g_`p''" == "1" local gname `"`v_`p''"'
}
file write `H' `"How to read this map, step by step"' _n
file write `H' `"
Each solid box is one survey item, in questionnaire order, `rdir'. Start at the `rd1' box, `v_1': `rn1' respondents were in scope there, and the count line inside each box says how many answered it and what share of the scope that is.
"' _n
if `HASRESP' {
file write `H' `"
The shaded rows inside a box are that item's most common answers. Each row's bar length is its share of the people the item was put to, so the answer rows, the other answers row and the no answer row account for everyone who saw the question.
"' _n
}
file write `H' `"
Follow the arrow out of a box to the next item the survey asked.
"' _n
if "`gname'" != "" {
file write `H' `"
Where a heading says split by `gname', the sample fans into lanes, one per answer to `gname', each headed by the answer and the number of people in that lane. Inside a lane, a solid box is an item that lane was asked and a dashed grey box is an item the skip logic routed that lane around.
"' _n
file write `H' `"
The lanes rejoin the spine at a small dot, and the single path continues. Lane counts add back to the sample: nobody is lost and nobody is counted twice.
"' _n
}
else {
file write `H' `"
This survey has no branching drawn, so there is a single path. A dashed grey box, if one appears, is an item the skip logic routed respondents around.
"' _n
}
file write `H' `"
!! flags an item that many people declined to answer; !? flags an item where the declared skip logic and the data disagree. Hover any box for its full record, and the table at the bottom of the page repeats every number as text.
"' _n
file write `H' `""' _n
}
file write `H' `"
"' _n
if "`embed'" == "" {
file write `H' `"
"' _n
* ---- the same numbers, as text ------------------------------------
* A screen reader cannot follow a spine, and neither can a reader who
* prints this badly or has the images turned off. The map is drawn from
* a table, so the fallback is that table rather than a sentence about it.
file write `H' `""' _n
file write `H' `"The same map as a table"' _n
file write `H' `"
"' _n
file write `H' `"
Every item in questionnaire order. Answered, declined and not shown add to the `nnf' respondents in scope at every row.
"' _n
file write `H' `"
#
item
answered
declined
not shown
routed by
"' _n
file write `H' `""' _n
forvalues p = 1/`K' {
_srh_n `"`nn_`p''"'
local tnn `"`s(o)'"'
_srh_n `"`nr_`p''"'
local tnr `"`s(o)'"'
if "`tnr'" == "" local tnr "0"
_srh_n `"`ns_`p''"'
local tns `"`s(o)'"'
if "`tns'" == "" local tns "0"
local tgb `"`gb_`p''"'
if `"`tgb'"' == "." | `"`tgb'"' == "" local tgb "—"
local trow "sm-tr"
if "`g_`p''" == "1" local trow "sm-tr sm-trg"
file write `H' `"