Module:Sharpness documentation

Module documentation[view] [edit] [history] [purge]

This module is used for Template:Sharpness documentation to automate information for sharpness templates (templates that show how many steps sharps or flats raise or lower by).

By default, it handles standard sharps and flats, quarter-tone accidentals, and ups and downs notation.

See also

• Category:Sharpness templates

---

local yesno = require("Module:yesno")
local module = {}

function module.main(frame)
	local in_str = frame.args["input"]
	local note = frame.args["note"] or ""
	local aux_note = frame.args["auxnote"] or ""
	local notation = frame.args["notation"] or ""

	-- 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 out_str = "This template is used "

	if s == 0 then
		-- Sharp-0 EDOs (lower 5 multiples of 7) are redundant, take care of that right away
		out_str = out_str
			.. "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
		out_str = out_str
			.. "for [[edo]]s where a sharp "
			.. ((s < 0) and "lowers" or "raises")
			.. " by "
			.. math.abs(s)
			.. " step"

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

		out_str = out_str .. "."

		if notation == "" then
			out_str = out_str .. " This symbol set "

			if math.abs(s) == 1 then
				out_str = out_str .. "is identical to standard notation."
			else
				if extension == "" then
					if math.abs(s) == 2 then
						-- If a sharp raises by two steps
						out_str = out_str
							.. "comprises sharps, flats, and Stein&ndash;Zimmerman [[24edo #Notation|quartertone]] accidentals."
					else
						-- Otherwise (if a sharp raises by three or more steps)
						out_str = out_str
							.. "is based on [[ups and downs notation]] and comprises sharps, flats, "
							.. (s % 2 == 0 and "naturals, and Stein&ndash;Zimmerman [[24edo #Notation|quartertone]] accidentals " or "and naturals ")
							.. "with arrows from [[Helmholtz&ndash;Ellis notation]]."
					end
				elseif extension == "a" or extension == "A" then
					-- Extension for modern-style ups and downs
					out_str = out_str .. "is based on [[ups and downs notation]] using separate arrows."
				end
			end
		else
			out_str = out_str .. " It is based on " .. notation .. "."
		end

		-- display custom notes
		if note or aux_note then
			out_str = out_str .. " " .. 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

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

		-- Display a "see also" section for sharpness-2 and above
		if s >= 2 or s <= -2 then
			local basic = "Template:Sharpness-" .. typ .. value
			local basic_suf = basic .. "-" .. suffix
			out_str = out_str .. "\n\n<h3>See also</h3>\n"
				.. "* [[Alternative symbols for ups and downs notation]]\n"
			
			if (extension == "a" or extension == "A") then
				-- If the template shows separate arrows
				out_str = out_str
					.. "* [[{{#ifexist: " .. basic_suf .. "|" .. basic_suf .. "|" .. basic .. "}}]] &ndash; "
					.. (s == 2
						and "uses Stein&ndash;Zimmerman quarter tone accidentals."
						or "the classic version of this template that shows arrows attached to standard accidentals.")
			else
				-- If the template shows integrated (HEJI-like) arrows
				out_str = out_str .. "{{#ifexist: " .. basic .. "a|* [[" .. basic .. "a]] &ndash; "
					.. "an alternate version of this template that shows separate arrows.\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)
					out_str = out_str .. "{{#ifexist: ".. basic .. "|* [[" .. basic .. "]] &ndash; "
						.. "the basic version of this template.|}}"
				else
					-- Otherwise, add an additional note for possible extended versions, if they exist
					if s == 3 or s == 5 then
						out_str = out_str .. "{{#ifexist: " .. basic .. "-extended|* [[" .. basic .. "-extended]] &ndash; "
						.. "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
							out_str = out_str .. "double"
						elseif s == 5 then
							-- Sharp-5 EDOs normally need double arrows, and note that sometimes
							-- triple arrows may be needed
							out_str = out_str .. "triple"
						end
						
						out_str = out_str .. " arrows.|}}"
					end
				end
			end
		end
	end

	local is_debug = yesno(frame.args["debug"])
	return frame:preprocess(is_debug == true and "<pre>" .. out_str .. "</pre>" or out_str)
end

return module