tweak portal, alphagen portal documentation, completion

docs/shaderManual/general-directives.html

@@ -176,7 +176,21 @@ textures/skies/xtoxicsky_dm9
 </blockquote>
 
 <h2 id="portal">portal</h2>
-<p>Specifies that this texture is the surface for a portal or mirror. In the game map, a portal entity must be placed directly in front of the texture (within 64 game units). All this does is set "sort portal", so it isn't needed if you specify that explicitly.</p>
+<p>Specifies that this shader is the surface for a portal or mirror. In the game map, a portal entity (e.g. "misc_portal_surface") must be placed directly in front of the surface (within 64 game units). All this does is set "sort portal", so it isn't needed if you specify that explicitly.</p>
+<p>Bare bones mirror shader example:</p>
+<pre>
+textures/ztest/mirror
+{
+	qer_editorimage textures/sfx/portalfog.tga
+	surfaceparm nolightmap
+	portal
+	{
+		map textures/sfx/portalfog.tga
+		blendFunc GL_ZERO GL_SRC_ALPHA
+		depthWrite
+	}
+}
+</pre>
 
 <h2 id="sort">sort value</h2>
 <p>Use this keyword to fine-tune the depth sorting of shaders as they are compared against other shaders in the game world. The basic concept is that if there is a question or a problem with shaders drawing in the wrong order against each other, this allows the designer to create a hierarchy of which shader draws in what order.</p>

docs/shaderManual/stage-directives.html

@@ -310,8 +310,29 @@ textures/obsidian_video/intro
 <h3>alphaGen const N.N</h3>
 <p>A constant vertex alpha is assigned to the affected surface. This modifies the transparency of the texture.</p>
 
-<h3>alphaGen portal</h3>
-<p>This rendering stage keyword is used in conjunction with the surface parameter keyword portal. The function accomplishes the "fade" that causes the scene in the portal to fade from view. Specifically, it means "Generate alpha values based on the distance from the viewer to the portal." Use alphaGen portal on the last rendering pass.</p>
+<h3>alphaGen portal <em>distance</em></h3>
+<p>This rendering stage keyword is normally used in conjunction with the surface parameter keyword portal. The function accomplishes the "fade" that causes the scene in the portal/mirror to fade from view. Specifically, it means "Generate alpha values based on the distance from the viewer to the portal". Viewer distance 0 maps to alpha 0, when distance is more than "distance" parameter value, alpha is 1. While latter is the case, portal/mirror content is not rendering at all, this optimization is original purpose of the keyword, though it may be utilized for other distance dependent effects.</p>
+<p>
+Basic fading portal/mirror shader example:
+</p>
+<pre>
+textures/ztest/portal
+{
+	qer_editorimage textures/sfx/portalfog.tga
+	surfaceparm nolightmap
+	portal
+	{
+		map textures/sfx/portalfog.tga
+		blendFunc GL_ZERO GL_SRC_ALPHA
+		depthWrite
+	}
+	{
+		map textures/sfx/portalfog.tga
+		blendfunc GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA
+		alphagen portal 256
+	}
+}
+</pre>
 
 <h2 id="tcGen">tcGen coordinateSource</h2>
 <p>Specifies how texture coordinates are generated and where they come from. Valid functions are base, lightmap, environment and vector.</p>

radiant/gtkdlgs.cpp

@@ -1238,7 +1238,6 @@ static const std::vector<ShaderFormat> g_shaderStageFormats{
 			"oneMinusEntity",
 			"vertex",
 			"oneMinusVertex",
-			"portal",
 		}
 	},
 	{
@@ -1252,7 +1251,10 @@ static const std::vector<ShaderFormat> g_shaderStageFormats{
 		}
 	},
 	{
-		"alphaGen const %f", c_pageStage, c_colorKeyLv2
+		"alphaGen %s %f", c_pageStage, c_colorKeyLv2, {
+			"const",
+			"portal",
+		}
 	},
 	{
 		"tcGen %s", c_pageStage, c_colorKeyLv2, {