WIP improving the docs

docs/designers/language-builtin-functions/language-function-capture.md

@@ -1,5 +1,4 @@
-{capture} {#language.function.capture}
-=========
+# {capture}
 
 `{capture}` is used to collect the output of the template between the
 tags into a variable instead of displaying it. Any content between
@@ -7,69 +6,68 @@ tags into a variable instead of displaying it. Any content between
 specified in the `name` attribute.
 
 The captured content can be used in the template from the variable
-[`$smarty.capture.foo`](#language.variables.smarty.capture) where "foo"
+[`$smarty.capture.foo`](../language-variables/language-variables-smarty.md#smartycapture-languagevariablessmartycapture) where "foo"
 is the value passed in the `name` attribute. If you do not supply the
 `name` attribute, then "default" will be used as the name ie
 `$smarty.capture.default`.
 
 `{capture}'s` can be nested.
 
-**Attributes:**
+## Attributes
 
-   Attribute Name    Type    Required   Default  Description
-  ---------------- -------- ---------- --------- ----------------------------------------------------------------------
-        name        string     Yes       *n/a*   The name of the captured block
-       assign       string      No       *n/a*   The variable name where to assign the captured output to
-       append       string      No       *n/a*   The name of an array variable where to append the captured output to
+| Attribute Name | Required | Description                                                          |
+|----------------|----------|----------------------------------------------------------------------|
+| name           | Yes      | The name of the captured block                                       |
+| assign         | No       | The variable name where to assign the captured output to             |
+| append         | No       | The name of an array variable where to append the captured output to |
 
-**Option Flags:**
+## Option Flags
 
-    Name    Description
-  --------- -----------------------------------------
-   nocache  Disables caching of this captured block
+| Name    | Description                             |
+|---------|-----------------------------------------|
+| nocache | Disables caching of this captured block |
 
 
-    {* we don't want to print a div tag unless content is displayed *}
-    {capture name="banner"}
-    {capture "banner"} {* short-hand *}
-      {include file="get_banner.tpl"}
-    {/capture}
-
-    {if $smarty.capture.banner ne ""}
-    <div id="banner">{$smarty.capture.banner}</div>
-    {/if}
-
-       
+```smarty
+{* we don't want to print a div tag unless content is displayed *}
+{capture name="banner"}
+{capture "banner"} {* short-hand *}
+  {include file="get_banner.tpl"}
+{/capture}
 
+{if $smarty.capture.banner ne ""}
+<div id="banner">{$smarty.capture.banner}</div>
+{/if}
+```
+      
 This example demonstrates the capture function.
+```smarty
 
-
-    {capture name=some_content assign=popText}
-    {capture some_content assign=popText} {* short-hand *}
-    The server is {$my_server_name|upper} at {$my_server_addr}<br>
-    Your ip is {$my_ip}.
-    {/capture}
-    <a href="#">{$popText}</a>
-
+{capture name=some_content assign=popText}
+{capture some_content assign=popText} {* short-hand *}
+The server is {$my_server_name|upper} at {$my_server_addr}<br>
+Your ip is {$my_ip}.
+{/capture}
+<a href="#">{$popText}</a>
+```
          
 
 This example also demonstrates how multiple calls of capture can be used
 to create an array with captured content.
 
-
-    {capture append="foo"}hello{/capture}I say just {capture append="foo"}world{/capture}
-    {foreach $foo as $text}{$text} {/foreach}
-
-         
+```smarty
+{capture append="foo"}hello{/capture}I say just {capture append="foo"}world{/capture}
+{foreach $foo as $text}{$text} {/foreach}
+```
 
 The above example will output:
 
-
-    I say just hello world
-
+```
+I say just hello world
+```
       
 
-See also [`$smarty.capture`](#language.variables.smarty.capture),
-[`{eval}`](#language.function.eval),
-[`{fetch}`](#language.function.fetch), [`fetch()`](#api.fetch) and
-[`{assign}`](#language.function.assign).
+See also [`$smarty.capture`](../language-variables/language-variables-smarty.md#smartycapture-languagevariablessmartycapture),
+[`{eval}`](./language-function-eval.md),
+[`{fetch}`](./language-function-fetch.md), [`fetch()`](../../programmers/api-functions/api-fetch.md) and
+[`{assign}`](./language-function-assign.md).