azurecloudmonk / codedoc Goto Github PK

The codedoc plugin is directed at the display of large blocks of code.  Its basic syntax is:
<codedoc code> 
</codedoc>

<codedoc file> 
</codedoc>

<codedoc toggle description> 
</codedoc>

The first two create code blocks of the type specified by the parameter -- code or file.

The third creates an initially hidden code block which comes with a toggle button
enabling the block to be opened and closed (i.e.displayed and hidden).  The description,
which is a text string, describes the content of this block.

So, a more complete syntax model would be:
<codedoc code> 
 <codedoc toggle description> 
 </codedoc>
 <codedoc toggle description> 
 </codedoc>
</codedoc>

<codedoc file> 
 <codedoc toggle description> 
 </codedoc>
 <codedoc toggle description> 
 </codedoc>
</codedoc>

This nesting of the codedoc containers is limited to one level, that is you can't include a
toggle inside another toggle.

COMMENTS
There are three forms that support comments. 
      ~~codedoc:timestamp~~
      ~~codedoc:comment~~             
      ~~codedoc:xref:anchor_name~~  

1. The first simply creates a timestamp for the file which contains the documented code:

2. The second allows for internal comments on the code. The comment can contain Dokuwiki
internal links, for instance:

   Dokuwiki embeds [[:snippet]] filenames in HTML definition lists [[:definitions#def_1|see definitions]]

As the above demonstrates, the links can contain references to internal link headings. Wherever
Dokiwiki creates a heading, it creates a named anchor. So this:

     ===== This is a Heading ===== 

creates the following anchor:

    <a name="this_is_a_heading" id="this_is_a_heading">This is a Heading</a>

If the comment contains a <br /> character or takes up more than one line, the comment
will have the coment characters on separate lines as in:

/*
  comment
**/
Otherwise the comment appears on one line:  /* comment */

If the comment contains either and <em>  or a <b>, it will get highlighted coding as defined in
the plugin's style.css file.  Currently, the colors will be red and the styling as either bold or
italic.  The color can be anything you choose by making the change in style.css.  The style.css
file also has the option to treat either the em or the b as normal text, by uncommenting
the relevant element.  Useful for emphasizing single words or phrases inside a comment.


3. The third creates named anchors which enable you to link to places on a page where there 
are no Dokuwiki headings:
     <a name="anchor_name">&nbsp;</a>

LITERALS

   ~~codedoc:clean:text~~  

In order to support links in codedoc comments, the codedoc plugin must accept Dokuwiki's 
subtitution modes.  Most of these are the various types of links that Dokuwiki supports;
in addition they include smileys, linebreaks (\\), acronyms and entities.  If any of these
are included in a codedoc code block, Dokuwiki will make the appropriate substitution.  In
order to prevent substitutions where you want the literal text to remain in place,
the codedoc plugin uses its clean text syntax.  For instance, to prevent a smiley from
being substituted for 
         8-) 
you would enter the following:
     ~~codedoc:clean:8-)~~
This is the equivalent of Dokuwiki's %%8-)%% syntax.