nsedoc observations

[jah <jah () zadkiel plus com>]

Hello,

I'm liking nsedoc a lot, it's very cool.  It doesn't take a great deal
of work to document a script, especially if you do it as you go along,
and the result looks good.  Having said that, there seems to be a few
quirks/kinks in the HTML produced - maybe by design, maybe it's just
windows (or me), I'm not sure - and so here's some observations I've made.

First off, the User Summary.  This is taken from the scripts description
field if it exists, otherwise it seems to come from comments in the file
not associated with a function, table etc.  Whois.nse has got a fairly
long description in which I've laid out some usage examples and how
different --script-args affect the scripts behaviour.  In this instance,
I decided not to use the available @args tag because whois only uses one
argument, but allows it to have a variety of different values and the
layout in @args is a little inflexible for this case.
Formatting the description field however seems not to be possible: "\n"
is printed as is and doesn't cause a page break and whilst whitespace is
preserved in the final markup, it's collapsed upon rendering (which
isn't really a bad thing).
I sacked the description field and instead used a file comment which
allowed me to embed HTML tags into the script and affect the formatting
in the resulting document.
That's cool, but it makes the comments in the script a bit untidy, even
with liberal use of whitespace.
And of course, allowing just any old HTML in a script makes for some
interesting fun.  I've XSSed and rickrolled myself silly!
I've pasted my custom summary at the end of this email to show what I
did to get a nice looking HTML layout.

Second, tables.  Can't seem to get documentation to show for any tables
I've documented.  This may just be me and a working example would be a
great help.

The @usage tag displays for functions, but not for the script itself and
I think that this would be great to have.

On the HTML index page, in the side-bar list of files and on it's own
page the script name has a zero appended to the displayed filename:
scripts/whois.nse0.  I bet this is a windows thing, but I haven't looked
at the issue in any detail.

It would be great to use the @see tag inline in a comment rather than a
separate tag only and also to combine several @see values into a single
line rather than each on a new line.  Examples here
<http://luadoc.luaforge.net/api/files/luadoc/taglet/standard.html#file>
and here <http://luadoc.luaforge.net/api/files/luadoc/core.html#main>.

\n also didn't work for me in the @output tag.

Slashes appear in the document if, say, the description field uses "\"
to allow a multi-line string.

I can't work out whether I've misunderstood their usage or whether <% %>
and <% = %> just don't work.  I tried various things including just
trying to get the script id to be written to the html.  This wasn't a
serious need, I was trying to hide an html <script> tag in the lua code
and then have it output in the doc.  I failed.

Bloody w3.org validation icons seem to delay page loading by quite a
bit, quite often.  I think Fyodor mentioned the possibility of getting
rid of them and I'd like to +1 that!

Kris mentioned displaying required modules and I think this would be a
good idea too.

There's a @release tag, but this doesn't seem to output any html - this
actually seems to be by design so I mention it only for the sake of
mentioning it.


Overall, nsedoc is looking great, but perhaps much of the focus is on
documenting the functions in a script (which obviously is great) and not
quite enough on documenting the usage of scripts for the benefit of users.

I reckon that if \n and \t worked in the description field, in @output
and in any other script comments this would help alot.  We have @args
and that's good, but if @usage worked too, that would be a real
benefit.  I'd like to see something like a @notes tag to allow for extra
information about a script - warnings, tips etc.  Perhaps a @changelog tag?

Anyone else had a chance to play with nsedoc yet?


Regards,

jah



---
--                   Queries the WHOIS services of Regional Internet
Registries and attempts to retrieve information about the most specific
--                   IP Address Assignment containing the Target IP address.
-- <br /><br />
--                   The fields displayed contain information about the
assignment and the responsible organisation or customer using the
--                   assignment. With output verbosity, information
about Persons or Roles associated with the assignment will also
--                   be displayed.  Only one query will be sent for
multiple Targets in the same assignment and only one Host Script Result
--                   will display the obtained information - the
remaining Host Script Results will display a pointer to the information.
-- </p>
-- <h2>          Usage
-- </h2><p>
--                   nmap target --script whois
-- <br /><br />
--                   The default behaviour is to utilise a locally
cached copy of an IANA hosted assignments file to determine which Whois
service
--                   to query for a given target.  If this file is
unavailable then services defined in the whoisdb_default_order table will
--                   instead be queried, in turn, until redirected to
the desired record.
-- <br /><br />
--                  The default behaviour may be overridden by supplying
the script argument "whodb" thus:
-- <br />        nmap target --script whois --script-args whodb=nofile
-- <br />        nmap target --script whois --script-args
whois={whodb=nofile}
-- <br /><br />
--                  The default behaviour may also be overridden by
supplying a custom whoisdb_default_order with the script argument "whodb"
--                  thus:
-- <br />        nmap target --script whois --script-args
whodb=arin+ripe+afrinic
-- <br />        nmap target --script whois --script-args
whois={whodb=apnic*jpnic}
-- <br />        (N.B. commas or semi-colons should not be used to
delimit services)
-- <br /><br />
--                  Finally, the argument "nofollow" prevents the
following of redirects and instead returns the first record obtained:
-- <br />        nmap target --script whois --script-args whodb=nofollow
-- <br />        This may be used in conjunction with a single service
to query:
-- <br />        nmap target --script whois --script-args
whodb=nofollow+ripe
--
-- @output
--                                   Host script results:
-- <br />|&nbsp;&nbsp;    Whois: Record found at whois.arin.net
-- <br />|&nbsp;&nbsp;    netrange: 64.13.134.0 - 64.13.134.63
-- <br />|&nbsp;&nbsp;    netname: NET-64-13-143-0-26
-- <br />|&nbsp;&nbsp;    orgname: Titan Networks
-- <br />|&nbsp;&nbsp;    orgid: INSEC
-- <br />|_                      country: US stateprov: CA
-- </p>


id = "Whois"
<snip>


_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://SecLists.Org