Re: Finalized NSE Documentation System

Hi Kris,

On Wed, Jul 2, 2008 at 4:56 PM, Kris Katterjohn <katterjohn_at_gmail.com> wrote:
>> 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.
>>
>
> But when this is moved to /nmap, it will take the scripts and libraries
> straight from /nmap/scripts and /nmap/nselib, right?

The current plan is NSEDoc will be packaged separately from Nmap.
Developers should be able to download it to create documentation. Nmap
will ship with documentation already made.

>> 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.
>
> Looking up %p, I see that that's for any punctuation characters, but what
> about spaces? What if the argument has a space in it because the user wants
> to acknowledge a scoped-down argument in the fashion you do here[1]? Probably
> not common at all, but it hit me initially.

That's an interesting point. Perhaps we should require the "argument"
should be surrounded by quotes, otherwise use the first
alphanumeric-punctuated word?

> Maybe allow quotation marks around the argument name?
>
>> ==== 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
>>
>
> Where is this nsedoc.lua located?

/nmap-exp/patrick/nsedoc/src/nsedoc.lua

>> ==== 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.
>>
>
> Can you add the require statements to the parser? I didn't notice these
> anywhere looking at the html docs.
>
> In the future I can see people having their own libraries and scripts, and
> having the documentation on their website. Since required libraries may or
> may not be shipped with Nmap proper, this can make it easy to see the
> requirements.
>
> Plus I'm the curious type ;)

That sounds like a good idea. I'll see about adding that.

>>
>> Please post any questions or comments here.
>>
>
> So, from reading this[2], I take it the only way that something is added to
> the docs is if it starts with those three minuses? Because I was thinking
> that the doc system can use modifiers like Ruby's RDoc :startdoc:, :stopdoc:
> and :nodoc: . But if docs are *only* generated with the three minuses, then
> it probably doesn't matter. I'm just wondering about any gotchas :)

Documentation system uses the three minuses as a start. No gotchas :)

Thanks,

-- 
-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