Re: nsedoc observations

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

Hi Jah,

On Thu, Aug 14, 2008 at 10:04 AM, jah <jah () zadkiel plus com> wrote:
> If the description field contains a succinct description and it's necessary
> to expand upon that description with usage notes then a script would require
> the use of the @usage tag or similar.  Otherwise any file comment not part
> of tags would override the description field.  Therefore the short content
> of the description field would not be seen in the document and its content
> would need to be duplicated in the file comments.  That or place both the
> short description and extended information in the file comments and use
> decription="" or description=true in the script to satisfy the requirement
> for the description field.

I have added a usage section to a script's output. The usage tag, as I
have been using it, is for demonstrating using the script
(particularly args) from the command line.

I understand how it is undesirable for the description in the file
comment to duplicate parts or all of the description NSE field, but I
really see no other way around this. Combining them could just lead to
confusion. The reason for the description field's continued presence
is as a last ditch replacement for a script's description and for use
in the future in add ons like Zenmap. I'm completely open to clear
design strategies to keep the description field's use in NSEDoc. Some
have suggested that it be used as a Summary for the script (but
where?). I haven't found a good answer for this.

> Given that it's now possible to do some formatting in the description field
> (\n), I think it would be OK to prefer this for the User Summary over file
> comments - as before your change.  The addition of the @usage tag would
> enable documenters to keep the description field short and sweet.

I'm sure in the future the doc system will have many other formating
constructs that will convolute the description. Suggesting they go in
the description NSE field is something I think we should avoid?

> In the whois.nse I recently submitted, I did actually use the @args tag in
> the end.  The layout wasn't as inflexible as I'd made out.  I just
> interspersed html tags.  I've now tried replacing the html with \n, but this
> doesn't currently work for @args.

I will put adding the '\n' on my todo list. Please point out any other
problems you encounter.

> Confirmed.  This is much better. \t would be useful too.  Can you make the
> parser accept strings that span multiple lines which are enclosed in [[ ]]
> as well as those that use end of line \
>
> description = "foo \
> bar"
>
> and
>
> description = [[
> foo
> bar
> ]]

This should already be possible. Please try this again and let me know
if it still doesn't work.

> See above discussion of description.  The @usage tag would indeed be a good
> place to put example commands as well as lay out different usages.

I have added this as I mentioned above.

> What I had in mind here is what I saw in those examples.  You could refer to
> another function/script/library in context with some comments rather than in
> a separate block.  Also, in addition to having a separate block with each
> @see value on a separate line in the resultant document, you could combine
> them onto a single line.
>
> inline with comments:
> This function is great, it's better than that other blokes (see foo).
>
> and
>
> separate block with all references on the same line:
> See  foo, bar
>
> and
>
> separate block with each reference on a new line.
> See
> foo - for all things foo.
> bar - when you want a drink.
>
> Perhaps this is something for the back-burner, pending more interest.

I'll put this on the back-burner ;)

> There's a bit of a problem with your latest version from
> svn://svn.insecure.org/nmap-exp/patrick/nsedoc and it manifests itself a
> Host and Port rules appearing before much of the other content in the
> documents.  See
> http://www.unm.edu/~batrick/nse/docs/files/scripts/anonFTP.html
> The header for the summary of functions table has gone AWOL too.

I'll also look into this.

Thanks Jah,

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