Module:Sharpness szg documentation

This module should not be invoked directly; use its corresponding template instead: Template:Sharpness szg documentation.

This template automatically fills documentation for sharpness templates using Stein–Zimmermann–Gould notation, which show how many steps a sharp raises by in a given tuning along with any microtonal accidentals needed in the case of edos where sharps raise (or lower) by multiple steps.

---

local p = {}

local yesno = require("Module:Yesno")

function p.main(frame)
	local in_str = string.sub(frame.args["input"],1,-5) -- trim off "-szg"
	local note = frame.args["note"] or ""
	local aux_note = frame.args["auxnote"] or ""
	local notation = frame.args["notation"] or ""
	local debugg = yesno(frame.args["debug"])

	-- typ: "sharp" or "flat"
	-- value: Absolute value of sharpness (the "n" as in sharp-n and flat-n)
	-- extension: Used for identifying alternative symbol set
	local typ, value, extension, suffix = string.lower(in_str):match("%-(%a*)(%d+)(%a*)-?(%a*)")

	-- Signed sharpness
	local s = tonumber(value)
	if typ == "flat" then
		s = -s
	end

	if extension == nil then
		extension = ""
	end

	local result = "This template is used "

	if s == 0 then
		-- Sharp-0 EDOs (lower 5 multiples of 7) are redundant, take care of that right away
		result = result
			.. "for {{EDOs| 7, 14, 21, 28, and 35 }} [[equal divisions of the octave]]. "
			.. "Since these tunings temper out the 3-limit augmented unison ([[2187/2048]], known as the Pythagorean apotome), "
			.. "going up seven fifths brings one back to the root note, and as such "
			.. "the traditional sharps and flats are redundant and cannot raise or lower the pitch."
	else
		-- Otherwise
		result = result
			.. "for [[edo]]s where a sharp "
			.. ((s < 0) and "lowers" or "raises")
			.. " by "
			.. math.abs(s)
			.. " step"

		if math.abs(s) ~= 1 then
			result = result .. "s"
		end

		result = result .. "."
	end
	
	if notation == "" then
		result = result .. "<br>This symbol set "

		if math.abs(s) == 1 then
			result = result .. "is identical to standard notation."
		else
			if extension == "" then
				if math.abs(s) == 2 then
					-- If a sharp raises by two steps
					result = result
						.. "comprises sharps, flats, and Stein&ndash;Zimmermann [[24edo #Notation|quartertone]] accidentals."
				else
					if s == 0 then
						result = result
							.. "is based on [[ups and downs notation]] and comprises naturals "
							.. "with arrows from [https://w3c-cg.github.io/smufl/latest/tables/gould-arrow-quartertone-accidentals-24-edo.html Gould notation]."
					else
						-- Otherwise (if a sharp raises by three or more steps)
						result = result
							.. "is based on [[ups and downs notation]] and comprises sharps, flats, "
							.. (s % 2 == 0 and "naturals, and Stein&ndash;Zimmermann [[24edo #Notation|quartertone]] accidentals " or "and naturals ")
							.. "with arrows from [https://w3c-cg.github.io/smufl/latest/tables/gould-arrow-quartertone-accidentals-24-edo.html Gould notation]."
					end
				end
			elseif extension == "a" or extension == "A" then
				-- Extension for modern-style ups and downs
				result = result .. "is based on [[ups and downs notation]] using separate up and down chevrons."
			end
		end
	else
		result = result .. string.format(" It is based on %s.", notation)
	end

	-- display custom notes
	if note or aux_note then
		result = result .. " " .. note ..(aux_note ~= "" and "\n\n" .. aux_note or "")
	end

	-- Display the note about supersets of 12edo for sharpness-1 and above and set the edo number for supersets of 12edo
	if s >= 1 then
		local n_edo = s * 12

		result = result
			.. "\n\n<h3>Parameters</h3>\n"
			.. string.format("Passing in <code>%d</code> as a single unnamed parameter will change "
			.. "'''Step offset''' to '''Semitones''' in the case of [[%dedo]]", n_edo, n_edo)
		if s >= 2 then
			result = result .. string.format(", since %dedo is a superset of [[12edo]]", n_edo)
		end
		result = result .. "."
	end

	-- Display a "see also" section for sharpness-2 and above, and sharpness-0
	if s >= 2 or s <= -2 or s == 0 then
		local basic = "Template:Sharpness-" .. typ .. value
		local basic_suf = basic .. "-" .. suffix
		result = result .. "\n\n<h3>See also</h3>\n"
			.. "* [[Stein&ndash;Zimmermann&ndash;Gould notation]]\n"
		
		if (extension == "a" or extension == "A") then
			-- If the template shows separate up and down chevrons
			result = result
				.. string.format("* [[{{#ifexist: %s|%s|%s}}]] &ndash; ", basic_suf, basic_suf.."-szg", basic.."-szg")
				.. (s == 2
					and "uses Stein&ndash;Zimmermann quarter tone accidentals."
					or "the classic version of this template that shows arrows attached to standard accidentals.")
		else
			-- If the template shows integrated (Gould-like) arrows
			result = result .. string.format("{{#ifexist: %sa|* [[%s]] &ndash; ", basic, basic.."a-szg")
				.. "an alternate version of this template that shows separate up and down chevrons.\n|}}"
			
			if string.lower(suffix) ~= "" then
				-- If we are on a different version of a template (e.g. "extended" ones that show more arrows than the minimum)
				result = result .. string.format("{{#ifexist: %s|* [[%s]] &ndash; ", basic, basic.."-szg")
					.. "the basic version of this template.|}}"
			else
				-- Otherwise, add an additional note for possible extended versions, if they exist
				if s % 2 == 1 and s >= 3 then
					result = result .. string.format("{{#ifexist: %s-extended|* [[%s]] &ndash; ", basic, basic.."-extended-szg")
					.. "an alternate version of this template that includes "
				
					if s == 3 then
						-- Sharp-3 EDOs normally only need single arrows, but note that 
						-- sometimes double arrows may be needed
						result = result .. "double"
					elseif s == 5 then
						-- Sharp-5 EDOs normally need double arrows, and note that sometimes
						-- triple arrows may be needed
						result = result .. "triple"
					end
					
					result = result .. " arrows.|}}"
				end
			end
		end
	end

	-- Debugger option
	if debugg == true then
		result = "<syntaxhighlight lang=\"wikitext\">" .. result .. "</syntaxhighlight>"
	end
	
	return frame:preprocess(result)
end

return p