DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
plugin:codedoc

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
plugin:codedoc [2018-04-19 17:58] – [Installation] turnermmplugin:codedoc [2022-08-13 04:40] (current) – [codedoc Plugin] turnermm
Line 2: Line 2:
  
 ---- plugin ---- ---- plugin ----
-description: Inserts toggles for hiding and displaying code blocks; inserts html anchors for cross-referencing code; facilitates documentation, provides convenience features for marking up code, has branch with support geshi highlighting. +description: Inserts toggles for hiding and displaying code blocks; inserts html anchors for cross-referencing code; facilitates documentation, provides convenience features for marking up code, supports geshi highlighting 
-author     : Myron Turner  +author     : Myron Turner 
-email      : turnermm02@shaw.ca +email      : turnermm02@shaw.ca
 type       : syntax type       : syntax
-lastupdate : 2016-07-31  +lastupdate : 2018-04-20 
-compatible : lemming,anteater,rincewind,angua,adora belle,weatherwax,binky,"ponder stibbons", hrun,detritus,"Elenor Of Tsort"+compatible : Lemming, Anteater, Rincewind, Angua, Adora belle, Weatherwax, Binky, Ponder stibbons, Hrun, Detritus, Elenor Of Tsort, Greebo, Hogfather,IgoR
 depends    :  depends    : 
 conflicts  :  conflicts  : 
Line 21: Line 21:
 ===== Installation ===== ===== Installation =====
  
-Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually. +Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
  
 ===== Examples/Usage ===== ===== Examples/Usage =====
Line 30: Line 29:
   - codedoc creates code blocks, either of file or code types, into which you can embed comments that support HTML markup, including both internal and external links.     - codedoc creates code blocks, either of file or code types, into which you can embed comments that support HTML markup, including both internal and external links.  
   - it supports nested code blocks that can be toggled for display and hiding.      - it supports nested code blocks that can be toggled for display and hiding.   
 +
 ===== Syntax ===== ===== Syntax =====
 +
 ==== Basic Models ==== ==== Basic Models ====
  
Line 71: Line 72:
  
 This nesting of the codedoc containers is limited to one level, that is you can't include a toggle inside another toggle. This nesting of the codedoc containers is limited to one level, that is you can't include a toggle inside another toggle.
 +
 ==== Geshi ==== ==== Geshi ====
-Support for geshi highighting: To initiate the highlighting you must specify the language in the initial tag of the codedoc block, using a colon:  ''code:php'', ''file:java'', etc. + 
 +Support for geshi highighting: To initiate the highlighting you must specify the language in the initial tag of the codedoc block, using a colon:  ''code:php'', ''code:java'', etc. 
 <code> <code>
 <codedoc code:php>  <codedoc code:php> 
Line 78: Line 81:
 </codedoc> </codedoc>
 </code> </code>
 +
 ==== No Numbers ==== ==== No Numbers ====
  
Line 89: Line 93:
  
 ==== Support for Comments ==== ==== Support for Comments ====
-With codedoc you can add HTML formatted commentary to your code; these comments can contain links and therefore allow for cross-referencing.  There are three syntax configurations. These are in fact independent of the codedoc containers, i.e. can appear anywhere on a page.+ 
 +With codedoc you can add HTML formatted commentary to your code; these comments can contain links and therefore allow for cross-referencing.  There are five syntax configurations. These are in fact independent of the codedoc containers, i.e. can appear anywhere on a page.
  
 === 1. Timestamp === === 1. Timestamp ===
Line 95: Line 100:
 The first simply creates a timestamp for the file which contains the documented code: The first simply creates a timestamp for the file which contains the documented code:
  
-   ~~codedoc:timestamp~~+  ~~codedoc:timestamp~~
  
 === 2. User Name === === 2. User Name ===
  
 This outputs the current user's name. This outputs the current user's name.
-    ~~codedoc:user~~ + 
 +  ~~codedoc:user~~
  
 The timestamp and the user name are independent of the codedoc container and can be placed anywhere in a document. The timestamp and the user name are independent of the codedoc container and can be placed anywhere in a document.
Line 109: Line 115:
   ~~codedoc:comment~~                ~~codedoc:comment~~             
  
-The comment can contain Dokuwiki internal links, for instance:+The comment can contain DokuWiki internal links, for instance:
      
