G'MIC Gimp Help Pages: Help Page Template - GreycLab/gmic-community GitHub Wiki

Note: This page can be copied and pasted into a new help form the first line following this paragraph (Beginning with the second occurrence of "**Note**" to the end) to serve as a general template for Help Page design. This page's content, aside from section headers, is meant to be replaced with information relevant to the script in question.

Most Important Thing First
Remember when writing a help file the following assumptions apply:

  1. This is the first time the reader has ever used The GIMP.
  2. This is the first time the reader has ever used G'MIC.
  3. This reader is not a graphic artist, programmer, or artist.
  4. This reader is not a native English speaker.

By keeping the above assumptions in mind, and using language and terminology correctly, these will become the "de-facto" help pages which our users turn to. If the documents are too technical, or fail to link to the glossary where technical information must be used, many readers will become lost, and may turn away from here, or worse yet, G'MIC. These are not intended to be "Developer Docs", but layman's help files, like those You would expect to see in a simple text editor's help. Educate the reader, but gently. Don't overwhelm them!

The page's name should be in the form:
G'MIC GIMP Help: <author's name>'s <script menu name capitalized as appropriate> (<script name as used in a G'MIC GIMP command string>).
Example:
G'MIC GIMP Help: garagecoder's Wiremap (gcd_wiremap)

Delete this line and all text above it.
Note: General information applicable to all help files can be found at the end of this page.

Overview

This section should contain a brief summary of what the script's intended function is. There should be no non-layman-terminology used here unless absolutely required. If such terminology is used, make sure the term is explained in layman's-terms in the glossary page.

This image should be replaced with an image showing the controls for the script, as it appears in the Gimp's G'MIC plugin. The image should be present in the git repository for the GMIC-GIMP plugin, or in some other location which is permanent. Locations such as tumblr, imageshack, and other such sites (including deviantart) can be cleaned out periodically, or the account in question closed. This would cause the loss of the image in question. The image link must appear on a line of it's own, with a blank line both before, and after it.

"Picture of script option controls."

The Controls

This section should contain a numbered list, with one entry per control displayed by the plugin. Each entry should be formatted according to the data it provides. The "Entry Name" (first bold characters of any entry), should match the name of the control in question, as it is shown in the GUI. The entries below are the proper formats, with the "entry name" in this case indicating the nature of control it should be used with. One or more "Tip:" entries can be associated with any control.

  1. Numeric Data -- A field of this type is one which accepts input from a slider, spin-control, or text entry; where said input is expected to be numeric. Remember that this line, and all subsequent lines in a given control's entry (except for the last one) need to end with two blank spaces before You hit Enter/Return. If they do not, proper vertical spacing will not occur.
    Default: This should show the Default value displayed by the GUI, or used by the script. Don't forget two blank spaces at the end of the line!
    Range: 4 - 400 (0.1 - 1509.0) This should represent the range of values which the script can receive for this control, and function properly. Two forms are shown, one for floating point values, and one for integers, one of them should be used, not both, and the parenthesis are omitted. Don't forget two blank spaces at the end of the line!
    TIP: Information which could help the end user, either in script writing, or in GUI usage of the script, involving this control/parameter should be displayed as a tip. Each piece of specific information should have it's own tip, and should be short and succinct, without being to technical. Don't forget two blank spaces at the end of the line only if there are more tips to follow!

  2. Pick List -- This type of entry should be used anywhere the user is prompted for a choice of "one among many". The first part of this section should contain an overall description of what is being chosen in the selection. The sections final characters should be
    ": " (without the quotes), to ensure proper vertical formatting. The sections which follow this one do not need to reflect the order of the choices in the display, but need to begin with the default selection, which is so indicated as shown below. :
    Choice One -- The default setting. A brief description of what this choice would mean for the user. Do not forget to end this section with two spaces on the end of the last line.
    Choice Two -- A brief description of what this choice would mean for the user. Do not forget to end this section with two spaces on the end of the last line.
    Choice Three -- A brief description of what this choice would mean for the user. Do not forget to end this section with two spaces on the end of the last line.
    etc, etc, etc -- A brief description of what this choice would mean for the user. Do not forget to end this section with two spaces on the end of the last line, if more lines are to follow, but not on the final line!

Input Details

If the script itself behaves differently depending on Input modes defined in the plugin itself, this section must exist. This section may or may not have a general introduction, depending on the script. Individual headers, of level 3 type, should exist for behaviour being detailed. Said sections should include the input method appropriate to what is being explained, and which output methods can be used with it. The samples below, Black and White Modes and Color Modes is taken from garagecoder's Wiremap script help page and are here as samples. They should be removed.

Black and White Modes

The script processes a single layer in the "Black and White" "Output" modes. It uses oversampling by reducing the image to a width equal to the "Segments" value, and uses the values of the pixels on this temporary layer, to define it's grid. While it will work on any RGB layer, it is meant to function on a Pseudo Greyscale layer, where every pixel's Red Green and Blue value are the same. These "Heightmaps" as they are often called provide the truest results.
Valid Input/Output Settings:
Input: Any except None
Output: Any

Color Modes

The script process it's grid the same way in this mode as it does in in the Black and White modes, until it comes to coloring them. At that point it draws it's colorization data from a layer BELOW the source layer in the layer stack. This second layer must be visible to be used by the plugin, and thus by the script.
Valid Input/Output Settings:
Input: Any which provide the active layer and the layer below
Output: Any

##Output Details This section is identical in form and function to the Input Details section defined above, except that it applies to Output modes of G'MIC GIMP.

Command String

This section needs no text at all, other than the string which should be used in a plugin to access this command, and the warning shown in the sample below (4 lines total). This command string appears in pseudo code form, similar to a C or C++ declaration. Remember to keep the two blank spaces on the end of the warning line, and the "representing..." line, for proper vertical placement.Example:

G'MIC-GIMP command lines may not contain any spaces except for the one right after the script name!
gcd_wireframe int,int,float,float,int
representing ...,
gcd_wireframe segments, depth, smoothness, distance, output

General Help Details

The final link, to other scripts by the same author, should have the URL modified as appropriate. All other links should remain intact as-is. This text, and the empty line, should be removed. Only the links below should remain.

Glossary  Help Home Page
Script Help Sorted by Menu Name   Script Help Sorted by Internal Name
Script Help Sorted by Author   Script Help for This Author's Scripts