Table of Contents
LingoDoc
LingoDoc is a special formatting for comments in lingo scripts.
Here in the trac wiki a custom trac plugin is used to format these comments. The advantage is, that you do not need to change anything here in trac, if you update the description in your script. As soon as it is committed into the subversion repository, the changes to the comments are automatically reflected in the corresponding lingoDoc page. The disadvantage however is that although it appears in the wiki, it is not searchable via the trac search, as these lingoDoc pages are generated on the fly form the source file in the repository.
The format for the lingo comments follows simple rules: There are two lingoDoc items: the script abstract and the handler description
Script abstract
Everything at the beginning of a scriptmember until the first line, which is NOT a comment is treated as the script abstract. Every section is defined by being one single word with a colon as the first word of the line. There are no other rules. Section keywords can be choosen freely, the only rule is, that it is the first word of a line directly followed by a colon.
Handler description
Everything at the beginning of a handler (right after the handler definition => on handlerName params) is treated as handler description. It can only start at the same line where the handler is defined or the following line. As soon as there is more than one line between the handler definition and the first comment it is NOT a lingoDoc handler description. Handler descriptions follow the same section formatting rules as Script abstracts: Every first word of a comment line, followed directly by a colon is a section header.
As a convention I add only lingoDoc handler descriptions to public handlers, so that private handlers do not appear in the trac, but rather only the public handlers, which shall be used by other scripts. So it is more a public interface documentation, than a script documentation itself. Comments for the private handlers, which are meant as help to understand the script itself as opposed to its public interface) are rather ABOVE the handler definition line => BEFORE (outside of) the handler. So we can look up the public interface via lingoDoc in trac.
That's it for the lingo side of things (Use the HandlerMenu tool to insert templates for Script abstracts and Handler definitions ; find it under the menu item: "Utilities:Glossary")
Please note that wiki keywords are parsed in lingoDoc comments. So you can link to bugnumbers or other wiki pages from within you lingo comments. Sometimes that is unwanted, though. The escape character is ! or escape a block of text by enclosing it in {{{ your block of text here }}} a pair of 3 opening and 3 closing braces. Another special case are the "divider handlers" we use to subdivide our lingo handlermenu: if a handler starts with more than three underscores it is considered as divider and appears in lingoDoc as subheader in the handler index at the top.
Now that your script has lingoDoc-style comments and is in the subversion repository as text file (-> lingosource) it can be used in the trac wiki. To do so just create a new wiki page with a line to embed the trac plugin like: [[TracLingoDoc(Foo)]]
Trac Plugin Description
Parses the given repository document ( -> first parameter) for strings in a specific format, ingodoc and outputs the result to the current wiki page. It takes one mandatory item and two optional positional items. The mandatory item is the file path in the repository ( -> first parameter). The optional items are the CSS class of the generated heading and the CSS class of the div tag surrounding the included page. If the first positional item is missing, no heading will be generated. If the second is missing, no div will be generated.
Example:
[[TracLingoDoc(Foo)]] [[TracLingoDoc(Foo,headclass)]] [[TracLingoDoc(Foo,headclass,blockclass)]]
To make creation of lingoDoc pages easier there is a template for a lingoDoc page. Whenever you create a new wiki page you can choose from a dropdown menu to use the lingoDoc template for the new page. Now you simply need to complete the path to the repository file, which is the name of the script with an ".ls" extension in the folder "castlibXY" where XY is the number of the castlib.
In order to structurize the wiki pages, I would like to ask you to create your lingodoc wiki pages as sub wiki pages of the "lingo" directory, so they appear better structured on the Index page.
To do so just create the new page in a subdirectory. e.g. lingo/UtilityScripts/myNewScript.ls?
By now there are the following sub pages:
- Example (lingo/libraryScript/xmlParser)