-   ~~codedoc:Dokuwiki embeds [[:snippet]] filenames in HTML definition lists [[:definitions#def_1|see definitions]]~~+  ~~codedoc: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, that is to the named anchors which Dokuwiki creates when it formats its H1-H5 headings.+As the above demonstrates, the links can contain references to internal link headings, that is to the named anchors which DokuWiki creates when it formats its H1-H5 headings.
  
-One of the benefits of codedoc is that its comments support HTML markup. Comments will appear on more than one line if you insert HTML line-breaks into the comment or if the comment contains an internal newline.  If the plugin finds an HTML line-break, i.e. <BR /> or <br />, or if the comment is on more than one line, the comment will have the multi-line comment format:+One of the benefits of codedoc is that its comments support HTML markup. Comments will appear on more than one line if you insert HTML line-breaks into the comment or if the comment contains an internal newline.  If the plugin finds an HTML line-break, i.e. ''%%<BR />%%'' or ''%%<br />%%'', or if the comment is on more than one line, the comment will have the multi-line comment format:
  
 <code> <code>
-      /*   +/*   
-         comment +  comment 
-     **/+**/
 </code> </code>
  
 Otherwise the comment will have the single line format:   Otherwise the comment will have the single line format:  
  
-    /* comment */+  /* comment */
  
 In actual fact, the plugin looks only for the opening side of the markup, '<br' or '<BR'.  It will not recognize mixed case, i.e. '<Br' or '<bR'.   In actual fact, the plugin looks only for the opening side of the markup, '<br' or '<BR'.  It will not recognize mixed case, i.e. '<Br' or '<bR'.  
Line 131: Line 137:
 An "internal newline" is a newline that occurs in the comment itself, where the text breaks and moves to a new line: An "internal newline" is a newline that occurs in the comment itself, where the text breaks and moves to a new line:
  
-    ~~codedoc:This comment appears on more than one line +  ~~codedoc:This comment appears on more than one line 
-    and so would be formatted as a +  and so would be formatted as a 
-    multi-line comment~~+  multi-line comment~~
  
 The result would be: The result would be:
-    /* 
-    This comment appears on more than one line 
-    and would be formatted as a 
-    multi-line comment 
-    **/ 
-     
-=== 4. Named Anchor === 
  
-    ~~codedoc:xref:anchor_name~~              +  /* 
-     +  This comment appears on more than one line 
-This will create a named anchor in your page, enabling you to link to places in your code, on the same or other pages, which are not marked by the anchors which Dokuwiki creates((Dowkuwiki creates anchors for each H1-H5 heading)).  This feature is obviously very useful when linking to places inside code blocks which cannot contain header markup and therefore cannot have anchors defined by Dokuwiki headers.+  and would be formatted as a 
 +  multi-line comment 
 +  **/ 
 + 
 +=== 4. Selective Highlighting === 
 + 
 +  ~~codedoc: <em>. . . </em>~~ 
 +  ~~codedoc: <b>. . . </b>~~ 
 + 
 +If the enclosed text contains either an ''<em>''  or a ''<b>'', it is styled as defined in 
 +the plugin's style.css file.  Currently, the colors will be red and the styling 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 css.  This is useful for emphasizing single words or phrases.     
 + 
 +=== 5. Named Anchor === 
 + 
 +  ~~codedoc:xref:anchor_name~~ 
 + 
 +This will create a named anchor in your page, enabling you to link to places in your code, on the same or other pages, which are not marked by the anchors which DokuWiki creates((DokuWiki creates anchors for each H1-H5 heading)).  This feature is obviously very useful when linking to places inside code blocks which cannot contain header markup and therefore cannot have anchors defined by DokuWiki headers.
  
 ==== Literals ==== ==== Literals ====
 +
   ~~codedoc:clean:text~~     ~~codedoc:clean:text~~  
  
-In order to support links in codedoc comments, the codedoc plugin must accept Dokuwiki's substitution 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 +In order to support links in codedoc comments, the codedoc plugin must accept DokuWiki's substitution 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
-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  being substituted for 
-         8-) + 
 +  8-)  
 you would enter the following: you would enter the following:
-     ~~codedoc:clean:8-)~~ + 
-This is the equivalent of Dokuwiki's double percent sign syntax:  +  ~~codedoc:clean:8-)~~ 
-    %%8-)%%+ 
 +This is the equivalent of DokuWiki's double percent sign syntax:  
 + 
 +  %%8-)%%
  
 ==== CSS Styles ==== ==== CSS Styles ====
 +
 codedoc higlights its comments in blue and outputs its literals in black.  These can be changed in the style.css file, which contains the following styles: codedoc higlights its comments in blue and outputs its literals in black.  These can be changed in the style.css file, which contains the following styles:
  
-   .codedoc_hilite { color: blue; } +  .codedoc_hilite { color: blue; } 
-   .codedoc_clean { color: black; } +  .codedoc_clean { color: black; }
- +
-   +
  
 ==== Illustrations Showing toggled blocks both in closed and open states==== ==== Illustrations Showing toggled blocks both in closed and open states====
 +
 == Closed == == Closed ==
  
-{{  http://www.mturner.org/userfiles/codedoc_closed.png  }}+{{ http://www.mturner.org/userfiles/codedoc_closed.png }}
  
 == Open == == Open ==
  
-{{  http://www.mturner.org/userfiles/codedoc_open_2.png  }}+{{ http://www.mturner.org/userfiles/codedoc_open_2.png }}
  
 == Two line comment == == Two line comment ==
  
-{{  http://www.mturner.org/userfiles/codedoc_comment.png  }}+{{ http://www.mturner.org/userfiles/codedoc_comment.png }} 
 ===== Development ===== ===== Development =====
  
  
 === Change Log === === Change Log ===
 +
 {{rss>https://github.com/turnermm/codedoc/commits/master.atom date count=12}} {{rss>https://github.com/turnermm/codedoc/commits/master.atom date count=12}}
  
plugin/codedoc.1524153510.txt.gz · Last modified: 2018-04-19 17:58 by turnermm
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Global DokuWiki Links