Mod manual page

What is the manual page for mods?

Manual page for mods is a file consisting of documentation for the mod or for a specific part of the mod. They clarify how to use the mod, what are the commands, and so on. Sometimes, they may include release notes with the mod.

The file format didn't have so many changes from the 0.0.6.0's .ksman format, but the file extension is changed to .man format, along with the other changes that the modern format has seen.

Feature	.ksman	.man
Comments	~~-	~~-
Manual page start	(*MAN START*)	(*MAN START*)
Title & Revision	-TITLE:/-REVISION:	-TITLE:/-REVISION:
Manual layout ver.	-KSLAYOUT:0.0.5.9-OR-ABOVE	(none)
Body start	-BODY START-	-BODY START-
Body end	-BODY END-	-BODY END-
Placeholders	(none)	Supported
Color configuration per-word	-COLOR CONFIGURATION-	(none)
Color configuration per-word end	-COLOR CONFIG END-	(none)
Sections (SE1, SE2, SE3, ...)	-SECTIONS-	(none)
Sections end	-SECTIONS END-	(none)
TODOs	~~- TODO:	~~- TODO:

To make the comparison clearer, compare the two examples which are shown below:

Mod documentation example in .man format

(*MAN START*)

~~- This man file is a demonstration about how it works in full scale. It supports placeholders.
-TITLE:Simplistic manual page for mod
-REVISION:1.0
~~- TODO: Needs work

-BODY START-
This is a body for the simplistic manual page for your mod. You can use placeholders in it.

<f:4>Hello world! in color!<f:reset>

~~- All comments are ignored by the parser.
-BODY END-

Mod documentation example in .ksman format

(*MAN START*)

~~- This man file is a demonstration about how it works in full scale. It doesn't support placeholders.
-TITLE:Simplistic manual page for mod
-REVISION:1.0
-KSLAYOUT:0.0.5.9-OR-ABOVE
~~- TODO: Needs work

-BODY START-
Mod Manual

This is a body for the simplistic manual page for your mod. You can use placeholders in it.

Hello world! in color!

~~- All comments are ignored by the parser.
-BODY END-

-COLOR CONFIGURATION-
Hello world! in color!=>Green
-COLOR CONFIG END-

-SECTIONS-
Mod manual=>SE1
-SECTIONS END-

Format

Open your favorite text editor and write the (*MAN START*) tag, because every single manual page must contain this tag in the first line. Then, write the below specifiers to let Kernel Simulator know the title and the version of your manual page.

Title and Revision

The title can be the manual page title in one line. The revision can be either SemVer2-compliant, date and time, build number, or just the mod version.

-TITLE:Your manual title
-REVISION:1.0

Body

The contents of the manual page must be surrounded by the -BODY START- and the -BODY END- tags to signify that they are actually shown in the mod manual viewer. Take a look at the example below to show what was meant to be:

-BODY START-
This is a body for the simplistic manual page for your mod. You can use placeholders in it.
-BODY END-

Comments

Of course, all the comments are ignored and are not shown, whether it's on the body or not. They are to clarify some points on the developer's side. These comments start with the ~~- tag and the text follows it. If you want to specify a TODO to indicate that the work isn't finished yet, you may do so by writing ~~- TODO: . These tasks are shown in the kernel prior to displaying the body.

Comments outside body

~~- All comments are ignored by the parser.
~~- TODO: Needs work

Comments inside body

-BODY START-
~~- All comments in body are ignored by the parser.
~~- TODO: Clarify point 2
-BODY END-

Personalization

You can even use the placeholders to personalize your manual page. Consult the Placeholders page for more information about how to use them in manual pages.

-BODY START-
<f:4>Hello world! in color!<f:reset>
-BODY END-

Installation

To install the manual page to your mod, create a folder in KSMods the mod DLL name with .manual appended to the end (for example, mod.dll.manual). Put all your .man files inside the folder (for example, manual.man). The structure should look like this:

KSMods/
  |
  +-> mod.dll
  +-> mod.dll.manual/
        |
        +-> manual.man

Run Kernel Simulator, log-in to your account, and write modman <manual title>. If your manual title is enclosed in spaces, you may surround the title with the double quotes, for example, modman "First Mod Manual".