Nmap Development mailing list archives
Finalized NSE Documentation System
From: "Patrick Donnelly" <batrick.donnelly () gmail com>
Date: Fri, 27 Jun 2008 22:25:30 -0600
Hey Folks, There have been some changes to how the NSE Documentation System works since I last posted (see: http://seclists.org/nmap-dev/2008/q2/0739.html). The doc system is now built on LuaDoc. It has one dependency, LuaFileSystem, which can be downloaded here: http://luaforge.net/frs/?group_id=66 The current version of NSEDoc can be seen in my branch at nmap-exp/patrick/nsedoc/src There are three directories in this path of interest: nselib and scripts (some scripts from /nmap/scripts|nselib but with the new documentation), as well as docs which holds the current output (documentation) for the files in those directores. ==== FILE FORMAT AND TAGS ==== The documentation for a file should be in the following format: <file> --- File summary in one sentence. Continued description. -- continued description -- @tag description -- above tags continued description -- @tag2 description --- Function description. -- continued... --@tag description function dostuff() end </file> A file's summary uses the first sentence in the description for use as a "short" synopsis of its purpose in the index html document. The tags are documented by LuaDoc here: http://luadoc.luaforge.net/manual.html#tags In addition to those tags are "args", "summary", and "output". Documented below: -- @args These are the args given to the file through --script-args switch. The first alphanumeric word (literally matching ([%w%p]+) in Lua) is used as the name for the argument, the rest is its description. This tag is only used for the file comment. -- @summary This is the summary which can be used instead of what normally is the first sentence of the File's description. -- @output This is used to show the typical output of a script. Use "\n" to force a line break where you please. ==== USE ==== The typical method for producing documentation is: "./nsedoc.lua -d docs scripts nselib". All the command line switches are documented here: http://luadoc.luaforge.net/manual.html#options A point of divergence from LuaDoc is the standard NSE fields, such as "id" and "description", are used in the documentation. If there is no commented file description, then the NSE field is used. The same is true for using the author field if the author tag in the file comment is missing. ==== HOW IT WORKS ==== The system is well documented by LuaDoc here: http://luadoc.luaforge.net/architecture.html#architecture I have substituted a parser for NSE that is mostly equivalent to LuaDoc's parser except it acquires NSE fields and makes substitutions. The documentation framework in nsedoc/src/luadoc/doclet/html/* follow use a form of tags that allow you to interweave Lua code with the documentation itself. Lua code is placed in <% code %> tags. Lua code in <%= %> tags are evaluated as a statement and written to the file. All other information in the document is placed in an output function a a string. An example: <head> <title><% =file_doc.title %></title> </head> <%if file_doc.name:sub(-4) == ".nse" then %> Script <% else %> File <% end %> becomes f:write("<head> <title>") f:write(file_doc.title) f:write("</title> </head>") if file_doc.name:sub(-4) == ".nse" then f:write("Script") else f:write("File") end You can see various looping and control constructs can influence how a file is constructed. ==== Please post any questions or comments here. Cheers, -- -Patrick Donnelly "One of the lessons of history is that nothing is often a good thing to do and always a clever thing to say." -Will Durant _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org
Current thread:
- Finalized NSE Documentation System Patrick Donnelly (Jun 27)