candk 2.3.0

Simple text parsing and markup for language-independent source code documentation

• Corndog + Ketchup v2.3.0
• Charles Koch - August 9, 2024

Overview

---

Corndog with Ketchup is a combination of tools that allows quick and simple creation of source code documentation.

Corndog

A plain text extraction tool. Corndog uses a special "corndog" marker ( -==) in text and source code files to extract sections of text and output them to a console or file.

Corndog can parse the following file formats:

Type	File Extension	Type	File Extension
Plain text	.txt	XML	.xml
Python	.py	HTML	.html
Java	.java	CSS	.css
SQL	.sql	PHP	.php
C/C++	.c/ .cpp	JavaScript	.js
TaskBuilder	.tas	FreeMarker	.ftl
Properties	.properties	Bash shell script	.sh
Ketchup	.kp	Windows Batch file	.bat

Usage

To capture text from a file, place a "corndog" marker ( -==) in front of the text you wish to capture. Corndog will capture all text after the -==symbol until it hits a newline or another -==symbol.

To preserve leading whitespace, use a double forward slash ( //) in front of the whitespace you want to keep. By default, Corndog will remove all leading whitespace.

Corndog can be run from a command line with the following command:

corndog -hfrm -s <start_point> -n <output_name> -x <output_extension> -o <output_directory>

Option	Description
-h	Display the help text.
-f	Output to a single file. Use with the -nand -xoptions to set a name and file extension for the output file.
-r	Recursive search. If the start_pointprovided by the -soption is a directory, a recursive search will also search each subdirectory.
-m	Output to multiple files, with each file corresponding to a source file. The files are named the same as the source file with the subfolders prepended by hyphens (-) and the extension .txt. The names cannot be set with the -noption, but the extension can be changed with the -xoption.
-s	The starting point of the search. If the start_pointprovided is a file, Corndog will only parse that single file. If the strat_pointis a directory, it will parse every file in the directory. Use with the -roption to make the search recursive.
-n	The name of the resulting parsed file. This option is only relevant if the -foption is used.
-x	The file extension for the resulting file(s). This option is only relevant if the -for -moption is used.
-o	The directory to place the resulting output file(s). This option is only relevant if the -for -moption is used.

Ketchup

A special markup language designed for documenting code. It includes many specialized tags, as well as some wiki-like markup.

Ketchup can read any text-based file, but the convention is to use the .kpfile extension for files that contain Ketchup tags.

Usage

Ketchup can be run from a command line with the following command:

ketchup  <filepath> -hmNw -p <page_name> -n <output_name> -o <output_directory> -c <css_file>

Option	Description
-h	Display the help text.
-p	The name of the rendered HTML page. If the name has periods, the page title will be only the right-most portion, but the full .page_namewill display on the HTML page itself.
-n	The name of the rendered HTML file.
-o	The directory to place the rendered HTML file.
-c	Replaces the default CSS with the stylesheet specified.
-N	Makes h1 headers in navigation collapsible; for exceptionally large documents.
-m	Export to Markdown ( .md) rather than HTML ( .html)
-w	Automatically run Ketchup rendering whenever changes are detected in the file.

Using Corndog with Ketchup

---

You can use Corndog with Ketchup with the following command

candk -hfrmN -s <start_point> -n <output_name> -o <output_directory> -c <css_file>

NOTE: This command gives you file options for the Corndog parsing, but it does not give you any file options for Ketchup. It will do its file naming and titling based on the name of the source files.

Option	Description
-h	Display the help text.
-f	Output to a single file. Use with the -nand -xoptions to set a name and file extension for the output file.
-r	Recursive search. If the start_pointprovided by the -soption is a directory, a recursive search will also search each subdirectory.
-m	Output to multiple files, with each file corresponding to a source file. The files are named the same as the source file with the subfolders prepended by hyphens (-) and the extension .txt. The names cannot be set with the -noption, but the extension can be changed with the -xoption.
-s	The starting point of the search. If the start_pointprovided is a file, Corndog will only parse that single file. If the strat_pointis a directory, it will parse every file in the directory. Use with the -roption to make the search recursive.
-n	The name of the resulting parsed file. This option is only relevant if the -foption is used.
-x	The file extension for the resulting file(s). This option is only relevant if the -for -moption is used.
-o	The directory to place the resulting output file(s). This option is only relevant if the -for -moption is used.
-M	Export to Markdown ( .md) rather than HTML ( .html)
-c	Replaces the default CSS with the stylesheet specified.
-N	Makes h1 headers in navigation collapsible; for exceptionally large documents.

Ketchup Markup Guide

---

Ketchup can read any text-based file, but the convention is to use the .kpfile extension for files that contain Ketchup tags.

Ketchup generally reads a file top-to-bottom, and splits the file into sections. A new section is marked by an empty line or a tag, which always starts with an "at" symbol ( @). Ketchup does not preserve whitespace (multiple spaces, newlines, and tabs) unless a tag is specifically made to do so. There are 3 types of markup in Ketchup: inline, frontline, and tags.

One key difference from other markup languages is that Ketchup tags cannot be nested. You cannot put a @tabletag inside a @returntag. You can, however, nest inline markup inside other inline markup or in frontline markup as well as certain tags.

Inline Markup

Inline markup is markup that can occur anywhere in a line of text, even within some tags.

\ (backslash)

The backslash will let you escape any character that would normally be used by Ketchup for inline or frontline markup.

Markup:

Email: charles\@cerrax.com

Render:

Email: [e-mail]

@ (line break)

The line break lets you insert a newline in a tag that normally wouldn't let you have one.

Markup:

I like this place@
@
But I don't@
want to
be here anymore.@
Good-bye!

Render:

I like this place

But I don't
want to be here anymore.
Good-bye!

/ (code)

Very often when documenting source code, you'll want to reference a variable name or a method. To make these references stand out and avoid confusion when the name is a very common word, use the forward slash (known as the code markup) to mak the word directly following it styled in a monospace font that is similar to how most IDE's display source code.

NOTE: Other inline markups (bold, italic, codeline, and line break) will not be applied to the word styled by this markup.

Markup:

When testing this method, set the /startTime value to 0 for best results.

Render:

When testing this method, set the startTimevalue to 0 for best results.

/- -/ (codeline)

When documenting code, it may be useful to provide short snippets of code. Whereas the forward slash provides a single word with the appropriate styling, the codeline markup provides a way to mark a whole string as a code segment.

NOTE: Other inline markups (bold, italic, code, and line break) will not be applied to the word styled by this markup.

Markup:

The function will exit the loop prematurely if /-num_parkas/1.2 <= 3-/ and you initialize the rainstorm.

Render:

The function will exit the loop prematurely if num_parkas/1.2 <= 3 and you initialize the rainstorm.

! (hyperlink)

When you need to provide a link, use an exclamation mark (!) at teh bgeinning of the link to make it clickable.

NOTE: Other inline markups (bold, italic, code/codeline, and line break) will not be applied to the word styled by this markup.

Markup:

Follow the yellow brick road: !http://www.cerrax.com

Render:

Follow the yellow brick road: http://www.cerrax.comhttp://www.cerrax.com

*bold*

To mark a string as bolded style, place asterisks on either side. Make sure there isn't any space between the asterisk and the first character, or the styling will not take effect.

Markup:

"You don't understand!" he cried, "You *really* won't like me when I'm angry..."

Render:

"You don't understand!" he cried, "You really won't like me when I'm angry..."

_italics_

To mark a string as italic style, place a single underscore on either side. Make sure there isn't any space between the underscore and the first character, or the styling will not take effect.

Markup:

"Miss, don't be alarmed, but the call is coming _from inside the house._" the police officer said.

Render:

"Miss, don't be alarmed, but the call is coming from inside the house." the police officer said.

Frontline Markup

Frontline markup is markup that only applies if it is the first mark on a line. Frontline markup can contain inline markup, but it cannot contain tags or other frontline markup.

- (unbulleted list)

To make a list that has no bullet points next to the list items, place hyphens with a space after to create a list. The more hyphens you add, the deeper the list (to a maximum of 4).

Markup:

- This is a list
- *It has items* in it. Some items
    Are more fun than others
    But it's all in good fun.
-- This is a _deeper list_
--- Even /deeper still. Pretty neat huh?
    It is a marvelous world
- Now /-we're back to the first-/ level
--- And we can jump to the third!

Render:

• This is a list
• It has items in it. Some items Are more fun than others But it's all in good fun.
  • This is a deeper list
    • Even deeperstill. Pretty neat huh? It is a marvelous world
• Now we're back to the first level
  • And we can jump to the third!

* (bulleted list)

To make a list with bullet points, place asterisks with a space after to create a list. The more asterisks you add, the deeper the list (to a maximum of 4).

Markup:

* This is a bulleted list!
** See how deep it gets!
*** Yowza!
**** Level four

Render:

• This is a bulleted list!
  • See how deep it gets!
    • Yowza!
      • Level four

# (numbered list)

To make an ordered list, place hash marks with a space after to create a list. The more hash marks you add, the deeper the list (to a maximum of 4).

Markup:

# Numbered list
# See it counting up?
## Second level
### How deep does
    the rabbot hole go?
#### Pretty deep actually
## Wow
# Pretty cool

Render:

1 Numbered list 1 See it counting up? 1 Second level 1 How deep does the rabbot hole go? 1 Pretty deep actually 1 Wow 1 Pretty cool

Tags

Every tag in Ketchup is marked with an "at" symbol ( @). Tags must be on their own line. Each line after the tag is considered part of that tag. Once an empty line or another tag is encountered, the tag will close.

NOTE: Ketchup cannot nest tags and tags cannot contain frontline markup. However, tags can contain inline markup.

@page

By default, Ketchup uses the source filepath as the page name. The filename is used for the HTML <title>tag and the full filepath is the title displayed on the page.

Markup:

@page
directory.another_dir.module

Render:

The page will render with module as the name displayed in the tab of the browser and directory.another_dir.module in the black title bar across the top of the page. This is a single-line tag, meaning that multiple lines will be concatenated into a single line.

@file

Defines the filename that this document should have.

NOTE: Only valid file names will work. Invalid file names will cause Ketchup to throw an exception.

Markup:

@file
Output-File-name

Render:

This will create an HTML file named Output-File-name.html

@outdir

Defines the filepath to place the rendered HTML file.

NOTE: It is recommended to use an absolute filepath. This is because a relative filepath with start from the start_pointprovided to Ketchup and thus the correct path cannot be guaranteed.

Markup:

@outdir
/Users/user1/Documents/Ketchup-Docs

Render:

This will save the rendered HTML in a file at /Users/user1/Documents/Ketchup-Docs.

@byline

Any information that pertains to the authorship, ownership, or relationship of a section should be placed in a @bylinetag. This is a multi-line tag, meaning that each line will stay on its own line.

Markup:

@byline
Project Awesome v1.3.76
Charlie Koch - January 25, 2016

Render:

• Project Awesome v1.3.76
• Charlie Koch - January 25, 2016

@imports

Any modules or other code that is needed for this code to work (e.g. Java import, or C/C++ include, or HTML <link>or <script>tags). This is a multi-line tag, meaning that each line will stay on its own line.

Markup:

@imports
import os, sys
from module.another_module.file import MyClass, BetterClass
from module.different_module.file2 import Class2

Render:

Imports:

• import os, sys
• from module.another_module.file import MyClass, BetterClass
• from module.different_module.file2 import Class2

@class

Marks the following line(s) as the header of a class. This is a single-line tag, meaning that multiple lines will be concatenated into a single line.

This tag also creates an entry in the navigation sidebar.

NOTE: Inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag.

Markup:

@class
public GreatObject extends AnotherObject
                        implements AnInterface

Render:

public GreatObject extends AnotherObject implements AnInterface

@method

Marks the following line(s) as the header of a function or method. This is a single-line tag, meaning that multiple lines will be concatenated into a single line.

This tag also creates an entry in the navigation sidebar.

NOTE: Inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag.

Markup:

@method
def prepareLaunch(power, payload,
                    vector1, vector2,
                    spaceship, fuel_type)

Render:

def prepareLaunch(power, payload, vector1, vector2, spaceship, fuel)

@deflist

Creates a table with names and their descriptions. Each line is a row of the table in the format: def_name: Description of the definition . The def_namesection ignores all markup. The description allows inline markup.

The @attributes, @params, @constants, and @exceptionstags do the same formatting with special headers attached.

Markup:

@deflist
definition: this is a definition
def2: this is another def
whoa: this is cool

@attributes
str: The string to search
chars: Number of characters to search
variable_name: Description

@constants
MAX_RETRIES: Maximum number of retries to
             attempt before quitting
TIMEOUT: Time in seconds before the communication should end
SUCCESS_STRING: The string that prints if successful

@params
start_time: Time when this function started
end_time: Time when this function should end
filepath: Where this function should place the output

@exceptions
DataAccessError: database access error
BusinessLogicError: when something violates the rules

Render:

• definition: this is a definition
• def2: this is another def
• whoa: this is cool

Attributes:

• str: The string to search
• chars: Number of characters to search
• variable_name: Description

Constants:

• MAX_RETRIES: Maximum number of retries to attempt before quitting
• TIMEOUT: Time in seconds before the communication should end
• SUCCESS_STRING: The string that prints if successful

Parameters:

• start_time: Time when this function started
• end_time: Time when this function should end
• filepath: Where this function should place the output

Exceptions:

• DataAccessError: database access error
• BusinessLogicError: when something violates the rules

@return

A small section that details the return value of a method or function.

This is a single-line tag, meaning that multiple lines will be concatenated into a single line.

Markup:

@return
A small integer, but not too small. But just right.
Ask Goldilocks about it...

Render:

Returns: A small integer, but not too small. But just right. Ask Goldilocks about it...

@h1, @h2, @h3, @h4

Standard wiki-like header tags. The smaller the number, the larger the text.

Header sizes 1 and 2 ( @h1and @h2) also create an entry in the navigation sidebar.

Headers are a special tag which can also be used at the bgeinning of line, rather than on the line above.

NOTE: Inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag.

Markup:

@h1
Header 1

@h1 Header 1

@h2
Header 2

@h2 Header 2

@h3
Header 3

@h3 Header 3

@h4
Header 4

@h4 Header 4

Render:

Header 1

Header 1

Header 2

Header 2

Header 3

Header 3

Header 4

Header 4

Headers 1 and 2 ( @h1and @h2) can also be defined by using blank lines above them. 3 blank lines makes a Header 1, and 2 blank lines makes a Header 2.

NOTE: When using blank lines to create a header, you cannot place 1 Header tag directly beneath another. There must be some text or other tag below the header before defining the next one.

This is a paragraph.



Header 1

Text here.


Header 2

More text.

Render:

This is a paragraph.

Header 1

Text here.

Header 2

More text.

@table

A simple table element. Because Ketchup can't nest tags, you cannot use any tags inside the table. However, inline markup still works.

Each line is a row of the table. Each column is separated by a pipe ( |), but there are no pipes on the ends of the row. The first row is the header row. The next row is a row of at least 3 hyphens ( ---) to mark the end of the header. Each row after that is a simple row of the table.

Markup:

@table
Column 1     | Column 2 | Column 3
-----------------------------------------
Data in here | more     |
             | Stuff    | _More_ data in here!
/Data?       |          | *Even more!*

Render:

Column 1	Column 2	Column 3
Data in here	more
	Stuff	More data in here!
Data?		Even more!

@br

A sort-of line break (hence the "br") that provides extra whitespace between elements.

Markup:

Section

Another section

This is a section@with an inline break.
@br
And this a line break!

Render:

Section

Another section

This is a section
with an inline break.

And this a line break!

@hr ___

A horizontal rule, useful for separating sections to improve readability. An alternate markup for the horizontal rule is 3 underscores ( ___) though anything more than 3 will work.

Markup:

Using the /\@hr tag
@hr
Using the /___ markup
___
Using a longer underscore markup
____________________________

Render:

Using the @hrtag

---

Using the ___markup

---

Using a longer underscore markup

---

@codeblock

Since the inline markup for codeand codelineonly works on a single line and doesn't preserve whitespace, this tag provides exactly than for larger sectiosn of code. Because of this, it requires a second tag at the end of the block: @codeblockend.

NOTE: As with all code markup, inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag.

Markup:

@codeblock
There's code in here.
    Lots of code.
        So much code!

    For real, this is crazy.
@codeblockend

Render:

There's code in here.
    Lots of code.
        So much code!

    For real, this is crazy.

@literal

Similar to the codeblock, but still renders the text in regular section rather than monspace. Usually HTML will collapse all whitespace into a single space character, so keep that in mind when using this tag. It's mainly for entering large sections of text that may contain many characters and tags that are used by Ketchup. Can also be used to insert HTML or other markup languages in a Ketchup document.

Markup:

@literal
This is a literal
@br

There's some crazy /stuff _in this tag_
but Ketchup *won't render any of it*.
<div style="border: 1px solid black;background-color:green;width:20rem;">This is a div</div>

# List
## Numbered list
&#64;literalend

Render:

This is a literal @br

There's some crazy /stuff in this tag but Ketchup won't render any of it.

This is a div

List

Numbered list

@note

Inserts a special note section that can used to bring a specific section to the reader's attention or add a significant footnote. The italic inline markup does appear to change the style of the text since this tag makes text italic by default.

This is a single-line tag, meaning that multiple lines will be concatenated into a single line.

Markup:

@note
You must be careful. _*Never*_ underestimate
the power of the /-Dark Side-/.

Render:

NOTE: You must be careful. Never underestimate the power of the Dark Side.