Home page logo
/

nmap-dev logo 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


  By Date           By Thread  

Current thread:
  • Finalized NSE Documentation System Patrick Donnelly (Jun 28)
[ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]
AlienVault