DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:codedoc

codedoc Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" yes

plugin 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

Last updated on
2018-04-20
Provides
Syntax
Repository
Source

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Examples/Usage

The codedoc plugin is directed at the display and documentation of blocks of code. The code can be of any type (i.e. language).

  1. 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.
  2. it supports nested code blocks that can be toggled for display and hiding.

Syntax

Basic Models

<codedoc code> 
   . . .your code here. . .
</codedoc>

<codedoc file> 
   . . .your code here. . .
</codedoc>

<codedoc toggle description> 
   . . .your code here. . .
</codedoc>

The first two forms 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.

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, code:java, etc.

<codedoc code:php> 
   . . .your code here. . .
</codedoc>

No Numbers

In the basic formatting, the code blocks are numbered (in square brackets). The numbering can be omitted by using the _no_numbers option:

<codedoc code:php _no_numbers> 
   . . .your code here. . .
</codedoc>

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 five syntax configurations. These are in fact independent of the codedoc containers, i.e. can appear anywhere on a page.

1. Timestamp

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

~~codedoc:timestamp~~

2. User Name

This outputs the current user's name.

~~codedoc:user~~

The timestamp and the user name are independent of the codedoc container and can be placed anywhere in a document.

3. Comment

The second allows for internal comments on the code:

~~codedoc:comment~~             

The comment can contain DokuWiki internal links, for instance:

~~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.

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:

/*  
  comment
**/

Otherwise the comment will have the single line format:

/* 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'.

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
and so would be formatted as a
multi-line comment~~

The result would be:

/*
This comment appears on more than one line
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 creates1). 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

~~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 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 double percent sign syntax:

%%8-)%%

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_hilite { color: blue; }
.codedoc_clean { color: black; }

Illustrations Showing toggled blocks both in closed and open states

Closed

Open

Two line comment

Development

Change Log

Known Bugs and Issues

FAQ

Discussion

1)
DokuWiki creates anchors for each H1-H5 heading
plugin/codedoc.txt · Last modified: 2022-08-13 04:40 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