Template:Interwiki doc page pattern

Snippet heading from {{Interwiki doc page pattern}}:
This {{interwiki doc page pattern}} template does nothing but display useful information until substituted in an templatename/doc type of usage and documentation page.

The substituted template forms a boilerplate for building a Doc page pattern usage page, doing all the heavy typing, including the proper templates in the proper places, and embedding reminders and messages for you to put in the key ingredient: The text prose and examples to make the working template(s) purpose and "how-to" clear and comprehensible to the newest of new editors, and the jaded old wikipedian needing a refresher prompt or two. You'll find that is a challenge, like any good writing.

• This 'interwiki doc page pattern' page will however be non-functional immediately after substitution, which is of necessity, the initial save of the new page. It is broken such that it will show deliberately broken preprocessor commands in block forming pairs (after subst'ing) -- all involve the partial (broken) command word "in clude" (note the added space) -- these are deliberate breakings of those wikimarkup language keywords to ensure this whole boilerplate template will be subst'ed. Fix these after substing this page in it's destination and delete this heading, as well as the how-to guiding imbedded comments below.
  

• Define the parameter 'SUBST=subst:' , for common usage pages for several related templates. This can be done for a /doc page for a single template as well.
  
     The syntax is precisely this:
  {{subst:interwiki doc page pattern|SUBST=subst:}}
  

• If the common usage page is not a PAGENAME/doc page, the edit link will need a slight fixup-- the "/doc" part will need deleted.
  
  

• This line and the balance of the usage text below is not subst'd, that which is currently hidden is subst'ed, including the boxed area above. When the usage page looks right, delete that too!

---

This {{interwiki doc page pattern}} template does nothing useful but display information on how to use it until it is substituted in an templatename/doc page or alternatively a group (usage) documentation page setup for several utility templates with related capabilities.

If you are weak on template knowledge, please refer to M:Help:template and familiarize yourself with the terms and meanings of 'includeonly' and noinclude at this time.

Use is as follows

1. Understand you are building a M:DPP type page which is meant to be included by a template to provide it with documentation notations and interwiki's. There are several good reasons for doing this, not the least of which is protecting the servers from unnecessary updates and a site's content from vandalism. There are processing efficiencies involved, particularly when a template is used a lot on the same page such as site discussion pages.
   
      
2. Hence the important thing to understand is the frame of reference--the page you are building will be displayed but not executed. It will be walled off behind a noinclude block, which provides the benefits mentioned above to the system, but the page you are building can therefore be elaborate enough to provide clear instructions to the layperson or novice, or totally inept never used a template before in their lives, new editor.
   
      
3. In the following, "Cut buffer" means the same as the Microsoft Windows "Clipboard", usually accessed via [[CTRL—C] (copy), [[CTRL—X] (cut), [[CTRL—V] (paste), and the odd occasional [[CTRL—A] (select all) or in conjunction with mouse drag and highlight operations. (MacIntosh people use the 'Apple Key' (Command) instead of [CTRL].

The process

1. Open the documentation page usage pagename.
   
      
2. subst this template and save the new usage page.
   
      
3. edit the new page, pasting in the usage from the cut buffer, transferring from the usage in the old depreciated talk page method, or writing from scratch, etcetera.
   1. It is quite easy to cut out usage from a template page, create the link inside a noinclude block to the usage (or /doc) page, preview, then edit the redlink usage page just referenced in the working template.
   2. Click the redlink to begin editing the newly created page.
   3. Start that by subst'ing this page: {{subst:interwiki doc page pattern}}, save, edit the page, then park your cut buffer by pasting it in the labeled section.
      
         
4. That leaves some quick fixups:
   1. there will be broken links where the preprocessor commands 'includeonly' and 'noinclude' have been deliberately 'broken' by introducing a single space. These can be easily searched for and fixed 'later' searching for 'clude' in your browser or text editor.
   2. Without repairing them at this time, familiarize yourself with the module's (page's) alternating between including and not including certain sections.
   3. There are several embedded inline commented out sections of code and instructions.
   4. Unlike this header section of instructions, those things behind broken 'cludes' came along to your new page when you subst'd. This, behind the wall of a noinclude, did not get included. Simple, eh! Your documentation page will use the same technique.
      
         
5. Those things that are within includeonly blocks, are data for the pages which call the current page, they will be seen by the 'working template' when the documentation is saved, and by people viewing the working template page. So these blocks hold:
   1. Category declarations for the working (or calling) template(s).
   2. Purpose statements describing the calling template(s) job.
   3. Instructions on the templates 'Named parameters', arguments ('Numbered parameters') and their interplay and effects on the templates operation. (See: M:Help:template#parameters at need).
   4. An usage example or two, three or five.
   5. Possibly a list of similar templates in a 'see also' sub-section.
      
         
6. Those lines which are NOT included are data for the '/doc type' documentation page you are building and might include notations that the page is for multiple templates, where to put interwiki's for the doc type page, and any categories that apply to the documentation page alone such as category:template documentation.
   
      
7. Comments are comments. Some are instructions, some are so you need only type a minimal amount, all must nest with a begin and end comment 'arrow point' in the right places. Many are present to space out key words for us humans, and template (any text stream) preprocessing flows so quickly that performance is not an issue with these behind the noinclude wall in the working template. These only evince if the page is viewed, so comments and the extra vertical space are desired to ease maintenance loads on humans going forward.
   1. Mostly, what's present in the boiler plate can be left alone.
   2. Some disable things like category declarations which will need you to adjust the comment block ends and beginnings in the appropriate way. .. including just deleting that which doesn't apply.
      
         
8. Each area of the boilerplate might have instructions to a person viewing the page in edit mode: (the documentation to be reproduced on the working template page, is for view of the template user, and the notes inside noinclude blocks for others maintaining the 'doc' or 'usage' page, including those notes inside inline comment blocks.
   
      
9. Both kinds of 'include' blocks may have declarations of categories and that for the working template will possibly have internal or interwiki links, list other templates, etcetera.
   1. Mostly, using the boilerplate involves deleting things, spaces, and the majority of the inline comments serving as set-up instructions, as well as the occasional insertion of material, within well labeled regions (see below excerpt).
   2. Many inline comments should be left in place as well. The nature of the comments within will guide that decision cycle for each.
           • The one's like those simulated below can and should just be left alone.
           • Many common category names are provided within a comment block, and that should be altered to satisfy the need. And so forth.
      
         
10. Essentially, once you have verified the page is being creating the correct url for maintenance of the /doc style usage page in the top section, save for the difficult task of writing clear usage for the lay editor, the most important edit is in place.
    
       
    1. If the page is usage for several templates, those 'PAGENAME' values in the top section must be subst'ed.
    2. If it is a single templates /doc page, no further action need be taken.
    3. Just fix up the broken 'in cludes' by deleting the space, and move on to groom the next section. And so forth.
       
          
11. Most of your time will therefore be spent tweaking the presentation of your usage for the reader, not worrying about the logic of the page. All of that editing takes place in a single section of the page.
    
       
12. If you started the page by previewing from the working template, when you save the '/doc' page, backspace until you can preview that again. .. verify the display, test the edit link, fix what you need to tweak, then save your new /doc page pattern equipped template.
    
       
13. Once you've done one or two with this template, you'll find it easy and convenient and that most all your time is spent on polishing the text of your usage.
    
       
14. Money back— guaranteed!

---

   

<!--- ------------------------------------------------------------------- -----
----- EDIT the /doc (or THIS usage page only) Interwiki's BELOW THIS LINE -----
----- ------------------------------------------------------------------- -----
---->

   

    <!--- ------------------------------------------------------ -----
---- Self declarations, this page, not the parent template. -----
----- ------------------------------------------------------ -----
----> [[Category:Template documentation|{{PAGENAME}}]] ...

   15.  So simple, even a gecko Cave-critter can do it! (Ask any Neanderthal!)

(If this joke has no basis for you, suffice it to say you haven't seen a series of 'all too frequently aired' Cable Television advertisements in the United States lately!)

---