Re: Finalized NSE Documentation System

["Patrick Donnelly" <batrick.donnelly () gmail com>]

Hi Kris,

On Wed, Jul 2, 2008 at 4:56 PM, Kris Katterjohn <katterjohn () 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